Skip to main content

Run a CPG-backed project audit

Choose an audit depth, read the evidence-aware Q1-Q12 result, and investigate recurring defect findings without accepting a false green result.

User Guides

CodeGraph now uses one audit pipeline for command-line, dashboard, scheduled, scenario, export, and history consumers. The selected profile changes the depth of analysis. It does not switch to a second audit engine.

Use this guide when you need to assess a project, inspect recurring defect patterns, or compare two compatible audit results. The report helps direct a review. It does not replace security or architecture release gates.

Choose the audit depth

Choose the audit depth
Product mode CLI profile Scope and cost Use it for
quick ci_fast Changed files plus the declared dependency closure; bounded syntax, symbols, CFG, and critical rules. Pull requests and short feedback loops.
standard standard Full project basis with architecture, data flow, and quality metrics. Regular project reviews and comparable baselines.
deep deep_security Standard analysis plus alias-sensitive, field-sensitive, and feasibility checks within an explicit budget. Confirmation of difficult security or data-flow findings.

tests_light is a GoCPG scope profile, not a fourth project-audit mode. A quick run also needs a real delta basis. Without one, CodeGraph reports the missing scope instead of assigning a project-wide score.

Run a deterministic standard audit from the repository root:

python -m src.cli audit --db <cpg.duckdb> --source-path <project-root> --profile standard --format json --output <audit.json> --skip-llm-conclusion --skip-persistence

The database must belong to a configured project. --skip-persistence keeps the run read-only with respect to audit projections, but CPG freshness checks may still update a stale project graph. Use a disposable or governed project database when that write is not acceptable.

Read the canonical result

Inspect quality_assessment before any compatibility fields:

  • pipeline_id identifies unified_audit_pipeline.v1;
  • model_version identifies the scoring definition;
  • mode and basis identify the analysis scope and revision;
  • factors contains Q1 through Q12, their status, score, coverage, and limitations;
  • score_eligible says whether an overall score may be calculated;
  • overall_score is nullable and remains absent when required evidence is incomplete;
  • release_authority is always false for the quality assessment.

Historical reports can contain legacy section and overall scores. CodeGraph keeps those values as labelled compatibility data. They do not override an unavailable canonical assessment and are not silently recalculated with a new model.

Each evidence contribution has one primary quality factor. Cross-references may show the same risk in other sections, but they do not apply the same penalty twice. See Dashboard score methodology for the factor definitions and scoring contract.

Recurring defect findings

The unified report can qualify three recurrent defect classes:

Recurring defect findings
Class Evidence needed for a finding When CodeGraph reports an analysis gap
Magic number AST context, symbol or call role, and the applicable policy. The constant cannot be classified safely or the language context is unsupported.
Swallowed exception Error-flow evidence that a failure outcome is discarded instead of propagated, handled, or deliberately converted. The call graph or language error-flow model is incomplete.
SQL/schema mismatch Parsed SQL, an executable call witness, engine ownership, schema identity, bind contract, and result contract. SQL is dynamic, the owning schema is unknown, or parsing and schema evidence do not cover the statement.

A scanner candidate is not automatically an application defect. Each result is classified as a confirmed finding, a supported non-finding, an unsupported case, or an analysis gap. A false positive belongs in the detector backlog; a missing witness belongs in analysis coverage. Neither should be hidden by changing an application suppression file.

When you fix a confirmed issue, record one of the bounded dispositions: application_fix, detector_fix, approved_defer, or evidence_gap. Repeat the applicable audit mode against the same comparison basis and keep the old result immutable.

Metric diagnostics

Method and class diagnostics are versioned. A metric record includes its definition digest, language profile, unit, entity identity, source and CPG revision, completeness status, and witnesses. Unsupported or unmeasurable values remain null; they are not converted to zero.

Percentiles are meaningful only inside a compatible cohort with a recorded membership digest and sufficient sample size. Rename, move, split, merge, model drift, or definition drift may break a direct comparison. Top-ranked Halstead or complexity values are advisory review signals, not automatic refactoring orders and not estimates of hours or cost.

Intervention queue

The report may include intervention_prioritization.v1. It groups compatible signals by stable entity and structural cause, then keeps priority, urgency, readiness, and confidence separate. The queue is bounded and can be empty.

Human review remains mandatory. The queue cannot modify source code, open an accepted release gate, or claim a causal benefit. A trial with too little evidence is labelled inconclusive; CodeGraph retains the existing baseline until a frozen evaluation meets its declared guardrails.

What blocks a clean interpretation

Stop before using the score when any of these conditions is present:

  • the CPG is stale, partial, or bound to another revision;
  • a required capability or eligible-population denominator is missing;
  • a detector reports unsupported or unresolved evidence;
  • the audit mode, model version, definition digest, project scope, or cohort is incompatible with the comparison;
  • score_eligible is false or overall_score is null.

Fix or regenerate the missing evidence, then rerun the same entry point. An exit code of zero, an empty finding list, or a legacy numeric score does not repair an incomplete canonical result.

For architecture-specific YAML policies, see Architecture control in CodeGraph. GoCPG loads project invariants only from the explicitly selected policy and release control files; the analyzer does not infer CodeGraph-specific rules for another project.

Report a documentation issue