feat: ruff strict-rule suppressions baseline gate

[ryan-crabbe-berri]

Relevant issues

None

Linear ticket

None

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

What this adds

This gives the backend a stricter ruff rule set in the same spirit as the dashboard's eslint gate, without forcing a repo-wide cleanup first. Each of ten rules gets a hard ceiling on how many times it may appear across the whole codebase. Today's count sits under the ceiling, so existing violations are grandfathered; a change only fails CI when it pushes a rule's total above its ceiling. As violations get fixed and a count drops, you lower that ceiling, so the number can only ratchet down

The new rules are kept in ruff-strict.toml, a config separate from ruff.toml. The existing ruff check gate is untouched, so nothing about today's linting changes

The rules and their ceilings

The ceiling for each rule is baseline + slack, stored in ruff-strict-budget.json, where the baseline is today's count. The annotation-completeness rules (ANN001, ANN401, TID251, ANN003) get a slack of 10 to 25 so they nudge rather than block; the correctness and structural rules get a small cushion of 3 to be liberal to start

Rule	Enforces	Today	Slack	Ceiling
ANN001	function arguments must be typed	2,865	10	2,875
ANN401	no Any in annotations	1,885	10	1,895
PLR0913	at most 5 function arguments	1,813	3	1,816
TID251	no importing the listed typing collection aliases	2,404	10	2,414
ANN003	**kwargs must be typed	759	10	784
C901	cyclomatic complexity at most 15	301	3	304
PLW0603	no rebinding module globals via global	183	3	186
B006	no mutable values as argument defaults	180	3	183
RUF012	mutable class attributes must be ClassVar	158	3	161
ANN002	*args must be typed	64	3	67

TID251 is import-level, so it counts about one violation per file; it bans typing.Any, Dict, List, Set, MutableSequence, and MutableMapping, steering new code toward structured and immutable types (tuple, Sequence, Mapping, frozenset, AbstractSet, frozen dataclasses, NamedTuples, TypedDicts). Tune any rule by editing its slack, and ratchet by lowering the baseline with make lint-strict-budget-update after fixes

Some rules are intentionally partial. "No lists or dicts unless frozen" is covered for argument defaults (B006), class attributes (RUF012), and new imports of the mutable typing collection aliases such as Dict, List, and Set (TID251), but ruff cannot ban every literal. "Globals must be frozen" is covered only as a ban on global rebinding (PLW0603), since ruff has no rule forcing module constants to be Final. Mutation of function arguments has no ruff rule at all and is left out

How the gate works

A first cut compared the whole tree against a committed baseline count, and it broke immediately. CI lints the PR merged with the current base tip, so when other PRs merged new violations into litellm_internal_staging, those counted against this PR's frozen baseline even though this PR never touched those files. A committed snapshot goes stale the moment the base moves

scripts/ruff_strict_gate.py is drift-safe instead. It counts each rule on the head, counts the same rule on the base it merges into (a throwaway git worktree of the merge-base), and fails a rule only when its head total is both over the ceiling and higher than the base. So if the base already drifted over a ceiling, a change that does not add to that rule still passes, and a change that reduces an over-ceiling rule passes too; only a change that pushes the total up is blamed. Existing violations are grandfathered because they already sit in the base count

The escape hatch for a genuinely justified violation is an inline # noqa on that line, which stays visible and greppable

CI (LiteLLM team)

• Branch creation CI run
  Link:
• CI run for the last commit
  Link:
• Merge / cherry-pick CI run
  Links:

Proof of fix

The gate is dev tooling, so the proof is its behavior. A clean change passes; a change that pushes a rule over its ceiling fails and names what it added; a change within the slack passes

$ python scripts/ruff_strict_gate.py
OK: every strict rule is within its codebase ceiling (base origin/litellm_internal_staging)

# add 3 mutable defaults (B006 ceiling is 183 = 180 baseline + 3 slack)
$ python scripts/ruff_strict_gate.py ; echo "exit=$?"
OK: every strict rule is within its codebase ceiling (base origin/litellm_internal_staging)
exit=0

# add a 4th, now over the ceiling
$ python scripts/ruff_strict_gate.py ; echo "exit=$?"
FAIL: strict-rule totals exceed their ceiling (base origin/litellm_internal_staging):
  B006: total 184 over cap 183 (this change added 4)
    litellm/_tmp_probe.py:1
    litellm/_tmp_probe.py:5
    litellm/_tmp_probe.py:9
    litellm/_tmp_probe.py:13
Reduce the new violations or remove an equal number elsewhere; the ceiling is baseline + slack in ruff-strict-budget.json.
exit=1

The gate logic is unit tested in tests/test_litellm/test_ruff_strict_gate.py: the ceiling boundary, drift safety (a base already over the ceiling does not blame a change that adds nothing, and a change that reduces an over-ceiling rule passes), per-rule independence, a missing rule defaulting to zero, and the diff parsing used to point at what a change added

Type

Infrastructure

Changes

ruff-strict.toml (new) defines the ten strict rules by extending ruff.toml and configures the TID251 banned-api list. ruff-strict-budget.json (new) holds each rule's baseline and slack. scripts/ruff_strict_gate.py (new) is the drift-safe total-count gate, with --update to re-capture baselines after fixes. .github/workflows/test-linting.yml gains one step that runs the gate against the PR base. The Makefile gains lint-strict-budget and lint-strict-budget-update, with the check wired into make lint. ruff.toml is untouched. CLAUDE.md documents how to ratchet the baselines down and how to avoid spending the Any budget

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR introduces a ratcheting ruff strict-rule gate that enforces ten additional lint rules across the codebase without requiring an upfront mass cleanup. A drift-safe script compares head violation counts against the merge-base rather than a frozen snapshot, so only changes that push a rule's total above its ceiling are blocked.

• ruff-strict.toml + ruff-strict-budget.json define ten rules with per-rule baselines and slack; scripts/ruff_strict_gate.py implements the ceiling check using git worktree for the base snapshot and a diff parser to pinpoint which lines in the PR introduced breaches.
• The CI workflow gains one PR-only step passing BASE_SHA from the PR event, and make lint is wired to run the budget check locally via origin/litellm_internal_staging as the default base.
• Unit tests cover the ceiling boundary, drift-safety, per-rule independence, and diff-line parsing, though the parametrised hunk test uses a weak truthiness assertion.

Confidence Score: 5/5

Safe to merge; the gate is additive dev tooling that leaves the existing ruff check untouched and only affects PR CI on violations exceeding a generous per-rule budget.

All findings are quality-of-life issues in the gate script itself (exception masking in the worktree cleanup, exit-code conflation, and a weak test assertion). None affect whether the gate correctly passes or fails a PR in normal operation, and the core evaluate/drift-safety logic is well-exercised by the new unit tests.

scripts/ruff_strict_gate.py — the finally block in base_counts and the shared _run exit-code handling are worth a second look for robustness when git worktree add fails.

Important Files Changed

Filename	Overview
scripts/ruff_strict_gate.py	New drift-safe gate script; correct core logic but finally block can mask the original git error when worktree add fails, and _run conflates ruff/git exit-code 1 semantics
tests/test_litellm/test_ruff_strict_gate.py	Good unit coverage of evaluate, drift-safety, and diff parsing; parametrised hunk test uses weak truthiness assertion instead of explicit line-set comparison
.github/workflows/test-linting.yml	Adds one PR-only CI step that passes BASE_SHA from the PR event; workflow is pull_request-scoped so BASE_SHA is always populated, fetch-depth=0 satisfies git worktree requirements
Makefile	Adds lint-strict-budget and lint-strict-budget-update targets and wires the budget check into make lint; local execution requires origin/litellm_internal_staging to be up to date
ruff-strict.toml	New ruff config extending the existing one with ten strict rules; TID251 banned-api messages are clear and actionable
ruff-strict-budget.json	New file recording today's baseline counts and per-rule slack; values match the PR description table

_{Reviews (3): Last reviewed commit: "chore: give the structural strict rules ..." | Re-trigger Greptile}

[ryan-crabbe-berri]

@greptileai re review

[ryan-crabbe-berri]

@greptileai re review

[mateo-berri]

I love this. LGTM 🏆