diff --git a/scripts/audit_exception_handling.py b/scripts/audit_exception_handling.py index 1f91467a..8d28b09b 100644 --- a/scripts/audit_exception_handling.py +++ b/scripts/audit_exception_handling.py @@ -2,8 +2,11 @@ """Audit try/except/finally/raise usage against the data-oriented error handling convention. -This is an INFORMATIONAL audit, not a CI gate. It produces a report that the -user (or a follow-up track) uses to decide whether a refactor is worth it. +This audit is INFORMATIONAL by default (exits 0) so developers can run it +freely to see the current state. Pass `--strict` (or its alias `--ci`) +to enable CI-gate mode (exits 1 on any violation). The 4-script +enforcement set (see docs/AGENTS.md "Convention Enforcement") uses +`--strict` mode for pre-commit hooks and CI. The convention (see conductor/code_styleguides/error_handling.md) requires: @@ -47,10 +50,17 @@ Usage: uv run python scripts/audit_exception_handling.py --src src # source dir uv run python scripts/audit_exception_handling.py --top 20 # top N files uv run python scripts/audit_exception_handling.py --verbose # every site - uv run python scripts/audit_exception_handling.py --strict # exit 1 on violation + uv run python scripts/audit_exception_handling.py --strict # CI gate (exit 1 on violation) + uv run python scripts/audit_exception_handling.py --ci # alias for --strict uv run python scripts/audit_exception_handling.py --summary # per-file summary table uv run python scripts/audit_exception_handling.py --by-size # group by migration effort +Pre-commit / CI use (the convention's CI gate): + uv run python scripts/audit_exception_handling.py --strict + # Exits 1 on any violation. Use in pre-commit hooks and CI to enforce + # the data-oriented error handling convention. Part of the 4-script + # enforcement set (see docs/AGENTS.md "Convention Enforcement"). + Output modes (mutually exclusive; --json / --summary / --by-size override the default human-readable report): --summary: per-file table sorted by V+S descending. Use this for @@ -60,8 +70,9 @@ the default human-readable report): (default): top-N files with per-site breakdown and 1-line hints. Exit codes: - 0 - audit ran (informational mode; findings don't fail the script) - 1 - usage error, or --strict mode with violations found + 0 - audit ran in informational mode (default; no violations fail the script) + 1 - usage error, or --strict/--ci mode with violations found + 2 - source directory not found """ from __future__ import annotations import argparse @@ -838,7 +849,8 @@ def main() -> int: parser.add_argument("--top", type=int, default=15, help="Show top N files by violation count (default: 15)") parser.add_argument("--verbose", action="store_true", help="Show every site inline (default: top N summary)") parser.add_argument("--include-tests", action="store_true", help="Also scan tests/ and scripts/") - parser.add_argument("--strict", action="store_true", help="Exit 1 if any violations are found (for CI use)") + parser.add_argument("--strict", action="store_true", help="Exit 1 if any violations are found (for CI use; the convention's CI gate)") + parser.add_argument("--ci", dest="strict", action="store_true", help="Alias for --strict (clearer name for CI scripts; e.g., pre-commit hooks)") parser.add_argument("--include-baseline", action="store_true", help="Include the 3 refactored files in the violation count (default: exclude)") parser.add_argument("--summary", action="store_true", help="Per-file summary table (for migration planning)") parser.add_argument("--by-size", action="store_true", help="Group files by migration effort bucket (small/medium/large/baseline)")