Review Rules

Review Rules

The diff decides whether a critic runs, not the ticket. needs-review.sh prints one line per rule the change fires. Any output means a full review.

needs-review.sh            # against origin/HEAD, then origin/main, then origin/master
needs-review.sh develop    # against another base

It is advisory and always exits 0.

The rules file

Rules live in your repository at .lean/needs-review.rules. Start from examples/needs-review.rules in the plugin. Each rule is an INI section.

[secrets]
label   = secrets, tokens or credentials touched
added   = (?i)(secret|token|password|api[_-]?key|private[_-]?key)

[schema]
label = schema or migration touched
path  = (?i)(^|/)(migrations?|schema|db/)|\.sql$

Key	Meaning
label	What the output line says
path	Regex over the repo-relative path. Alone, the rule fires when a changed file matches. With added or removed, it only limits which files those apply to.
added	Regex over added lines
removed	Regex over removed lines, for a test that loses an assertion

All regexes are Python syntax, matched with search. Sections sharing a label print as one line, which is how a rule says "this path, or this kind of line".

Categories that transfer

The patterns are specific to a codebase. The categories are not:

• authentication and permissions
• anything anonymous
• raw SQL
• schema and migrations
• secrets and logging
• concurrency and background work
• deletion and retention
• build and dependency files
• a test file that removes assertions

Docs, additive fields and assertion-only test additions fire nothing.

Every rule should trace to a defect that reached review. When one stops firing on anything real for several batches, delete it. When a reviewer keeps finding the same thing and no rule names it, add one.

What it compares

The working tree against the merge base with the base branch, with untracked files folded in as new files. A rule that reads only committed changes misses the file an agent has written and not yet added.

That also means running it in a checkout full of unrelated work walks all of it. Run it in a clean copy of the branch.

It never looks quiet when it could not run

No rules file, no rules in the file, or no merge base each print a line on stdout. A check that could not run must not look like a change that fired nothing. The count of files examined goes to stderr, and the rules file itself is never scanned.

Without a gate script

The critic falls back to a fixed list: a full review if the diff touches any of the categories above.