chore: import upstream snapshot with attribution

scripts/check_code_size_budget.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Enforce a ratcheting Rust file-size budget.
+
+This script keeps the current oversized-file debt from getting worse while the
+larger refactor program is underway.
+
+Policy:
+- Production Rust files above the configured LOC threshold are tracked in a
+  baseline file.
+- Existing tracked oversized files may not grow.
+- New oversized production files may not be introduced.
+- If oversized files shrink or disappear, the script reports the improvement.
+- `--update` refreshes the baseline after intentional cleanup.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+BASELINE_FILE = REPO_ROOT / "scripts" / "code_size_budget.json"
+DEFAULT_THRESHOLD = 1200
+SCAN_ROOTS = (REPO_ROOT / "src", REPO_ROOT / "crates")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--update",
+        action="store_true",
+        help="refresh the baseline to the current oversized-file set",
+    )
+    return parser.parse_args()
+
+
+def is_production_rust_file(path: Path) -> bool:
+    rel = path.relative_to(REPO_ROOT).as_posix()
+    if path.suffix != ".rs":
+        return False
+    parts = rel.split("/")
+    if parts[0] == "tests" or any(
+        part == "tests" or part.endswith("_tests") or part.endswith("_test") or part.startswith("tests_")
+        for part in parts
+    ):
+        return False
+    name = path.name
+    if (
+        name == "tests.rs"
+        or name.endswith("_tests.rs")
+        or name.endswith("_test.rs")
+        or name.startswith("tests_")
+    ):
+        return False
+    return True
+
+
+def rust_file_line_count(path: Path) -> int:
+    with path.open("r", encoding="utf-8") as handle:
+        return sum(1 for _ in handle)
+
+
+def current_oversized_files(threshold: int) -> dict[str, int]:
+    files: dict[str, int] = {}
+    for root in SCAN_ROOTS:
+        if not root.exists():
+            continue
+        for path in sorted(root.rglob("*.rs")):
+            if not is_production_rust_file(path):
+                continue
+            line_count = rust_file_line_count(path)
+            if line_count > threshold:
+                files[path.relative_to(REPO_ROOT).as_posix()] = line_count
+    return files
+
+
+def load_baseline() -> dict[str, Any]:
+    if not BASELINE_FILE.exists():
+        raise SystemExit(f"error: missing baseline file: {BASELINE_FILE}")
+    data = json.loads(BASELINE_FILE.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise SystemExit(f"error: invalid baseline file format: {BASELINE_FILE}")
+    threshold = data.get("threshold_loc")
+    tracked = data.get("tracked_files")
+    if not isinstance(threshold, int) or threshold <= 0:
+        raise SystemExit(f"error: invalid threshold_loc in {BASELINE_FILE}")
+    if not isinstance(tracked, dict) or any(
+        not isinstance(k, str) or not isinstance(v, int) or v <= 0
+        for k, v in tracked.items()
+    ):
+        raise SystemExit(f"error: invalid tracked_files in {BASELINE_FILE}")
+    return data
+
+
+def write_baseline(threshold: int, tracked_files: dict[str, int]) -> None:
+    payload = {
+        "version": 1,
+        "threshold_loc": threshold,
+        "tracked_files": tracked_files,
+    }
+    BASELINE_FILE.write_text(
+        json.dumps(payload, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def main() -> int:
+    args = parse_args()
+    baseline = load_baseline()
+    threshold = baseline["threshold_loc"]
+    current = current_oversized_files(threshold)
+
+    if args.update:
+        write_baseline(threshold, current)
+        print(
+            "Updated code-size baseline: "
+            f"tracked={len(baseline['tracked_files'])} -> {len(current)} oversized files"
+        )
+        return 0
+
+    tracked: dict[str, int] = baseline["tracked_files"]
+    regressions: list[str] = []
+    improvements: list[str] = []
+
+    for path, lines in sorted(current.items()):
+        old_lines = tracked.get(path)
+        if old_lines is None:
+            regressions.append(
+                f"new oversized file exceeds {threshold} LOC: {path} ({lines} LOC)"
+            )
+        elif lines > old_lines:
+            regressions.append(
+                f"oversized file grew: {path} ({old_lines} -> {lines} LOC)"
+            )
+        elif lines < old_lines:
+            improvements.append(f"oversized file shrank: {path} ({old_lines} -> {lines} LOC)")
+
+    for path, old_lines in sorted(tracked.items()):
+        if path not in current:
+            improvements.append(
+                f"oversized file no longer exceeds {threshold} LOC: {path} ({old_lines} -> OK)"
+            )
+
+    if regressions:
+        print(
+            "Code-size budget exceeded. Existing oversized Rust files must shrink or stay flat, "
+            "and new oversized production files are not allowed:",
+            file=sys.stderr,
+        )
+        for entry in regressions:
+            print(f"  - {entry}", file=sys.stderr)
+        print(
+            "Run scripts/check_code_size_budget.py --update only after intentional cleanup.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if improvements:
+        print("Code-size budget improved:")
+        for entry in improvements:
+            print(f"  - {entry}")
+        print("Consider running: scripts/check_code_size_budget.py --update")
+    else:
+        print(
+            "Code-size budget OK: "
+            f"tracked={len(tracked)} threshold={threshold}LOC no oversized-file regressions"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())