Skip to main content

Review a bounded code change

Collect findings for commits, staged changes or selected files. Check analysis coverage, graph freshness and report contents before a review decision.

User Guides

The review CLI collects findings for a commit comparison, staged changes, or selected files. The report gives the reviewer source locations, finding categories and severity, and graph status. Compare this evidence with the change and test results, then make the review decision.

Before you start

Prepare the Python environment and local configuration using the CLI guide. Run the commands below in PowerShell from the CodeGraph repository root. You need an existing CPG for the repository and an accessible GoCPG gRPC service.

Replace the quoted placeholders with the CPG path, Git ref, repository-relative source paths, and your chosen output paths. Create the output directory first. Use a new output filename so that a failed run cannot be mistaken for an earlier report.

Choose one review scope

Compare the base ref with the current HEAD commit. This mode does not include uncommitted working-tree changes:

python -m src.cli review --db "<cpg-path>" --base-ref "<git-ref>" --format markdown

Review staged changes:

python -m src.cli review --db "<cpg-path>" --staged --format json --output-file "<report.json>"

Review named files:

python -m src.cli review --db "<cpg-path>" --files "<file-one>" "<file-two>" --format sarif --output-file "<report.sarif>"

The current choices are --format {markdown,json,sarif}. Use python -m src.cli review --help to verify flags for the installed release.

Choose one selector. If you pass several, --files takes precedence over --staged, which takes precedence over --base-ref for quality findings. Security analysis runs only when --base-ref is present and --no-security is absent. Staged or file-only review therefore does not run the security scan, even without --no-security.

Use --output-file for a machine-readable JSON or SARIF file: standard output also contains progress messages. --sarif-file writes an additional SARIF file only when the main format is not sarif.

Read the result

  1. Confirm the base/target revision and actual changed files.
  2. Check each finding’s source location, category, severity, and rationale.
  3. Separate a candidate from a verified defect; reproduce high-impact findings.
  4. Record false positives and unresolved evidence gaps.
  5. Run the repository’s own tests and policy checks before deciding.

--no-security selects code-quality review. Record the selected scope, findings and test results in the review materials so the reviewer can assess the change.

Exit status 1 can mean a pipeline or output error, or critical/high findings in a completed report. Status 0 means no critical/high findings were reported; medium/low findings and degraded analysis can still be present. For JSON, inspect metadata.status, metadata.degradation_reasons, metadata.changed_file_paths, and metadata.freshness, as well as findings. Confirm that the new output file exists and parses.

Query or security-analysis failures can leave an empty findings list. An invalid base ref can also produce an empty changed-file list. Read the warnings and verify the Git comparison separately; an empty list is insufficient evidence of a clean review.

The local review_pipeline.auto_reparse setting controls graph updates. Its default value, prompt, defers the update. Set it to auto to update through GoCPG when the graph is available and its lag exceeds review_pipeline.stale_threshold_commits (default: 0). In JSON, check metadata.refresh.required, metadata.refresh.attempted, and metadata.refresh.status. After a successful update, review checks graph freshness again and records it in metadata.freshness.

metadata.freshness.fresh indicates whether changes since the graph was built affect files included in the CPG. commits_behind counts commits between the graph revision and HEAD. The graph can therefore have fresh=true with a nonzero commit lag when its included files have not changed. Compare the graph scope with the files in the current review.

Read JSON in PowerShell

After running a command with --format json --output-file "<report.json>", use the same report path here:

$report = Get-Content "<report.json>" -Raw | ConvertFrom-Json
$report | Select-Object project_name, base_ref, total_findings | Format-List
$report.metadata | Select-Object status, changed_file_paths, degradation_reasons, freshness | Format-List
$report.findings | Select-Object file, line, type, severity, message | Format-List

The first output shows the project, base revision and finding count. The next shows analysis status, selected files, degradation reasons and graph freshness. The final list shows each finding’s file, line, category, severity and message. For selected-file review, base_ref is empty; compare changed_file_paths with the --files arguments. With an empty findings array, the findings list is empty too; the scope and analysis status remain in metadata.

Recovery

  • Empty diff: verify the base ref, staged state, and file selectors.
  • Stale project evidence: refresh the project before accepting graph-backed findings.
  • No CPG database found: pass the correct --db path; the CLI does not discover it automatically.
  • Unsupported output: check live --help and use an available format.
  • Timeout or partial result: preserve warnings and rerun only after correcting the cause or narrowing the scope.

Reference material

Configure automatic change reviews using the hook guide.

Report a documentation issue