Review the Python you changed, not the Python you inherited.

Avouch is a lightweight, Git-aware static analysis CLI for Python. It asks
Git which files your next commit will touch, parses each changed .py
file with the standard ast module, and reports structural problems
against limits you configure in avouch.toml.

No daemon. No network. No path lists to maintain. Run it in the seconds
before git push, fix what it flags, push.

pip install avouch cd your-repo avouch
- Why it exists
- Installation
- Quick start
- JSON output
- Quiet mode
- GitHub Actions
- Other CI systems
- Configuration
- Rules
- How it works
- Repository layout
- Adding a rule
- Testing
- Roadmap
- FAQ
- Contributing
- License

The review set is the diff, not the repository.Avouch computes the review set from Git at run time (- git diff HEAD --name-onlyplus untracked files). Every finding is attributable to work you are about to push — never to the legacy you inherited.
Metrics are exact.Parameter counts, nesting depth, and line spans come from the AST, not regex. If a metric cannot be computed exactly, Avouch does not claim it.
Errors are data.An unreadable or syntactically broken file becomes an- ERRORentry in the report. One broken file never cancels the review of the others.
Avouch reviews; it does not gate.The exit code signals the outcome —- 0clean,- 1violations found,- 2Avouch error — but enforcement belongs in an opt-in interface, not in a tool you run before every push.
The runtime is the standard library.Three- gitsubprocess calls and- ast/- tomllib. No daemon to keep alive; runtime is bounded by the size of your diff, not your repository.

Requires Python 3.10+ (rules use ast.Match; configuration uses
tomllib) and Git on PATH.

pip install avouchor from source:

git clone https://github.com/mukundzha/avouch.git cd avouch pip install -e .
Both register the avouch console script (avouch.cli:main).

The interface is one command with a small set of optional flags:

```
cd your-repo

... make a change ...

avouch # human report
avouch --json # one JSON document on stdout
avouch --docs # built-in documentation; no review performed
avouch --version # print the version and exit
avouch --verbose # step-by-step review details on stderr
avouch --quiet # analyze, print no report; exit code only
avouch --changed # compact added/deleted view of changed files vs HEAD
avouch --staged # review only files staged for the next commit
avouch --all-files # review every eligible Python file, not just the diff
avouch --not-git # review every eligible .py file on disk; no Git repo needed
avouch --help # every flag
`` The review set is defined by Git, so there is nothing to configure at invocation time. With--not-git, Avouch skips the Git requirement and reviews every eligible.py` file found by walking the current
directory instead (skipping Git, cache, and virtual-environment
directories). Avouch reviews:

tracked files modified vs. HEAD(git diff HEAD --name-only), and
untracked .pyfiles (git ls-files --others --exclude-standard).

Deleted paths and non-.py files are skipped. Committed, untouched files
never appear in the output. Files that look generated
(generated.py, *_generated.py, codegen.py, autogen.py, … — see
src/avouch/utility/is_generated.py) are skipped too.

The review-scope flags --changed, --staged, and --all-files are
mutually exclusive — pick at most one. The output flags --json,
--verbose, and --quiet combine freely with any review scope.

$ avouch AVOUCH · 2 FILES · 4 WARN ──────────────────────────────────────────────────────────────────────────────── bad.py:1: SCR002: Bare except detected. Catch a specific exception instead, e.g. except ValueError:. │ 1 │ def connect(host, port, user, password, db, timeout): │ ^^^^^^^ SCR002 2 │ try: │ bad.py:1: SCR014: Too many parameters (6/5). Group related parameters into a data class or dictionary. │ 1 │ def connect(host, port, user, password, db, timeout): │ ^^^^^^^ SCR014 2 │ try: │ ──────────────────────────────────────────────────────────────────────────────── BY RULE SCR002 Bare except 1 SCR014 Too many parameters 1 ──────────────────────────────────────────────────────────────────────────────── PASSED ✓ src/util.py
- Header—- AVOUCH · N FILES · W WARN · E ERR: file and per-severity counts, followed by the per-file findings.
- Findings— each finding renders compiler-style: a- file:lineheader with the rule id and full message, then the offending code region with dimmed line numbers and a caret- ^^^^^under the flagged name (rule id in blue on a TTY).
- BY RULE summary— findings counted per rule, most common first, with counts aligned on the right. Rendered only when findings exist.
- PASSING grid— compliant files, compressed to a few lines with a- [+N more]note when there are many.
- Identical (component, rule)findings are deduplicated per file — the header counts every finding, so with overlapping rule IDs (SCR004 / SCR006 duplicate-branch) the row count can be lower than the header count.

$ avouch All clean.
$ cd /tmp/somewhere-without-git $ avouch error: no Git repository found hint: run Avouch from inside a Git repository, or use --not-git to review files without Git $ cd ~/fresh-checkout # e.g. a CI runner $ avouch error: nothing to review hint: nothing changed vs HEAD (CI checkouts are clean); use --all-files for a full review
Colors are ANSI codes emitted only when stdout is a TTY. Piped output is
plain, so avouch | tee review.log and CI capture work cleanly. Runtime
errors are written to stderr, so stdout stays clean for piping and
--json capture. The exit code is 0 when the review is clean, 1
when findings are reported, and 2 when Avouch cannot run.

avouch --docs prints terminal documentation derived from this codebase —
what Avouch does, the Git-aware workflow, every rule with its scope, every
configuration key with its default, both output formats, and realistic
examples — then exits 0 without running a review. It works anywhere,
even outside a Git repository. In a real terminal it opens as an
interactive browser (Help, Go, Main screen, Quit); when stdout
is piped it prints the plain text instead.

For automation and CI, --json prints the review as a single JSON document
on stdout, with no human-readable text mixed in:

avouch --json```` { "version": 1, "tool": "avouch", "violations": [ { "rule": "SCR014", "severity": "WARNING", "message": "Too many parameters (6/5). Group related parameters into a data class or dictionary.", "file": "buggy.py", "name": "extra", "kind": "func", "line": 4 } ], "summary": { "total": 1, "errors": 0, "warnings": 1, "files_with_violations": 1 } } ``` Each violation carries the rule id (or a human-readable label when the finding has none), its severity, the message, the file, the component name, its kind (func,class, orfile), and the line the finding refers to (nullfor file-level findings) — the same component and kind shown in the human table.files_with_violations` is the number of distinct
files containing at least one violation.

The document is a stable, versioned contract for automation: version
is the schema version (independent of the Avouch package version), tool
identifies the emitter, and the same input always produces the same JSON
— no colors, timestamps, or diagnostics leak in. Exit codes behave
exactly as in normal mode, so avouch --json can gate CI: parse stdout
for the findings and react to the exit status (0 clean, 1 violations,
2 Avouch error).

--quiet runs the exact same analysis but prints no report; only the
exit code signals the outcome (0 clean, 1 violations, 2 Avouch
error), which makes it fit hooks and scripts that need only the status.
Errors are never silenced: messages such as "error: no Git repository found" still print, --json still emits its document, and
--verbose diagnostics still go to stderr.

Avouch can run as a GitHub Actions check on every pull request and push.

For an existing project, a minimal workflow installs the published package and reviews the whole checkout on every PR and push:

name: Avouch on: pull_request: push: jobs: avouch: runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v6 - uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install Avouch run: python -m pip install avouch - name: Run Avouch run: avouch --all-files --json
- actions/checkoutputs the pull request's code in the runner's working tree — Avouch analyzes the files that checkout provided, nothing more.
- actions/setup-pythonprovides a Python runtime; Avouch requires Python 3.10+.
- python -m pip install avouchinstalls the latest published release. Pin a version (- avouch==0.3.1) for reproducible runs.
- avouch --all-files --jsonreviews every eligible- .pyfile and prints the machine-readable document to the job log.- permissions: contents: readis the only permission needed — the workflow makes no API calls.

The default review set is files changed vs. Git HEAD, so a freshly
checked-out working tree — clean by construction — has nothing to review:
avouch would print error: nothing to review and exit 2. The same
applies to --changed and --staged; they only make sense locally,
against your own working tree. Whole-repository review is the mode that
works in CI:

| Command | Purpose | In CI |
|---|---|---|
| avouch | review files changed vs HEAD | empty set; don't use |
| avouch --changed | diff view of changed files | empty set; don't use |
| avouch --staged | review staged changes | empty set; don't use |
| avouch --all-files | review every eligible Python file | the CI mode |
| avouch --json | machine-readable document on stdout | combine with --all-files |
| avouch --quiet | suppress report; exit code only | fine for gating |

Avouch's exit code behaves in CI exactly as it does locally: 0 is clean,
1 means findings were reported, 2 means Avouch could not run. GitHub
Actions fails a job when a step exits non-zero, so --all-files --json
fails the check on any finding, and the JSON document in the job log shows
why. Nothing is hidden with || true; findings already present in the
repository fail the check until they are fixed or excluded with
ignore_paths in avouch.toml.

The Avouch repository itself ships .github/workflows/avouch.yml; enable it
in the repository's Actions tab and it runs on its own. It installs
the repository's own source with pip install -e ., so it tests the code
in the pull request rather than a published release, then reviews the
whole checked-out repository with --all-files --json.

Avouch is a plain console command with a documented exit code, so any CI system can run it with the same three steps:

Install: python -m pip install avouch
Run: avouch --all-files --json
Treat the exit code as the result: 0pass,1findings,2error.

The JSON document on stdout is stable and versioned (see JSON output), so it can be parsed for job annotations, summary comments, or dashboards.

Configuration is optional, partial, and declarative. Avouch looks for a
avouch.toml in the current working directory — no upward search, so
configuration is repository-local. Any subset of keys is merged over the
built-in defaults; a missing or empty file simply means defaults, with
no warning.

[limits] # numeric thresholds per rule [rules] # on/off toggle per rule ignore_paths = ["tests", "migrations"] # top-level: paths to skip
- Name and format:- avouch.tomlin your working directory, plain TOML.
- Scope:the current directory only. Avouch never searches parent directories, so each project configures itself.
- Missing or empty:defaults are used silently — there is no "no configuration found" warning.
- Environment variables:none. Configuration comes only from- avouch.toml(the- AVOUCH_FONTvariable only selects a terminal font).

List the limit you want under [limits]; only the keys you name change,
everything else stays at its default:

[limits] max_parameters = 8 # allow up to 8 parameters instead of 5 max_file_lines = 2500 # tolerate larger files
Put the rule under [rules] and set it to false:

[rules] nested_function = false # stop reporting SCR015
A one-line [rules] section is a complete, valid configuration.

| Key | Default | Rule |
|---|---|---|
| async_without_await | true | SCR001 |
| bare_except | true | SCR002 |
| max_boolean_conditions | true | SCR003 |
| detect_duplicateb | true | SCR004 |
| max_large_comprehensions | true | SCR005 |
| empty_except | true | SCR006 |
| max_if_else_chain | true | SCR007 |
| max_lambda_nodes | true | SCR008 |
| max_local_variables | true | SCR009 |
| max_class_lines | true | SCR010 |
| max_file_lines | true | SCR011 |
| max_function_lines | true | SCR012 |
| max_nesting | true | SCR013 |
| max_parameters | true | SCR014 |
| nested_function | true | SCR015 |
| max_return_statements | true | SCR016 |
| mutable_default_args | true | SCR017 |
| max_complexity | true | function/class complexity |

Setting a toggle to false disables that rule's findings.

| Key | Default | Rule | Meaning |
|---|---|---|---|
| max_parameters | 5 | SCR014 | Max positional + keyword params |
| max_nesting | 5 | SCR013 | Max block nesting depth |
| max_function_lines | 300 | SCR012 | Max function line span |
| max_class_lines | 200 | SCR010 | Max class line span |
| max_file_lines | 1000 | SCR011 | Max file line count |
| max_complexity | 40 | — | Max cyclomatic complexity |
| max_boolean_conditions | 5 | SCR003 | Max operands in one chain |
| max_if_chain | 5 | SCR007 | Max if/elif links in a chain |
| max_local_variables | 30 | SCR009 | Max distinct assigned names |
| max_return_statements | 6 | SCR016 | Max returns per function |
| max_lambda_nodes | 10 | SCR008 | Max AST nodes in a lambda body |
| max_large_comprehensions | 40 | SCR005 | Max AST nodes in a comprehension |

Limits are applied by key. A rule whose limit key is absent from the
merged config falls back to the limit hardcoded in its own module, so a
partial [limits] never turns a rule off. Every limit key in the table
above lives in DEFAULT_LIMITS and can be tuned from avouch.toml.

Two mechanisms exclude files, both matching repository-relative paths
component-wise — tests skips tests/ and tests/x.py but not
tests.py; a bare "." skips the whole repository:

avouch --ignore-path PATH— repeatable CLI flag, or
ignore_paths = ["tests", "migrations"]at the top level of- avouch.toml(must be a list; anything else raises).

CLI and TOML paths are combined and de-duplicated before analysis.
Matching is purely string-based (src/avouch/utility/is_ignored.py) —
no filesystem access.

Run avouch --verbose: when there is a review set, the first diagnostics
line reports the config source and the active ignore-path count:

avouch: config: avouch.toml, 2 ignore path(s) avouch: ignore paths: tests, migrations
Without a avouch.toml the line reads config: defaults (no avouch.toml), 0 ignore path(s). avouch --docs prints the same limits
and rule defaults for reference.

Malformed TOML (or a non-list ignore_paths) printserror: invalid avouch.toml configuration: ...on stderr and exits2.
Unknown keys are accepted and ignored silently — a typo makes the
intended setting silently ineffective, and Avouch does not warn
(--verboseshows only the file name and the ignore-path count).
Limit values are not type-checked: a non-numeric value such as
max_parameters = "eight"is not rejected and fails at analysis time with an internal error (exit2).
--ignore-pathappends to the TOML- ignore_paths(combined and de-duplicated); there is no CLI override for- [limits]or- [rules].
Configuration applies equally to every review mode — --changed,--staged, and--all-files— and to every output mode:--json,--quiet, and--verbose.
Severity is not configurable: rule findings are WARNING;ERRORis reserved for files that cannot be read or parsed.
--docsrenders the built-in documentation and exits before any configuration is read, so it is unaffected by- avouch.toml.

```

avouch.toml — the exact file this repository lives by

ignore_paths = ["tests"]
[limits]
max_parameters = 5
max_nesting = 5
max_function_lines = 300
max_class_lines = 200
max_file_lines = 1000
max_complexity = 40
max_boolean_conditions = 5
max_if_chain = 5
max_local_variables = 30
max_return_statements = 6
max_lambda_nodes = 10
max_large_comprehensions = 40
[rules]
max_parameters = true
max_nesting = true
max_function_lines = true
max_class_lines = true
max_file_lines = true
max_complexity = true
max_boolean_conditions = true
max_local_variables = true
max_return_statements = true
max_lambda_nodes = true
max_large_comprehensions = true
mutable_default_args = true
`` Avouch ships 17 rule identifiers (SCR001–SCR017) plus two cyclomatic complexity checks on functions and classes sharing themax_complexitylimit. Every rule finding is aWARNING;ERRORfindings exist only for files that cannot be read or parsed. Rules with a threshold rendermeasured/limit; presence-based rules renderdetected`.

| ID | Rule | Limit | Scope | Metric |
|---|---|---|---|---|
| SCR001 | Async without await | — | async funcs | detected |
| SCR002 | Bare except | — | funcs | detected |
| SCR003 | Boolean expression too complex | 5 | funcs, classes | N/limit |
| SCR004 | Duplicate branch | — | funcs | detected |
| SCR005 | Large comprehension | 40 | funcs | N/limit |
| SCR006 | Duplicate branch | — | funcs, classes | detected |
| SCR007 | Long if/elif chain | 5 | funcs, classes | N/limit |
| SCR008 | Lambda too complex | 10 | funcs | N/limit |
| SCR009 | Too many local variables | 30 | funcs | N/limit |
| SCR010 | Class too large | 200 | classes | N/limit |
| SCR011 | File too large | 1000 | files | N/limit |
| SCR012 | Function too long | 300 | funcs | N/limit |
| SCR013 | Nesting too deep | 5 | funcs | N/limit |
| SCR014 | Too many parameters | 5 | funcs | N/limit |
| SCR015 | Nested function definition | — | funcs | detected |
| SCR016 | Too many return statements | 6 | funcs | N/limit |
| SCR017 | Mutable default argument | — | funcs | detected |
| — | Function too complex | 40 | funcs | N/limit |
| — | Class too complex | 40 | classes | N/limit |

def transform(v):
return v.strip().lower().split(",") if "," in v else [v]
`` Flags functions assigning more thanmax_local_variables(default 30) distinct names — every new name is cognitive load and a chance for shadowing. The count covers plainx = ...assignment targets only (ast.Assignwithast.Name` targets); augmented and unpacked
assignments are not counted. Assignments inside nested functions count
toward the enclosing function's total. Fix: extract groups of
assignments into helpers.

Flags classes whose line span exceeds max_class_lines (default 200).
A class past ~200 lines is usually several classes; fix by splitting by
responsibility.

Flags files exceeding max_file_lines (default 1000). Fix: split into
modules with single concerns.

Flags functions whose line span exceeds max_function_lines (default
300). Fix: extract helpers — process_order becomes validate,
reserve, and send.

def normalize(value):
return value.strip().lower()
def process_all(data):
return [normalize(x) for x in data]
`` Flags functions with more thanmax_return_statements(default 6)return`s — every exit point is a path to maintain. Returns inside
nested functions count toward the enclosing function's total.

Flags default parameter values that are mutable — list/dict/set
literals ([], {}, {1, 2}) or mutable constructor calls
(list(), dict(), set(), bytearray(), defaultdict(),
OrderedDict()). Defaults are evaluated once at definition time, so
the same object is shared across every call that omits the argument —
state leaks between unrelated calls.

```

bad

def add_item(item, items=[]):
items.append(item)
return items

good

def add_item(item, items=None):
if items is None:
items = []
items.append(item)
return items
`` The rule inspects only the function's own defaults — a mutable default on a nested function is reported once, by that function's own finding, never duplicated in the enclosing function's report. Immutable defaults (None, strings, numbers, tuples,frozenset()`) are never flagged.

Flags functions and classes whose McCabe cyclomatic complexity exceeds
max_complexity (default 40). Base 1, then +1 for every if, for,
async for, while, try, except handler, match, ternary,
assert, with, async with, and every and/or chain — an
and/or chain counts 1 regardless of how many operands it combines,
so a and (b or c) adds 2 (one per chain). The walk covers the whole
subtree: a class's complexity is the sum over its entire body, methods
included.

The codebase is deliberately small: a CLI orchestrator, four pipeline
modules, two config modules, and one rule per file. The governing rule is
that ** cli.py only orchestrates** — every function it calls lives in
another module, and nothing imports

cli.py.Execution flow — this is the full path of a run (--docs and
--version short-circuit before configuration):

flowchart TD M["avouch.cli:main()"] --> P["argparse --json · --quiet · --verbose · --ignore-path · --changed · --staged · --all-files · --not-git"] P --> PD{"--docs?"} PD -- "yes" --> D["utility/docs.py render_docs()"] D --> X0["exit 0"] PD -- "no" --> C["config/loader.py load_config(): avouch.toml merged over defaults"] C --> G{"Git repository?"} G -- "no · without --not-git" --> EX2A["exit 2 error: no Git repository found"] G -- "yes, or --not-git" --> S{"Selection mode"} S -- "--not-git" --> F4["git.py: get_all_files_on_disk() *.py walked from CWD"] S -- "--all-files" --> F3["git.py: get_all_files() git ls-files"] S -- "--staged" --> F2["git.py: get_staged_files() git diff --cached --name-only"] S -- "default" --> F1["git.py: get_changed_files() git diff HEAD --name-only + untracked"] F1 --> R["git.py: get_reviewable_files() existing .py · not generated · not ignored"] F2 --> R F3 --> R F4 --> R R -- "none left" --> EX2B["exit 2 error: nothing to review"] R -- "files" --> A["analyzer.py: analyze_file() read file → ast.parse → walk cache → rules"] A --> O{"Output mode"} O -- "--json" --> J["report.py: render_json()"] O -- "--quiet" --> Q["no report"] O -- "default + --changed" --> DIF["report.py: render_diff_view() git diff of the review set"] O -- "default" --> H["report.py: generate_report() terminal report"] J --> E{"Any findings?"} Q --> E DIF --> E H --> E E -- "no" --> EX0["exit 0"] E -- "yes" --> EX1["exit 1"]
Module dependencies — what imports what (each arrow is a real import):

flowchart LR CLI["cli.py orchestration only"] -->|load_config, DEFAULT_RULES| CFG["config/loader.py"] CLI -->|DEFAULT_LIMITS| DEF["config/default.py"] CLI -->|review-set computation| GIT["git.py"] CLI -->|analyze_file| AN["analyzer.py"] CLI -->|render_json · render_diff_view generate_report · vlog| REP["report.py"] CLI -->|render_docs| DOC["utility/docs.py"] CFG --> DEF AN --> RULES["rules/*.py one analyze(node, limits) per rule"] AN --> COM["rules/complexity.py calculate_complexity"] RULES -->|walk| WAL["utility/walk.py cached ast.walk, reset per file"] GIT --> IG["utility/is_generated.py"] GIT --> II["utility/is_ignored.py"] REP -->|get_file_diff| GIT
| Module | Role | Key exports |
|---|---|---|
| cli.py | Pipeline wiring | main() |
| docs.py(inutility/) | Built-in --docstext | DOCS |
| git.py | Git interaction | is_gitrepo,get_changed_files,get_staged_files,get_reviewable_files |
| analyzer.py | AST analysis | read_file,analyze_file |
| rules/*.py | One rule per module | analyze(node, limits) |
| utility/walk.py | Cached AST traversal | walk,reset_walk_cache |
| report.py | Terminal + JSON rendering | render_report,generate_report,render_json |
| config/default.py | Default limits | DEFAULT_LIMITS |
| config/loader.py | TOML load + merge | load_config,merge_limits,merge_rules,DEFAULT_RULES |

cli.main()loads config (- limits+- rulesmerged over defaults).
git.is_gitrepo()—- git rev-parse --is-inside-work-tree; exits the run with a message if not a repo.
git.get_changed_files()—- git diff HEAD --name-onlyplus untracked files;- git.get_staged_files()—- git diff --cached --name-only— is used with- --staged;- get_reviewable_files()keeps existing- .pypaths that are neither generated (- is_generated) nor covered by ignore paths (- is_ignored); if none remain, prints a message and exits- 2.
Per file, analyzer.analyze_file(path, limits, rules):- reads UTF-8 (OSError→ERRORreport), parses withast.parse(SyntaxError→ERRORreport; the rest of the run continues),
resets the walk cache (utility/walk.py), then walks the AST, dispatchingFunctionDef,AsyncFunctionDef, andClassDefnodes to their rules (rule toggles are checked before dispatch, so disabled rules never run),
returns (function_reports, file_reports, class_reports).
reads UTF-8 (
report.render_report(...)groups issues by file in a single pass and renders the- AVOUCHheader, per-file findings, the BY RULE summary, and the- [PASSING]grid.

cli.py with --docs short-circuits before config loading and calls
docs.render_docs(), so no Git or analysis code runs. In a TTY that
renders an interactive browser over docs.DOCS; piped stdout prints
the plain text.

Terminal rendering is hand-rolled ANSI in src/avouch/report.py — the
rich dependency declared in pyproject.toml is not imported. Colors
are emitted only when stdout is a TTY; piped output is plain. Each
finding renders compiler-style: a file:line header with rule id and
message, the offending code region with dimmed line numbers, and a
caret under the flagged name. Identical (component, rule) findings
are deduplicated per file, and the BY RULE summary counts deduplicated
findings, sorted most common first. The [PASSING] grid collapses to
at most a few lines, with a [+N more] note when it overflows.
AVOUCH_FONT=name is an opt-in OSC 50 font switch honored only by
capable terminals.

avouch/ ├── pyproject.toml # packaging, console script ├── avouch.toml # limits this repo lives by ├── src/avouch/ │ ├── cli.py # entry point; orchestration only │ ├── git.py # review-set computation │ ├── analyzer.py # AST walk, rule dispatch │ ├── report.py # terminal report UI │ ├── rules/ # one module per rule │ │ ├── complexity.py # cyclomatic metric (no issues itself) │ │ ├── max_nesting.py # get_depth + BLOCK_NODES │ │ └── ... # one analyze(node, limits) per rule │ ├── utility/ │ │ ├── walk.py # cached ast.walk + per-file cache reset │ │ ├── docs.py # --docs terminal documentation text │ │ ├── is_generated.py # generated-file patterns │ │ └── is_ignored.py # ignore-path matching │ └── config/ │ ├── default.py # DEFAULT_LIMITS │ └── loader.py # load_config, merge_limits, merge_rules └── tests/ └── test_git.py # 74 tests, incl. a real-git end-to-end run
A rule is a module in src/avouch/rules/ exposing
analyze(node, limits) -> list[issue], where an issue is:

{"rule": "SCR017", "severity": "WARNING", "message": "Description (value/limit). Remediation guidance."}
Plus a [rules] toggle in DEFAULT_RULES (and a limit in
DEFAULT_LIMITS if the rule has a threshold). Wire the dispatch into
analyze_file with a toggle guard, then write the tests: one for the
violation, one for the boundary. The renderer displays any
(severity, message) pair it receives, so no report code changes.

All 74 tests run in a fraction of a second — no network, no package installs:

pip install -e . python -m pytest tests/
Coverage includes the git helpers, config merging, every nesting block
type, every complexity decision point, boolean-chain measurement,
rule boundaries, analysis failure paths (unreadable/syntax-error files),
report output, the --docs flag (asserted to exit cleanly without
touching Git, inside or outside a repository), and an end-to-end run
against a real temporary git repository — Git itself is not mocked.
Mocking is limited to subprocess.run where a real Git isn't needed.

The detailed implementation plan for the next release lives in
roadmap.md — v0.3.3 ships eight new capabilities under the
theme "first run clean, every run relevant" (avouch init, a findings
baseline, parallel review, CI-native output formats, rule man pages, a
pre-commit hook, and inline diff annotations).

Beyond v0.3.3, informed by documented limitations, ordered by the pain they remove:

0.4 — Configuration hardening

Validate avouch.tomlvalues with readable errors (today: a malformed file raises)
Search upward from the working directory for avouch.toml(today: CWD only)

1.0 — CI-grade interface

Configurable exit codes, so enforcement thresholds can be tuned without changing avouch's review-only default

New rules must survive the philosophy section — the ceiling is raised deliberately, not by accretion.

Why only changed files?
Pre-existing issues are noise. A whole-repo run buries the few findings
you introduced under hundreds you didn't. The review set is the diff, so
the output is always relevant to the next push.

Why git diff HEAD and not git diff?
Plain

git diff covers only unstaged changes. HEAD covers staged plus
unstaged — the complete set of files about to be pushed — and avouch adds
untracked files on top, so brand-new files are never missed.Why AST instead of regex?
Regex cannot count parentheses across lines, measure nesting, or
distinguish a definition from a call. The AST answers structural
questions exactly for every valid Python file.

What are the exit codes?
Avouch returns 0 when the review is clean, 1 when findings are
reported, and 2 when Avouch cannot run. It still reviews rather than
gates — enforcement stays in whatever calls it — but CI can now react to
the outcome directly.

Does it need a network or a daemon?
No. Three git subprocess calls and the standard library. Runtime is
bounded by the size of your diff, not your repository.

Tests before code.A fix that cannot be expressed as a failing test first is not a fix yet.
Keep the diff small.A change that touches more than two modules needs a justification in the PR description.
The standard-library runtime is the contract.No new runtime dependencies without a written case that survives the philosophy section.
The README is the spec.If the behavior changed, the README changes in the same commit.

Setup:

git clone https://github.com/mukundzha/avouch.git cd avouch pip install -e . python -m pytest tests/
MIT — see LICENSE.

Newspaper

Show HN: I canceled my AI code reviewer and wrote a free local one

... make a change ...

avouch.toml — the exact file this repository lives by

bad

good

bad

good

bad — 6 operands

good

bad

good

bad

good

bad

good

bad

good

bad — 5 deep

good — early-return guards flatten it

bad

good

bad

good

bad

good