Repository navigation
ci(lint): ratcheted type-discipline gate (mutable collections, casts, guards, kwargs, suppressions) #30500
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
mateo-berri
merged 25 commits into
litellm_internal_staging
from
litellm_type_discipline_gate
Jun 16, 2026
Merged
ci(lint): ratcheted type-discipline gate (mutable collections, casts, guards, kwargs, suppressions) #30500
Changes from 10 commits
Commits
Show all changes
25 commits
Select commit
Hold shift + click to select a range
9f927b6
ci(lint): enforce type-discipline budget for casts and type guards
mateo-berri bcab7f5
ci(lint): enforce suppression-reason budgets and guard budgets agains…
mateo-berri 626a302
ci(lint): ban mutable collections in annotations and all mutable cons…
mateo-berri 7f64fa1
ci(lint): recommend pydantic at boundaries and add functional-refacto…
mateo-berri 0420802
style: make CLAUDE.md more concise
mateo-berri 957c30d
chore: update CLAUDE.md guidelines
mateo-berri 3851419
ci(lint): renumber mutable construction LIT009 -> LIT002 next to LIT001
mateo-berri 23e2aff
fix: numbering in CLAUDE.md
mateo-berri 5c18687
test(lint): test type-discipline checker, scope LIT007 to return types
mateo-berri 19c8afa
fix(lint): best-effort worktree teardown so cleanup can't mask the re…
mateo-berri 5f5f8bb
fix(lint): ratchet fails loudly on an unresolvable base; drop dead ch…
mateo-berri 7d58e15
fix(lint): degrade malformed source to LIT000 instead of crashing the…
mateo-berri 827b4ba
perf(lint): skip the base worktree scan when no rule is over its ceiling
mateo-berri 0ac778b
fix(lint): exempt .dict()/.list()/.set() method calls from LIT002
mateo-berri 45f64ab
Merge litellm_internal_staging into litellm_type_discipline_gate
mateo-berri 127de03
chore(lint): bump basedpyright ceilings to absorb staging base drift
mateo-berri f3ca65c
fix(lint): ratchet guard watches every budget file, not just two
mateo-berri ded1c54
Merge branch 'litellm_internal_staging' into litellm_type_discipline_…
mateo-berri a19f4e3
fix: add a lot more slack
mateo-berri ad6f016
fix(lint): restore LIT003 frozen slack to 0
mateo-berri 83d9287
fix(lint): restore documented slack 10 for the buffered LIT rules
mateo-berri e0c33a3
fix(lint): ratchet LIT003 baseline down to its actual count
mateo-berri 8efee05
fix: increase slack
mateo-berri ad80477
fix: increase slack
mateo-berri 73620e6
docs(lint): align gate docstring with buffered LIT003/LIT004 slack
mateo-berri File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| #!/usr/bin/env python3 | ||
| """Non-gating ratchet guard: budget ceilings may only fall, never rise. | ||
|
|
||
| The `*-budget.json` files (ruff-strict-budget.json, type-discipline-budget.json) are | ||
| one-way ratchets: each rule's ceiling is `baseline + slack`, and the whole point is | ||
| to drive that number DOWN over time. This check compares every budget file against | ||
| its own content at the merge-base with the target branch and fails (exits 1, red) if: | ||
|
|
||
| * a rule's ceiling went up, | ||
| * a rule was dropped from a budget (its ceiling effectively became infinite), or | ||
| * an entire budget file was deleted. | ||
|
|
||
| New rules and lowered/equal ceilings are fine. | ||
|
|
||
| This is deliberately NOT a gating check. It should turn the run red so that a | ||
| loosening is impossible to miss in review, but it must stay OUT of the | ||
| branch-protection required-checks list: a justified bump (e.g. banning a new API, | ||
| which mechanically raises a baseline) can then still be merged by a human who has | ||
| seen the red and accepted it. | ||
|
|
||
| Usage: | ||
| python scripts/budget_ratchet_check.py [--base REF] [budget.json ...] | ||
|
|
||
| Stdlib only. | ||
| """ | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import argparse | ||
| import json | ||
| import subprocess | ||
| import sys | ||
| from pathlib import Path | ||
| from typing import NamedTuple | ||
|
|
||
| REPO_ROOT = Path(__file__).resolve().parent.parent | ||
| DEFAULT_BASE = "origin/litellm_internal_staging" | ||
| DEFAULT_BUDGETS: tuple[str, ...] = ( | ||
| "ruff-strict-budget.json", | ||
| "type-discipline-budget.json", | ||
| ) | ||
|
|
||
|
|
||
| class Regression(NamedTuple): | ||
| budget: str | ||
| rule: str | ||
| detail: str | ||
|
|
||
|
|
||
| def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]: | ||
| return subprocess.run(cmd, cwd=REPO_ROOT, capture_output=True, text=True) | ||
|
|
||
|
|
||
| def _merge_base(base: str) -> str: | ||
| """The common ancestor of `base` and HEAD, so unrelated base drift is ignored.""" | ||
| proc = _run(["git", "merge-base", base, "HEAD"]) | ||
| return proc.stdout.strip() or base | ||
|
|
||
|
|
||
| def _load_head(rel: str) -> dict | None: | ||
| path = REPO_ROOT / rel | ||
| if not path.exists(): | ||
| return None | ||
| return json.loads(path.read_text()) | ||
|
|
||
|
|
||
| def _load_base(rel: str, ref: str) -> dict | None: | ||
| """Budget content at `ref`, or None when the file did not exist there.""" | ||
| proc = _run(["git", "show", f"{ref}:{rel}"]) | ||
| if proc.returncode != 0: | ||
| return None | ||
| return json.loads(proc.stdout) | ||
|
|
||
|
|
||
| def _caps(budget: dict) -> dict[str, int]: | ||
| """Map each rule to its ceiling (baseline + slack); skip malformed specs.""" | ||
| caps: dict[str, int] = {} | ||
| for rule, spec in budget.items(): | ||
| if isinstance(spec, dict): | ||
| caps[rule] = int(spec.get("baseline", 0)) + int(spec.get("slack", 0)) | ||
| return caps | ||
|
|
||
|
|
||
| def regressions_for(rel: str, base: dict | None, head: dict | None) -> list[Regression]: | ||
| if base is None: | ||
| return [] # new budget file: nothing to ratchet against yet | ||
| if head is None: | ||
| return [Regression(rel, "*", "budget file was deleted (every ceiling removed)")] | ||
|
|
||
| base_caps = _caps(base) | ||
| head_caps = _caps(head) | ||
| out: list[Regression] = [] | ||
| for rule, base_cap in sorted(base_caps.items()): | ||
| if rule not in head_caps: | ||
| out.append(Regression(rel, rule, f"rule dropped (ceiling {base_cap} -> removed)")) | ||
| elif head_caps[rule] > base_cap: | ||
| out.append(Regression(rel, rule, f"ceiling raised {base_cap} -> {head_caps[rule]}")) | ||
| return out | ||
|
|
||
|
|
||
| def main() -> int: | ||
| parser = argparse.ArgumentParser(description=__doc__) | ||
| parser.add_argument("--base", default=DEFAULT_BASE) | ||
| parser.add_argument("budgets", nargs="*", help="budget files to check") | ||
| args = parser.parse_args() | ||
| budgets = args.budgets or list(DEFAULT_BUDGETS) | ||
|
|
||
| ref = _merge_base(args.base) | ||
| regressions: list[Regression] = [] | ||
| checked: list[str] = [] | ||
| for rel in budgets: | ||
| base = _load_base(rel, ref) | ||
| head = _load_head(rel) | ||
| if base is None and head is None: | ||
| continue | ||
| if base is None: | ||
| print(f"skip {rel}: new file (no base at {args.base} to ratchet against)") | ||
| continue | ||
| checked.append(rel) | ||
| regressions.extend(regressions_for(rel, base, head)) | ||
|
|
||
| if regressions: | ||
| print(f"FAIL: budget ceiling(s) loosened vs base {args.base} (merge-base {ref[:12]}):") | ||
| for reg in regressions: | ||
| print(f" {reg.budget} {reg.rule}: {reg.detail}") | ||
| print( | ||
| "Budgets are one-way ratchets and may only go down or stay flat. This " | ||
| "check is non-gating: if the increase is justified (e.g. a newly banned " | ||
| "API), a human can merge over the red after acknowledging it." | ||
| ) | ||
| return 1 | ||
|
|
||
| suffix = f" ({', '.join(checked)})" if checked else "" | ||
| print(f"OK: no budget ceiling increased vs base {args.base}{suffix}") | ||
| return 0 | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| raise SystemExit(main()) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.