feat: add lint-gate target and truncation-proof summary to the strict ruff gate

Makefile

@@ -6,7 +6,7 @@
 	test-proxy-unit-a test-proxy-unit-b test-integration test-unit-helm \
 	info lint lint-dev format \
 	lint-basedpyright lint-basedpyright-budget-update \
-	lint-ruff-budget lint-ruff-budget-update lint-budget-update \
+	lint-ruff-budget lint-ruff-budget-update lint-budget-update lint-gate \
 	install-dev install-proxy-dev install-test-deps install-hooks \
 	install-helm-unittest check-circular-imports check-import-safety
 
@@ -28,6 +28,7 @@ help:
 	@echo "  make lint-basedpyright-budget-update - Re-capture the basedpyright per-rule budget (ratchet)"
 	@echo "  make lint-black         - Check Black formatting (matches CI)"
 	@echo "  make lint-ruff-budget - Gate the codebase total of each strict ruff rule against its ceiling"
+	@echo "  make lint-gate        - Strict ruff gate in CI-parity mode (fetches staging, simulates the merge)"
 	@echo "  make lint-ruff-budget-update - Re-capture per-rule baselines in ruff-strict-budget.json (ratchet)"
 	@echo "  make lint-budget-update - Re-capture all ratchet budgets (ruff + basedpyright)"
 	@echo "  make check-circular-imports - Check for circular imports"
@@ -134,6 +135,12 @@ lint-black: format-check
 lint-ruff-budget: install-dev
 	$(UV_RUN) python scripts/ruff_strict_gate.py
 
+# Strict gate, invoked the same way CI does in test-linting.yml so a local pass
+# means the CI check will pass too.
+lint-gate: install-dev
+	git fetch origin litellm_internal_staging
+	$(UV_RUN) python scripts/ruff_strict_gate.py --base origin/litellm_internal_staging
+
 lint-ruff-budget-update: install-dev
 	$(UV_RUN) python scripts/ruff_strict_gate.py --update
 

scripts/ruff_strict_gate.py

@@ -5,16 +5,21 @@
 gate counts each rule across the whole tree and fails when a rule is both over
 its ceiling and higher than the base it merges into, so a change is blamed for
 the violations it adds, never for drift that already exists in the base.
+
+The base is the merge-base of the current branch with --base; this matches CI,
+which checks out the PR head sha and runs the gate against the PR's base sha.
 """
 
 import argparse
+import contextlib
 import json
 import re
 import shutil
 import subprocess
 import sys
 import tempfile
 from collections import Counter
+from collections.abc import Iterator
 from pathlib import Path
 from typing import NamedTuple
 
@@ -40,6 +45,12 @@ class Breach(NamedTuple):
     added: int
 
 
+class GateInputs(NamedTuple):
+    head: list[Violation]
+    base: dict[str, int]
+    changed: dict[str, set[int]]
+
+
 def _run(cmd: list, cwd: Path = REPO_ROOT) -> str:
     proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
     if proc.returncode not in (0, 1):
@@ -56,14 +67,14 @@ def _ruff_json(cwd: Path, config: Path) -> list:
     return json.loads(raw or "[]")
 
 
-def head_violations() -> list:
+def collect_violations(root: Path, config: Path) -> list:
     out = []
-    for item in _ruff_json(REPO_ROOT, STRICT_CONFIG):
+    for item in _ruff_json(root, config):
         name = Path(item["filename"])
         rel = (
-            (name if name.is_absolute() else REPO_ROOT / name)
+            (name if name.is_absolute() else root / name)
             .resolve()
-            .relative_to(REPO_ROOT)
+            .relative_to(root)
             .as_posix()
         )
         out.append(Violation(rel, item["location"]["row"], item["code"]))
@@ -74,27 +85,29 @@ def count_by_rule(violations: list) -> dict:
     return dict(Counter(v.code for v in violations))
 
 
-def base_counts(ref: str) -> dict:
-    parent = Path(tempfile.mkdtemp(prefix="ruff_base_"))
+@contextlib.contextmanager
+def _temp_worktree(ref: str) -> Iterator[Path]:
+    parent = Path(tempfile.mkdtemp(prefix="ruff_wt_"))
     worktree = parent / "wt"
     try:
         _run(["git", "worktree", "add", "--detach", str(worktree), ref])
-        shutil.copy(STRICT_CONFIG, worktree / "ruff-strict.toml")
-        items = _ruff_json(worktree, worktree / "ruff-strict.toml")
-        return dict(Counter(item["code"] for item in items))
+        yield worktree
     finally:
-        _run(["git", "worktree", "remove", "--force", str(worktree)])
+        subprocess.run(
+            ["git", "worktree", "remove", "--force", str(worktree)],
+            cwd=REPO_ROOT,
+            capture_output=True,
+            text=True,
+        )
         shutil.rmtree(parent, ignore_errors=True)
 
 
-def evaluate(head: dict, base: dict, budget: dict) -> list:
-    breaches = []
-    for rule, spec in budget.items():
-        cap = spec["baseline"] + spec["slack"]
-        total = head.get(rule, 0)
-        if total > cap and total > base.get(rule, 0):
-            breaches.append(Breach(rule, total, cap, total - base.get(rule, 0)))
-    return sorted(breaches)
+def base_counts(ref: str) -> dict:
+    with _temp_worktree(ref) as worktree:
+        shutil.copy(STRICT_CONFIG, worktree / "ruff-strict.toml")
+        return count_by_rule(
+            collect_violations(worktree, worktree / "ruff-strict.toml")
+        )
 
 
 def parse_changed_lines(diff_text: str) -> dict:
@@ -110,24 +123,31 @@ def parse_changed_lines(diff_text: str) -> dict:
     return changed
 
 
+def evaluate(head: dict, base: dict, budget: dict) -> list:
+    breaches = []
+    for rule, spec in budget.items():
+        cap = spec["baseline"] + spec["slack"]
+        total = head.get(rule, 0)
+        if total > cap and total > base.get(rule, 0):
+            breaches.append(Breach(rule, total, cap, total - base.get(rule, 0)))
+    return sorted(breaches)
+
+
 def introduced(violations: list, changed: dict) -> list:
     return [v for v in violations if v.line in changed.get(v.file, set())]
 
 
-def cmd_check(base: str) -> None:
-    budget = json.loads(BUDGET_PATH.read_text())
-    head = head_violations()
+def gather(base: str) -> GateInputs:
     base_point = _run(["git", "merge-base", base, "HEAD"]).strip() or base
-    breaches = evaluate(count_by_rule(head), base_counts(base_point), budget)
-    if not breaches:
-        print(f"OK: every strict rule is within its codebase ceiling (base {base})")
-        return
-    new = introduced(
-        head,
-        parse_changed_lines(
-            _run(["git", "diff", base_point, "--unified=0", "--no-color", "--", TARGET])
-        ),
+    diff = _run(["git", "diff", base_point, "--unified=0", "--no-color", "--", TARGET])
+    return GateInputs(
+        collect_violations(REPO_ROOT, STRICT_CONFIG),
+        base_counts(base_point),
+        parse_changed_lines(diff),
     )
+
+
+def report(breaches: list, new: list, base: str) -> None:
     print(f"FAIL: strict-rule totals exceed their ceiling (base {base}):")
     for breach in breaches:
         print(
@@ -138,12 +158,24 @@ def cmd_check(base: str) -> None:
     print(
         "Reduce the new violations or remove an equal number elsewhere; the ceiling is baseline + slack in ruff-strict-budget.json."
     )
+    summary = "; ".join(f"{b.rule} {b.total}/{b.cap} (+{b.added})" for b in breaches)
+    print(f"BREACHED RULES: {summary}")
+
+
+def cmd_check(base: str) -> None:
+    budget = json.loads(BUDGET_PATH.read_text())
+    inputs = gather(base)
+    breaches = evaluate(count_by_rule(inputs.head), inputs.base, budget)
+    if not breaches:
+        print(f"OK: every strict rule is within its codebase ceiling (base {base})")
+        return
+    report(breaches, introduced(inputs.head, inputs.changed), base)
     raise SystemExit(1)
 
 
 def cmd_update() -> None:
     budget = json.loads(BUDGET_PATH.read_text())
-    head = count_by_rule(head_violations())
+    head = count_by_rule(collect_violations(REPO_ROOT, STRICT_CONFIG))
     for rule in budget:
         budget[rule]["baseline"] = head.get(rule, 0)
     BUDGET_PATH.write_text(json.dumps(budget, indent=2, sort_keys=True) + "\n")

tests/test_litellm/test_ruff_strict_gate.py

@@ -82,3 +82,13 @@ def test_introduced_keeps_only_violations_on_changed_lines():
 @pytest.mark.parametrize("hunk", ["@@ -1 +1 @@", "@@ -1,0 +1,2 @@"])
 def test_parse_changed_lines_handles_single_and_ranged_hunks(hunk):
     assert gate.parse_changed_lines(f"+++ b/litellm/a.py\n{hunk}\n")["litellm/a.py"]
+
+
+def test_report_emits_breached_rules_as_final_line(capsys):
+    # CI surfaces only the tail of the log, so the breached-rule summary (rule,
+    # total/cap, added) must be the last line or it gets truncated away.
+    breaches = sorted([gate.Breach("UP045", 530, 529, 1), gate.Breach("ANN401", 12, 10, 2)])
+    new = [gate.Violation("litellm/types/llms/bedrock.py", 16, "UP045")]
+    gate.report(breaches, new, "origin/litellm_internal_staging")
+    last = capsys.readouterr().out.strip().splitlines()[-1]
+    assert last == "BREACHED RULES: ANN401 12/10 (+2); UP045 530/529 (+1)"