ci(lint): ratcheted type-discipline gate (mutable collections, casts, guards, kwargs, suppressions)

[mateo-berri]

Summary

Adds a ratcheted CI gate that enforces type-discipline rules Ruff can't express per-call-site, layered on top of the existing ruff-strict budget infrastructure. Nothing existing is forced to change: the gate freezes today's counts as a baseline and fails only on additions beyond baseline + slack, so a change is blamed for the violations it adds, never for drift already in the base. Re-baseline with --update to ratchet a ceiling down as violations are removed.

Two enforcement layers:

1. Import-level freeze (Ruff banned-api / TID251). cast, TypeGuard, and TypeIs (from both typing and typing_extensions) are added to flake8-tidy-imports.banned-api in ruff-strict.toml (the mutable-collection typing aliases were already banned there). TID251 is one rule code covering all banned-api matches, so the ruff-strict-budget.json baseline is bumped 2404 → 2664 to absorb the pre-existing usages these new entries match.
2. Per-call-site granularity (custom AST checker, scripts/check_type_discipline.py). A stdlib-only checker emitting the LIT### rules below, each with its own baseline/slack in type-discipline-budget.json.

Rules

Rule	What it flags	Suppress with	Baseline / slack
LIT001	Mutable collection in any annotation (params, returns, class attrs, locals, globals) — builtins (dict/list/set), typing aliases (Dict/List/…), collections concretes (deque/defaultdict/…), and mutable ABCs (MutableMapping/MutableSequence/MutableSet). Annotate a read-only view (Mapping/Sequence/tuple[X, ...]/frozenset[X]) instead.	# mutable-ok: <reason>	21452 / 2000
LIT002	Mutable-collection construction: a list/dict/set literal or comprehension, or a mutable constructor call. dict/list/set count only unqualified, so a .dict()/.set()/.list() method call (e.g. a pydantic model.dict()) is not flagged, while the collections concretes (deque/defaultdict/Counter/…) count even when qualified. Catches the unannotated seed-then-mutate pattern LIT001 can't see (acc = []). Build in one shot and freeze — tuple(f(x) for x in xs), a tuple literal, or a frozen dataclass.	# mutable-ok: <reason>	25022 / 2500
LIT003	noqa without rule codes or without a reason.	# noqa: TID251 # <reason>	397 / 25
LIT004	type/pyright/mypy ignore without bracketed codes or a reason.	# pyright: ignore[rule] # <reason>	2515 / 50
LIT005	A # mutable-ok / # cast-ok / # guard-ok / # kwargs-ok / # any-ok suppression with no reason (any-ok is owned by check_any_discipline.py but enumerated here so the reason requirement holds even when only this checker runs).	add : <reason>	0 / 0
LIT006	cast(...) call site — an unchecked assertion (TypeScript's as) with zero runtime guarantee. Validate into a frozen type at the boundary.	# cast-ok: <reason>	1013 / 100
LIT007	TypeGuard[...] / TypeIs[...] annotation — the predicate body is never verified. Hard ban (none today).	# guard-ok: <reason>	0 / 0
LIT008	**kwargs parameter — erases the keyword contract (everything becomes Any). Declare explicit keyword params or accept one frozen payload. Typed *args is fine (it's a tuple).	# kwargs-ok: <reason>	914 / 90

The LIT### space is shared with PR #30379's Any gate, which owns LIT000 (build/read error) and LIT009 (Any-typed value); this checker owns the contiguous LIT001–LIT008. Annotation presence on *args/**kwargs has no LIT rule; Ruff's ANN002/ANN003 cover it.

Non-gating ratchet guard

scripts/budget_ratchet_check.py runs as a separate non-gating CI job (budget-ratchet). It compares each *-budget.json against its content at the merge-base and turns the run red if any ceiling (baseline + slack) rises, a rule is dropped, or a budget file is deleted. It is deliberately kept out of branch-protection required checks: a justified bump (e.g. banning a new API mechanically raises a baseline) can still be merged by a human who has seen and accepted the red. Budgets are a one-way ratchet — they may only go down or stay flat.

Budget slack

Beyond the TID251 baseline bump, this PR also widens the per-rule slack on ~33 existing ruff-strict rules (for example ANN001/ANN201/ANN401 from 10 to 50, ANN003/ANN202 from 10 to 30, BLE001 from 10 to 50, B006 from 3 to 10, C901 from 3 to 15); the new LIT rules carry the nonzero slack shown in the Rules table above, with LIT005 and LIT007 held at 0. Both ruff_strict_gate and type_discipline_gate are delta-vs-base, so slack never causes a PR to be blamed for drift already in the base; it only sets how many net-new violations one PR may add before the gate trips. Every one of these ceiling raises is reported red by the non-gating budget-ratchet job, so each increase stays visible for a human to accept and none can move a ceiling silently

CI wiring

test-linting.yml:

• adds a type_discipline_gate.py --base "$BASE_SHA" step next to the existing ruff_strict_gate.py step (gating), and
• adds a separate non-gating budget-ratchet job running budget_ratchet_check.py.

Files

• ruff-strict.toml — ban cast/TypeGuard/TypeIs via banned-api
• ruff-strict-budget.json — TID251 baseline 2404 → 2664, plus per-rule slack widening on ~33 rules (see Budget slack)
• scripts/check_type_discipline.py — vendored stdlib AST checker (LIT001–008)
• scripts/type_discipline_gate.py — baseline+slack gate with delta-vs-base
• scripts/budget_ratchet_check.py — non-gating "ceilings may only fall" guard; watches all four budgets (ruff-strict, type-discipline, mypy-code, basedpyright-code)
• type-discipline-budget.json — per-LIT budgets
• basedpyright-code-budget.json — 7 reportAny/reportUnknown* ceilings bumped to absorb pre-existing staging drift (see note below)
• .github/workflows/test-linting.yml — run the gate + the non-gating ratchet job
• tests/test_litellm/{test_check_type_discipline,test_type_discipline_gate,test_budget_ratchet_check}.py — per-rule, gate-logic, and ratchet regression tests

Test plan

• test-linting workflow passes on this PR (no net-new violations introduced here).
• Gate trips on a deliberately-added cast() / **kwargs / mutable annotation / mutable construction (verified locally).
• # cast-ok / # guard-ok / # kwargs-ok / # mutable-ok / # any-ok suppressions are honored.
• A missing reason on a suppression is rejected (LIT005).
• budget-ratchet job goes red when a ceiling is raised, and stays green on a decrease.

basedpyright ceiling bump

Merging litellm_internal_staging into this branch pulled in PR #30379's basedpyright gate, a total-count check that the linting workflow only runs on pull_request, so pushes to staging never re-baseline it. The merge surfaced pre-existing drift: seven reportAny / reportUnknown* rules sit 10-149 errors above their committed ceiling. This PR adds no files under litellm/, the only path basedpyright scans (pyrightconfig include is litellm), so the bump in basedpyright-code-budget.json just moves those seven baselines to the counts CI measured on the merge commit, with each rule's existing slack preserved. Ideally staging is re-baselined directly so every open PR stops tripping the same drift. The ratchet guard now watches basedpyright-code-budget.json, so this bump is surfaced by the non-gating budget-ratchet job for human review, the same as the TID251 raise

---

Note

Medium Risk
The change is mostly CI/scripts and budget JSON, but it tightens enforcement on a large existing litellm/ tree and raises several budget ceilings; wrong baselines or gate logic could block PRs or allow silent loosening if the ratchet job is ignored.

Overview
Adds a gating type-discipline pipeline alongside the existing ruff-strict budget: a stdlib AST checker (check_type_discipline.py) emits LIT001–LIT008 (mutable annotations/construction, undocumented suppressions, cast(), TypeGuard/TypeIs, **kwargs), and type_discipline_gate.py enforces per-rule ceilings in new type-discipline-budget.json with the same delta-vs-merge-base blame model as ruff_strict_gate.py. CI runs that gate in test-linting.yml.

Ruff layer: ruff-strict.toml bans imports of cast, TypeGuard, and TypeIs; ruff-strict-budget.json bumps TID251 baseline and widens slack on many strict rules so existing debt stays gateable.

Ratchet visibility: New non-gating budget-ratchet job runs budget_ratchet_check.py, which fails (red, mergeable) when any *-budget.json ceiling rises, a rule is dropped, or a budget file is deleted. CLAUDE.md documents LIT001/LIT002 remediation (immutable builds over # mutable-ok).

Unit tests cover the checker rules, gate logic, and ratchet comparisons.

^{Reviewed by Cursor Bugbot for commit 73620e6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a ratcheted type-discipline CI gate on top of the existing ruff_strict_gate infrastructure: a new stdlib AST checker (scripts/check_type_discipline.py) emits LIT001–LIT008 rules (mutable annotations/construction, unexplained suppressions, cast(), TypeGuard/TypeIs, and **kwargs), gated per-rule via type-discipline-budget.json and scripts/type_discipline_gate.py. A separate non-gating budget-ratchet job watches all *-budget.json ceilings and turns red whenever any ceiling rises.

• ruff-strict.toml bans cast/TypeGuard/TypeIs at the import level via banned-api; ruff-strict-budget.json raises the TID251 baseline from 2404 → 2664 to absorb pre-existing usages, but also silently widens slack on 30+ unrelated rules (PLR0913: 3→50, UP006/UP045: 10→100) without explanation in the PR description.
• The checker correctly uses io.StringIO(source).readline for tokenization, catches SyntaxError (incl. IndentationError) in scan_comments, scopes LIT007 to node.returns only, and uses best-effort worktree cleanup in finally.
• Tests cover all per-rule violations, suppression paths, gate logic (over_ceiling/evaluate), and ratchet regressions; test_default_budgets_watch_every_budget_file_in_the_repo pins the DEFAULT_BUDGETS list against the filesystem.

Confidence Score: 5/5

All changes are confined to CI scripts and budget JSON files; no litellm/ runtime code is touched, so merging cannot regress production behavior.

The bugs raised in earlier review rounds (tokenizer crash, double-fault in finally, vacuous pass on bad BASE_SHA, iter_guard_violations false positives) all have thread replies indicating fixes, and the current diff matches the described resolutions. The only remaining open question is why 30+ ruff-strict slack values were widened alongside the stated TID251 work — the non-gating budget-ratchet job surfaces these ceiling increases as red for a human to accept, so the risk is visible and containable.

ruff-strict-budget.json — the unexplained slack increases for rules unrelated to TID251 deserve a clarifying note before merge.

Important Files Changed

Filename	Overview
scripts/check_type_discipline.py	New stdlib AST checker for LIT001–LIT008; uses io.StringIO(source).readline for tokenization, catches SyntaxError (incl. IndentationError) in scan_comments, and correctly scopes LIT007 to return annotations only.
scripts/type_discipline_gate.py	Gate logic uses over_ceiling + evaluate (delta-vs-merge-base) correctly; best-effort worktree cleanup in finally avoids the double-fault from earlier threads; main() correctly propagates SystemExit(1) from cmd_check on breach.
scripts/budget_ratchet_check.py	Non-gating ratchet guard; _ref_is_commit guard prevents vacuous pass on invalid BASE_SHA; _load_base's git-failure-as-absent-file ambiguity is mitigated by the caller's commit verification.
ruff-strict-budget.json	TID251 baseline bump (2404→2664) is explained; however 30+ other rules have slack values increased (PLR0913: 3→50, UP006/UP045: 10→100, ANN001/BLE001: 10→50) without documented justification — the budget-ratchet job will flag these as ceiling regressions.
type-discipline-budget.json	New per-LIT budget; LIT005/LIT007 correctly at slack 0; LIT003 has slack=25, consistent with the gate docstring grouping it with slack-buffered rules.
.github/workflows/test-linting.yml	Adds type_discipline_gate step to the gating lint job and a separate non-gating budget-ratchet job; budget-ratchet correctly uses plain python (stdlib-only, no uv env needed) with fetch-depth:0.
tests/test_litellm/test_check_type_discipline.py	Good per-rule coverage including regression tests for the readline path, IndentationError degradation to LIT000, annotation-context exemption, and guard-outside-annotation non-flagging.
tests/test_litellm/test_budget_ratchet_check.py	Tests cover all ratchet cases; test_default_budgets_watch_every_budget_file_in_the_repo pins DEFAULT_BUDGETS against the filesystem.
tests/test_litellm/test_type_discipline_gate.py	Pins over_ceiling and evaluate pure functions; covers at-cap, over-cap-but-flat-vs-base, and over-cap-and-grown cases correctly.
ruff-strict.toml	Adds cast/TypeGuard/TypeIs to banned-api with clear rationale messages.
CLAUDE.md	Adds LIT001/LIT002 guidance directing contributors toward functional immutable builds.

_{Reviews (15): Last reviewed commit: "docs(lint): align gate docstring with bu..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e0c33a3. Configure here.}

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 73620e6. Configure here.}

[cursor]

Multi-line LIT001 wrong line

Medium Severity

LIT001 uses one anchor line for an entire annotation expression, so violations inside a multi-line return or assignment annotation are reported on the first line of that expression. A # mutable-ok comment on the line that actually contains the mutable name is ignored because suppression only checks that anchor line, and the type-discipline gate’s “introduced on this PR” hints can miss the edited line.

Additional Locations (2)

• scripts/check_type_discipline.py#L278-L282
• scripts/check_type_discipline.py#L292-L298

 

^{Reviewed by Cursor Bugbot for commit 73620e6. Configure here.}