Pular para conteúdo

AUR-431 — aurumcode review --fail-on: break the build on a grave finding

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

aurumcode review --base <ref> --fail-on <level> turns the AUR-430 review into a CI gate: the command exits with the distinct code 3 when the review reports at least one finding at the chosen severity or above, and 0 when no finding reaches the threshold. Without --fail-on, nothing changes: the command behaves exactly as documented in docs/specs/AUR-430.md, and findings never influence the exit code.

Command

aurumcode review --base <ref> [--fail-on <level>]
Flag Required Meaning
--base <ref> yes Unchanged from AUR-430: the ref to diff against HEAD.
--fail-on <level> no Minimum severity that closes the gate. When any finding sits at this severity or above, the command exits 3 after printing its normal output.

Levels

The review engine emits exactly three severities — error, warning, info (internal/prompt/parser.go rejects anything else). --fail-on accepts those names directly, plus the CI-conventional aliases high, medium and low. Matching is case-insensitive.

--fail-on value Gates on
high or error error only
medium or warning warning and error
low or info info, warning and error

Any other value — including an explicitly empty one (--fail-on=, or --fail-on "$VAR" with VAR empty in CI) — is a usage error: the command exits 2 before reviewing anything, never a silently-open gate.

Exit codes

Code Meaning
0 The review ran; no finding reached the --fail-on threshold (or no --fail-on was given).
1 A real failure, unchanged from AUR-430: not a git repository, the ref does not resolve, the LLM call failed, or the response could not be understood.
2 Usage error, unchanged plus one case: unknown subcommand, review without --base, or an unknown --fail-on level.
3 The gate closed: the review ran fine and found at least one issue at or above the --fail-on severity.

3 is deliberately distinct from 1 so a pipeline can tell "the review found a grave problem" (block the merge, show the findings) apart from "the review tool itself broke" (fix the pipeline).

Output

stdout is byte-identical with and without --fail-on: the same notices and findings, in the same sorted order, as specified by AUR-430. When the gate closes, one explanatory line goes to stderr:

aurumcode review: 1 finding(s) at severity error or above (--fail-on error)

The stderr note names the canonical engine severity (error, warning, info) regardless of which alias the user typed. Repeating the run over the same input produces the same output and the same exit code.

Example (no secrets)

Fully offline, deterministic, no network and no credentials — the model response is pinned to a file via AURUMCODE_LLM_FIXTURE (see AUR-430's provider selection):

$ cat /tmp/response.json
{
  "issues": [
    {
      "file": "config/demo-tokens.txt",
      "line": 4,
      "severity": "error",
      "message": "A credential-shaped value was committed in plain text (DEMO_API_TOKEN)."
    }
  ],
  "summary": "The change commits plaintext credential-shaped values."
}
$ cd tests/fixtures/repos/git-demo/repo.git
$ AURUMCODE_LLM_FIXTURE=/tmp/response.json aurumcode review --base HEAD~1 --fail-on high
config/demo-tokens.txt:4: [error] A credential-shaped value was committed in plain text (DEMO_API_TOKEN).
aurumcode review: 1 finding(s) at severity error or above (--fail-on error)
$ echo $?
3
$ AURUMCODE_LLM_FIXTURE=/tmp/response.json aurumcode review --base HEAD~1 --fail-on high; echo $?   # info-only response instead: exit 0

A typical CI step is then just:

aurumcode review --base "origin/${BASE_BRANCH}" --fail-on high

Failure diagnosis

  • Exit 3, findings printed — working as intended: a finding at or above the threshold closed the gate. Read the findings on stdout and the count on stderr.
  • Exit 2, --fail-on: unknown level ... — the level is not one of high|error, medium|warning, low|info. Fix the spelling; the gate never guesses.
  • Exit 1 — the review itself failed before any gating; diagnose it exactly as for AUR-430 (repository, ref, provider configuration, parser).
  • Exit 0 but you expected 3 — check the threshold: a warning finding does not close a --fail-on high gate. Rerun with --fail-on medium or low to gate on lower severities.

MUT-001 note

The skeptical mutation for this card downgrades the severity every finding presents to the gate (severityRank(issue.Severity) → severityRank(issue.Severity[:0]+"info") in cmd/aurumcode/main.go's countAtOrAbove — the slice keeps the mutant compiling): the gated command then exits 0 again and the acceptance fails. The mutation is applied only to a scratch staged copy inside tests/acceptance/AUR-431.sh::mutation_case; the committed source contains no mutation hook, and the unmutated binary reproduces the exact GREEN in the same run.

Scope

This card changes only cmd/aurumcode (flag parsing, severity ranking and the exit-code gate). The review pipeline — analyzer, prompt, parser, reviewer, providers — is byte-untouched, and every contract published by AUR-430 (output format, existing exit codes, provider selection) holds verbatim.