Run a CPG-backed project audit

A CPG (Code Property Graph) connects program elements, calls, and data flows. CodeGraph uses these relationships to audit the project.

CodeGraph 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 to assess a project, inspect recurring defects, and compare audit results. Use the report to select code for review, then check that code against the project’s security and architecture rules.

Prepare the project

Use the installed CodeGraph Python environment and a running GoCPG service. First import the project and verify that its CPG matches the source revision you want to audit.

Run the command from the CodeGraph installation directory containing config.yaml. The audit resolves the project by its CPG path in projects.registry. For a Python project, the corresponding entry has this form:

projects:
  registry:
    audit_project:
      language: python
      db_path: '<CPG_DB_PATH>'
      source_path: '<PROJECT_ROOT>'

Use the existing project’s name, language, CPG path, and source root. Keep the other settings in config.yaml. The database path in the registry must resolve to the same file as --db. --source-path selects the source root for that registered project. Create a writable output directory before running the command.

Choose the audit depth

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 standard audit in PowerShell from the CodeGraph installation directory:

python -m src.cli audit --db "<CPG_DB_PATH>" --source-path "<PROJECT_ROOT>" --profile standard --format json --output "<AUDIT_OUTPUT_PATH>" --skip-llm-conclusion --skip-persistence
if ($LASTEXITCODE -ne 0) { throw 'Audit failed' }

Use the installed CodeGraph Python environment, and replace the three quoted placeholders with the configured project’s CPG path, source root, and report path. The output directory must exist and be writable. --skip-persistence disables audit-projection writes. The initial freshness check requires a fresh CPG; the command writes the requested report file when the audit succeeds. Open the specified JSON file after the command succeeds. If the command fails, stop before reading the report: the same path may still contain a file from an earlier run. A stale graph produces audit_cpg_refresh_required. Refresh the project through project import and repeat the same audit command.

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:

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. Track application defects, detector errors, and analysis gaps separately so each has a clear next action.

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.

Review the queue and select changes to evaluate. Agree on the fix and release criteria with the project owner, then test the benefit of the change. A trial with too little evidence is labelled inconclusive; CodeGraph retains the existing baseline until a fixed evaluation meets its declared criteria.

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.

Automatic audits on a schedule

A project administrator configures a regular composite audit in the project catalog’s Schedules section. CodeGraph stores the project action settings, and Temporal starts the action according to its cron expression. You need project access, an administrator or write permission, a connected Temporal service with a worker, and an approved service account for audits. Obtain that account’s identifier from your installation administrator.

1. Open the project catalog, select the project and its Schedules section. Switch to Planning and select Create schedule.
2. Choose Composite audit (audit_composite). Enter the owner and service account identifier.
3. Set the cadence and time zone. For example, 30 2 * * * with Asia/Yekaterinburg runs daily at 02:30 in Yekaterinburg. Coordinate this time with other project audit windows: the server checks active windows for overlap.
4. Choose the missed-run policy: Skip (skip), Run once (run_once) or Catch up (catch_up). Catch up uses bounded replay; the current limit is one missed run.
5. Enable the schedule and select Create dashboard snapshot if you need a report in the dashboard. Click Create to confirm the settings and create the schedule.
6. Check the orchestrator schedule ID, status and next run time. Select Run now to check the configured action without waiting for cron. This starts a real audit of the selected project.
7. Open Run history. Wait for the job to finish, then open the audit artifact. If you enabled the dashboard snapshot, check that output too. Compare the project, code revision, analysis scope and findings with the job settings. If the run is blocked, read its reason in the run details.

To change the cadence, select the existing schedule, edit its cron expression or time zone and save it. Pause stops subsequent scheduled runs; Resume enables them again. Check the updated state and next run time.

The configuration value analysis.full_scan_interval_days sets the interval used to track whether a full analysis is due. Configure automatic execution separately in the project action schedule.

For API automation, use the schedule routes in the REST API: create and list /api/v1/traceability/projects/{project_name}/scheduled-actions; submit run_now, pause or resume to /api/v1/traceability/projects/{project_name}/scheduled-actions/{schedule_id}/commands.