Codebase Audit

Overview

AutoAudit analyzes your trace graph (nodes, edges, augmentations, epistemic enrichment, modules, and atlas) to produce structured findings and optional LLM-generated reports. It runs as an independent tool — not a pipeline stage — so you trigger it when you want insights, not on every file change.

AutoAudit V2 transforms SourcePrep from a "passive observer" into an "active taskmaster". Findings are categorized into flat tabs (Architecture, Quality, Coverage, Tech Debt), prioritized, and include concrete actionable items. You can select findings and click "Copy AI Command" to instantly hand off the context assembly to your AI via MCP.

Quick Start

CLI

Audits are triggered via the MCP prep_audit tool, the REST API, or the dashboard's Audit panel — not a direct CLI command. To read findings from the most recent run from a terminal, use prep opportunities:

# List actionable findings from the latest audit
prep opportunities

# Filter by minimum priority
prep opportunities --priority P1

# Export as SARIF for CI ingestion
prep opportunities --format sarif

# Pipe a high-priority subset to an AI agent prompt
prep opportunities --priority P0 --format ai_prompt

What a PR-sanity audit looks like when an agent calls prep_audit mid-review.

MCP Tool

One MCP tool, prep_audit, exposes all audit functionality across Cursor, Windsurf, Claude Code, and any MCP-compatible editor. The behavior is selected via the action parameter:

Findings can also be passed in via the findings parameter to enrich external lint output (ruff, eslint, semgrep, SARIF) with structural context — see the Audit Enrichment guide.

REST API

Built-in Analyzers

AutoAudit ships with 11 analyzers. Each reads the trace graph and produces structured findings — no LLM, no side effects.

Generated Reports

When you run with --synthesize (or synthesize: true in the API), an LLM generates 5 markdown documents from the findings:

• AUDIT_SUMMARY — Health grade (A–F), critical findings, top recommendations
• ARCHITECTURE_ANALYSIS — Module dependency flow, bottlenecks, boundary violations
• GAP_ANALYSIS — Misplaced concerns, duplicated logic, missing abstractions
• COMPONENT_INVENTORY — Every file with purpose, module, summary, in-degree
• TECH_DEBT_REPORT — Debt items by module with remediation roadmap

Output Location

All audit output is stored inside the project's index directory:

# Standalone mode (default):
~/.local/share/sourceprep/projects/{project-id}/audit/
  ├── findings.json            # Raw structured findings
  ├── audit_manifest.json      # Run metadata (timestamps, counts)
  ├── AUDIT_SUMMARY.md         # LLM-generated (if synthesized)
  ├── ARCHITECTURE_ANALYSIS.md
  ├── GAP_ANALYSIS.md
  ├── COMPONENT_INVENTORY.md
  └── TECH_DEBT_REPORT.md

# Embedded mode:
/path/to/project/.sourceprep/audit/
  └── (same files)

These files are also indexed by SourcePrep's search engine, so you can query them via prep_search (e.g., "what tech debt exists in the auth module?").

Settings

Audit behavior is configurable via the dashboard Settings panel or the audit_config section in ui_config.json:

Pipeline Connection

AutoAudit is not a pipeline stage. It's an independent tool that reads the same data the pipeline writes. The connection:

1. The enrichment pipeline runs to completion and produces trace_nodes, trace_augmented, trace_epistemic, trace_modules, and atlas.json.
2. You run prep audit when you want insights. The audit reads all that data and produces findings + reports.
3. If auto_run_after_deep is enabled, Tier 1 analyzers run automatically when deep enrichment completes.
4. Audit reports are indexed by SourcePrep's search engine and served via MCP, so your AI tools can access them.