Code Review Partner

Code Review Partner is a local, provider-neutral CLI for reviewing unified diffs. It turns a balanced clean-code policy into two useful artifacts:

• deterministic signals that point a reviewer toward concrete lines; and
• a self-contained packet for an optional human or AI second pass.

It does not call a network service, store source code, collect telemetry, or declare that code is “clean.” The first release is intentionally small and inspectable.

Alpha software: use the output as review leads, not as an approval gate.

Why this exists

Clean-code ideas are valuable when they help people communicate intent, control complexity, expose failures, and change behavior safely. They become brittle when a numeric preference or design slogan is applied without context.

This project keeps the useful questions and makes the tradeoffs explicit. A review can favor focused code while accounting for locality, abstraction cost, repository idiom, data layout, measured performance, and the cost of delaying a change.

Quick start

Python 3.11 or newer is required.

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
git diff --staged | review-partner analyze -

You can also run directly from a checkout without installing:

PYTHONPATH=src python3.11 -m code_review_partner analyze examples/sample.diff

JSON output is stable enough for local tooling:

review-partner analyze change.diff --format json -o review.json
review-partner validate review.json
review-partner render review.json

Existing output files are preserved unless --force is supplied. The CLI also refuses user-writable symlink components in an output path.

Optional second-pass packet

Build a Markdown packet to inspect and paste into a reviewer of your choice:

review-partner packet change.diff -o review-packet.md

Or create structured JSON:

review-partner packet change.diff --format json -o review-packet.json

The packet includes the entire diff. The CLI sends nothing, but sharing the packet can send proprietary or sensitive code to another system. Inspect it and understand that system's data terms first.

What the deterministic pass checks

The initial rules detect a deliberately narrow set of review-surface signals:

• possible credential literals, with every matched non-placeholder value on the line redacted from finding output;
• bare or apparently swallowed exceptions;
• shell interpretation and mutable Python defaults;
• unusually long lines, deep control-flow indentation, and wide signatures;
• comments that resemble disabled code, unresolved work markers, and large diffs.

The latter group is emitted as low-severity or low-confidence guidance. Thresholds are attention controls, not universal definitions of good code.

The finding contract

Every finding has a path and line when one is available, a category, severity, confidence, observed evidence, likely impact, a small suggested action, and a counter-consideration. Style preferences are non-blocking unless a project policy makes them requirements.

“No signals” means only that these rules found nothing in the changed text. It is not a correctness, security, performance, or maintainability verdict.

Project map

• Review constitution
• How it works
• Privacy and threat model
• Limitations
• Policy authoring
• Research basis and reference-only bibliography
• Contributing, security reporting, and license

Development

The runtime has no third-party Python dependencies. Run the test suite with:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3.11 -m unittest discover -s tests -v

Status and license

Version 0.1.0 is a local-first alpha. The project is research-informed but has not been empirically validated as a review-accuracy intervention.

New project material is licensed under Apache-2.0. Referenced works remain the property of their respective authors and publishers; their content is not redistributed here.