code-auditor-mcp 3.1.0 → 3.4.0

package/dist/cli.js

@@ -18,6 +18,7 @@ import { CodeMapGenerator } from './services/CodeMapGenerator.js';
 import { initParsers } from './languages/index.js';
 import { queryParser } from './search/QueryParser.js';
 import { CodeIndexDB } from './codeIndexDB.js';
+import { createBaselineFromFindings, saveBaseline, loadBaseline, diffBaselines } from './baseline.js';
 // Get package.json for version info
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -37,6 +38,9 @@ program
     .option('-o, --output <dir>', 'Output directory for reports')
     .option('-f, --format <format>', 'Report format: html, json, csv, or sarif')
     .option('--fail-on <severity>', 'Exit code 2 when violations at or above this severity exist')
+    .option('--full', 'Show full violation inventory (overrides default delta view when baseline exists)')
+    .option('--include-baseline', 'Evaluate baseline-known violations in --fail-on checks')
+    .option('--fail-on-regression', 'Exit code 2 when total advisory debt exceeds the baseline snapshot')
     .action(async (options) => {
     console.log(chalk.blue('🔍 Code Quality Audit Tool'));
     console.log(chalk.gray('══════════════════════════════════════════════════'));
@@ -55,10 +59,88 @@ program
             outputDirectory: options.output
         });
         const result = await runner.run();
-        console.log(`\nFound ${result.summary.totalViolations} violations`);
-        console.log(`Critical: ${result.summary.criticalIssues}`);
-        console.log(`Warnings: ${result.summary.warnings}`);
-        console.log(`Suggestions: ${result.summary.suggestions}`);
+        const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
+        const baseline = result.metadata?.baseline;
+        // ── Delta output (Spec 18 R2) ─────────────────────────────────
+        if (baseline && !options.full) {
+            const newViolations = violations.filter((v) => v.new === true);
+            const knownCount = baseline.knownCount ?? 0;
+            const fixedCount = baseline.fixedCount ?? 0;
+            const previousKnown = baseline.previousKnownCount ?? 0;
+            const currentDebt = newViolations.length + knownCount;
+            const debtDelta = currentDebt - previousKnown;
+            const trendIcon = debtDelta > 0 ? '↑' : debtDelta < 0 ? '↓' : '→';
+            const trendLabel = debtDelta > 0
+                ? `(debt increased since last baseline)`
+                : debtDelta < 0
+                    ? `(debt decreased since last baseline)`
+                    : '(unchanged)';
+            console.log(`\n📊 Delta: +${newViolations.length} new · −${fixedCount} fixed · ${knownCount} known  ${trendIcon} ${trendLabel}`);
+            if (newViolations.length > 0) {
+                console.log(chalk.gray(`\n── New Findings (${newViolations.length}) ──────────────────────────`));
+                for (const v of newViolations) {
+                    const icon = v.severity === 'critical' ? '🔴' :
+                        v.severity === 'warning' ? '🟡' : '🔵';
+                    console.log(`${icon} ${chalk.bold(v.file)}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.message}`);
+                }
+            }
+            else {
+                console.log(chalk.green('\n✓ No new findings since last baseline.'));
+            }
+            // Debt by analyzer
+            console.log(chalk.gray(`\n── Debt by Analyzer ──────────────────────────`));
+            const analyzerCounts = {};
+            for (const v of violations) {
+                const a = v.analyzer || 'unknown';
+                if (!analyzerCounts[a])
+                    analyzerCounts[a] = { known: 0, new: 0 };
+                if (v.new === false)
+                    analyzerCounts[a].known++;
+                else if (v.new === true)
+                    analyzerCounts[a].new++;
+            }
+            for (const [analyzer, counts] of Object.entries(analyzerCounts).sort()) {
+                const newPart = counts.new > 0 ? ` (+${counts.new})` : '';
+                console.log(`${analyzer}: ${counts.known.toLocaleString()} known${newPart}`);
+            }
+            // Top files
+            console.log(chalk.gray(`\n── Top Files ─────────────────────────────────`));
+            const fileCounts = new Map();
+            for (const v of violations) {
+                const f = v.file || '';
+                fileCounts.set(f, (fileCounts.get(f) || 0) + 1);
+            }
+            const topFiles = [...fileCounts.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 5);
+            for (const [file, count] of topFiles) {
+                console.log(`${file} — ${count} finding${count !== 1 ? 's' : ''}`);
+            }
+            console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit --full')} to see all ${currentDebt.toLocaleString()} findings.`));
+        }
+        else if (!baseline) {
+            // No baseline: current behavior + hint
+            console.log(`\nFound ${result.summary.totalViolations} violations`);
+            console.log(`Critical: ${result.summary.criticalIssues}`);
+            console.log(`Warnings: ${result.summary.warnings}`);
+            console.log(`Suggestions: ${result.summary.suggestions}`);
+            console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit baseline')} to adopt the ratchet and track changes over time.`));
+        }
+        else {
+            // --full with baseline: full itemized inventory (current behavior)
+            console.log(`\nFound ${result.summary.totalViolations} violations`);
+            console.log(`Critical: ${result.summary.criticalIssues}`);
+            console.log(`Warnings: ${result.summary.warnings}`);
+            console.log(`Suggestions: ${result.summary.suggestions}`);
+        }
+        // Spec-20 R4: built-in profile visibility — silent behavior changes
+        // are never acceptable. Notify when scripts-and-tests capped findings.
+        const builtinCapped = Object.values(result.analyzerResults)
+            .reduce((count, ar) => count + ar.violations.filter(v => v.profile === 'scripts-and-tests').length, 0);
+        if (builtinCapped > 0) {
+            console.log(chalk.blue(`\nℹ️  ${builtinCapped.toLocaleString()} findings capped by built-in profile "scripts-and-tests" (scripts/tests/fixtures → suggestion).`));
+            console.log(chalk.gray(`   Set ${chalk.cyan('"builtin": false')} in .codeauditor.json to disable.`));
+        }
         // Generate formatted report if --format is specified
         if (options.format) {
             const validFormats = ['html', 'json', 'csv', 'sarif'];
@@ -74,12 +156,24 @@ program
             await fs.writeFile(reportPath, report, 'utf-8');
             console.log(chalk.green(`\nReport written to ${reportPath}`));
         }
-        // Exit code based on --fail-on
+        // ── Fail-on logic (Spec 18 R3) ───────────────────────────────
+        // --fail-on-regression: compare total advisory debt to baseline snapshot
+        if (baseline && options.failOnRegression) {
+            const currentDebt = violations.filter((v) => v.new || v.new === false).length;
+            const snapshotDebt = baseline.previousKnownCount ?? 0;
+            if (currentDebt > snapshotDebt) {
+                console.error(chalk.red(`Debt regression: ${currentDebt - snapshotDebt} findings added without re-baselining.`));
+                process.exit(2);
+            }
+        }
+        // --fail-on: evaluate new + invariant findings only (unless --include-baseline)
         if (failOnSeverity) {
-            const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
+            const evaluableViolations = (baseline && !options.includeBaseline)
+                ? violations.filter((v) => v.new || v.analyzer === 'invariants')
+                : violations;
             const severityOrder = ['critical', 'warning', 'suggestion'];
             const failIndex = severityOrder.indexOf(failOnSeverity);
-            const hasAtOrAbove = violations.some((v) => {
+            const hasAtOrAbove = evaluableViolations.some((v) => {
                 const vIndex = severityOrder.indexOf(v.severity);
                 return vIndex >= 0 && vIndex <= failIndex;
             });
@@ -101,6 +195,7 @@ program
     .option('-f, --format <format>', 'Report format: json, or sarif (overrides --json)')
     .option('--quiet', 'Suppress output when zero violations')
     .option('--fail-on <severity>', 'Exit code 2 when violations at or above this severity exist', 'critical')
+    .option('--include-baseline', 'Evaluate baseline-known violations in --fail-on checks')
     .option('--stdin', 'Read file paths from stdin (one per line)')
     .option('-p, --path <projectPath>', 'Project root path', process.cwd())
     .action(async (paths, options) => {
@@ -147,6 +242,11 @@ program
         const result = await runner.run();
         // Collect all violations
         const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
+        // Baseline classification (Spec 18 R4 — hook path)
+        const baseline = result.metadata?.baseline;
+        const knownViolations = violations.filter((v) => v.new === false);
+        const newViolations = violations.filter((v) => v.new === true || v.new === undefined);
+        const knownCount = knownViolations.length;
         // JSON output
         if (options.format === 'sarif') {
             const { generateSARIFReport } = await import('./reporting/sarifReportGenerator.js');
@@ -179,7 +279,8 @@ program
                     endColumn: v.end?.column,
                     enclosingSymbol: v.symbol || v.enclosingFunction || '',
                     suggestion: v.suggestion || '',
-                    details: v.details || ''
+                    details: v.details || '',
+                    ...(v.new !== undefined && { new: v.new })
                 };
             });
             process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
@@ -193,20 +294,30 @@ program
             console.log(`Critical: ${result.summary.criticalIssues}`);
             console.log(`Warnings: ${result.summary.warnings}`);
             console.log(`Suggestions: ${result.summary.suggestions}`);
+            // Known-finding informational line (Spec 18 R4)
+            if (baseline && knownCount > 0) {
+                console.log(chalk.gray(`\nℹ️ ${knownCount} pre-existing finding${knownCount !== 1 ? 's' : ''} in files you touched (not blocking).`));
+            }
             if (violations.length > 0) {
                 console.log(chalk.gray('\n── Violations ────────────────────────────────────'));
                 for (const v of violations) {
                     const icon = v.severity === 'critical' ? '🔴' :
                         v.severity === 'warning' ? '🟡' : '🔵';
-                    console.log(`${icon} ${chalk.bold(v.file)}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.message}`);
+                    const statusTag = v.new === false
+                        ? chalk.dim(' [known]')
+                        : '';
+                    console.log(`${icon} ${chalk.bold(v.file)}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.message}${statusTag}`);
                 }
             }
         }
-        // Exit code based on --fail-on
+        // Exit code based on --fail-on (Spec 18 R3/R4)
         if (failOnSeverity) {
+            const evaluableViolations = (baseline && !options.includeBaseline)
+                ? violations.filter((v) => v.new || v.analyzer === 'invariants')
+                : violations;
             const severityOrder = ['critical', 'warning', 'suggestion'];
             const failIndex = severityOrder.indexOf(failOnSeverity);
-            const hasAtOrAbove = violations.some((v) => {
+            const hasAtOrAbove = evaluableViolations.some((v) => {
                 const vIndex = severityOrder.indexOf(v.severity);
                 return vIndex >= 0 && vIndex <= failIndex;
             });
@@ -220,6 +331,72 @@ program
         process.exit(1);
     }
 });
+// Baseline command (Spec 18 R1)
+program
+    .command('baseline')
+    .description('Snapshot current advisory findings as the baseline (excludes invariants)')
+    .option('-p, --path <path>', 'Project path', process.cwd())
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        await initParsers();
+        const runner = createAuditRunner({
+            projectRoot: options.path,
+        });
+        const result = await runner.run();
+        // Collect all violations from analyzer results
+        const allViolations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
+        // Compute corpus stats
+        const corpusStats = {
+            files: result.metadata.filesAnalyzed,
+            functions: result.metadata.collectedFunctions?.length ?? 0,
+        };
+        // Build per-analyzer counts
+        const analyzerCounts = {};
+        for (const v of allViolations) {
+            if (v.analyzer === 'invariants')
+                continue;
+            const a = v.analyzer || 'unknown';
+            analyzerCounts[a] = (analyzerCounts[a] || 0) + 1;
+        }
+        // Create new baseline
+        const newBaseline = createBaselineFromFindings(allViolations, {
+            toolVersion: packageJson.version,
+            totalFindings: allViolations.filter((v) => v.analyzer !== 'invariants').length,
+            analyzerCounts,
+            corpusStats,
+        });
+        // Load existing baseline for diff
+        const projectRoot = resolve(options.path || process.cwd());
+        const existing = loadBaseline(projectRoot);
+        const diff = existing ? diffBaselines(existing, newBaseline) : null;
+        // Save
+        saveBaseline(projectRoot, newBaseline);
+        if (options.json) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                absorbed: diff?.absorbed ?? newBaseline.entries.length,
+                fixed: diff?.fixed ?? 0,
+                totalKnown: newBaseline.entries.length,
+                invariantsExcluded: allViolations.filter((v) => v.analyzer === 'invariants').length,
+            }, null, 2) + '\n');
+        }
+        else {
+            const absorbed = diff?.absorbed ?? newBaseline.entries.length;
+            const fixed = diff?.fixed ?? 0;
+            const totalKnown = newBaseline.entries.length;
+            console.log(chalk.green(`\n✓ Baseline updated: ${absorbed} finding${absorbed !== 1 ? 's' : ''} absorbed, ${fixed} fixed, ${totalKnown} total known.`));
+            console.log(chalk.gray('Invariants excluded (they always enforce).'));
+            if (totalKnown > 0) {
+                console.log(chalk.gray(`\nRun ${chalk.cyan('code-audit')} to see your delta view.`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
 // Generate configuration command
 program
     .command('generate-config')
@@ -351,6 +528,75 @@ indexCmd
         process.exit(1);
     }
 });
+// ── Index status command (Spec 14 R1) ──────────────────────────
+indexCmd
+    .command('status')
+    .description('Show index health and graph statistics')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const stats = await db.getStats();
+        // Graph stats — non-fatal if graph cache is empty
+        let graphStats = null;
+        try {
+            graphStats = db.getGraphStats();
+        }
+        catch {
+            // No graph data yet — ok
+        }
+        if (options.json) {
+            process.stdout.write(JSON.stringify({
+                totalFunctions: stats.totalFunctions,
+                totalFiles: stats.filesIndexed,
+                languageBreakdown: stats.languages,
+                graphStats: graphStats ? {
+                    callNodes: graphStats.callNodes,
+                    callEdges: graphStats.callEdges,
+                    unresolvedCalls: graphStats.unresolvedCalls,
+                    unresolvedShare: graphStats.unresolvedShare,
+                    importNodes: graphStats.importNodes,
+                    importEdges: graphStats.importEdges,
+                } : null,
+            }, null, 2) + '\n');
+        }
+        else {
+            console.log(chalk.blue('📊 Index Status'));
+            console.log(chalk.gray('══════════════════════════════════'));
+            console.log(`${chalk.bold('Total functions:')} ${(stats.totalFunctions ?? 0).toLocaleString()}`);
+            console.log(`${chalk.bold('Total files:')} ${(stats.filesIndexed ?? 0).toLocaleString()}`);
+            if (stats.languages && Object.keys(stats.languages).length > 0) {
+                console.log(chalk.bold('\nLanguage breakdown:'));
+                for (const [lang, count] of Object.entries(stats.languages)) {
+                    console.log(`  ${lang}: ${count.toLocaleString()}`);
+                }
+            }
+            if (graphStats) {
+                console.log(chalk.bold('\nCall Graph:'));
+                console.log(`  ${chalk.bold('Nodes:')} ${graphStats.callNodes.toLocaleString()}`);
+                console.log(`  ${chalk.bold('Edges:')} ${graphStats.callEdges.toLocaleString()}`);
+                const pct = (graphStats.unresolvedShare * 100).toFixed(1);
+                if (graphStats.unresolvedShare > 0.3) {
+                    console.log(`  ${chalk.yellow(`⚠ Unresolved: ${graphStats.unresolvedCalls.toLocaleString()} (${pct}%) — graph metrics may be incomplete`)}`);
+                }
+                else {
+                    console.log(`  ${chalk.bold('Unresolved:')} ${graphStats.unresolvedCalls.toLocaleString()} (${pct}%)`);
+                }
+                console.log(chalk.bold('\nImport Graph:'));
+                console.log(`  ${chalk.bold('Nodes:')} ${graphStats.importNodes.toLocaleString()}`);
+                console.log(`  ${chalk.bold('Edges:')} ${graphStats.importEdges.toLocaleString()}`);
+            }
+            else {
+                console.log(chalk.gray('\nNo graph data available. Run a full sync (code-audit index sync) first.'));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
 // Config command
 const configCmd = program
     .command('config')
@@ -359,6 +605,8 @@ const configCmd = program
     console.log(chalk.yellow('Use a config subcommand:'));
     console.log(chalk.gray('  code-audit config rules-list       List invariant rules from .codeauditor.json'));
     console.log(chalk.gray('  code-audit config rules-check      Validate .codeauditor.json rules'));
+    console.log(chalk.gray('  code-audit config profiles         Show active path profiles'));
+    console.log(chalk.gray('  code-audit config detection        Show DB/validator provenance and inferred receivers'));
 });
 configCmd
     .command('rules-list')
@@ -456,6 +704,282 @@ configCmd
         process.exit(1);
     }
 });
+// Config profiles subcommand — debug surface for path profiles (Spec-20 R5)
+configCmd
+    .command('profiles')
+    .description('Show active path profiles and resolve per-file matching')
+    .option('-p, --path <path>', 'Project path', process.cwd())
+    .option('--file <file>', 'Resolve profiles for a specific file')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const fs = await import('fs/promises');
+        const pathModule = await import('path');
+        const { loadConfig } = await import('./config/configLoader.js');
+        const { resolvePathProfile } = await import('./config/pathProfiles.js');
+        const projectRoot = pathModule.resolve(options.path);
+        const configPath = pathModule.join(projectRoot, '.codeauditor.json');
+        let profiles = [];
+        try {
+            await fs.access(configPath);
+            const config = await loadConfig({ configPath });
+            profiles = config.pathProfiles || [];
+        }
+        catch {
+            // No config file — use defaults only
+            const { mergePathProfiles } = await import('./config/defaults.js');
+            profiles = mergePathProfiles(undefined, undefined) || [];
+        }
+        if (options.file) {
+            // Resolve profiles for a specific file
+            const filePath = pathModule.resolve(options.file);
+            const resolved = resolvePathProfile(filePath, projectRoot, profiles);
+            if (options.json) {
+                process.stdout.write(JSON.stringify({
+                    file: options.file,
+                    resolvedFilePath: filePath,
+                    matchedProfileNames: resolved.matchedProfileNames,
+                    severityCap: resolved.severityCap || null,
+                    overrides: resolved.overrides,
+                }, null, 2) + '\n');
+            }
+            else {
+                if (resolved.matchedProfileNames.length === 0) {
+                    console.log(chalk.gray(`No profiles match: ${options.file}`));
+                }
+                else {
+                    console.log(chalk.bold(`Profiles matching: ${options.file}`));
+                    for (const name of resolved.matchedProfileNames) {
+                        const profile = profiles.find(p => p.name === name);
+                        const builtinTag = profile?.builtin !== false && profiles.some(p => p.name === name) ? '' : '';
+                        console.log(`  ${chalk.cyan(name)}${builtinTag ? chalk.gray(' (built-in)') : ''}`);
+                    }
+                    if (resolved.severityCap) {
+                        console.log(chalk.yellow(`  severityCap: ${resolved.severityCap}`));
+                    }
+                    if (Object.keys(resolved.overrides).length > 0) {
+                        console.log(chalk.gray('  merged overrides:'));
+                        for (const [key, value] of Object.entries(resolved.overrides)) {
+                            console.log(chalk.gray(`    ${key}: ${JSON.stringify(value)}`));
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            // List all active profiles
+            if (options.json) {
+                process.stdout.write(JSON.stringify({
+                    projectRoot,
+                    profiles: profiles.map(p => ({
+                        name: p.name,
+                        paths: p.paths,
+                        overrides: p.overrides,
+                        builtin: p.builtin !== false,
+                    })),
+                }, null, 2) + '\n');
+            }
+            else {
+                if (profiles.length === 0) {
+                    console.log(chalk.gray('No path profiles active.'));
+                }
+                else {
+                    console.log(chalk.bold('Active path profiles:'));
+                    for (const p of profiles) {
+                        const tag = p.builtin !== false ? chalk.gray(' [built-in]') : '';
+                        console.log(`  ${chalk.cyan(p.name)}${tag}`);
+                        console.log(chalk.gray(`    paths: ${p.paths.join(', ')}`));
+                        if (p.overrides && Object.keys(p.overrides).length > 0) {
+                            for (const [key, value] of Object.entries(p.overrides)) {
+                                console.log(chalk.gray(`    ${key}: ${JSON.stringify(value)}`));
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+// Config detection subcommand — provenance debug surface (Spec-21 R2)
+configCmd
+    .command('detection')
+    .description('Show DB-provenanced and inferred receiver identifiers with per-entry evidence')
+    .option('-p, --path <path>', 'Project path', process.cwd())
+    .option('--json', 'Output as JSON')
+    .option('--mode <mode>', 'Detection mode filter (hybrid, provenance, names)')
+    .action(async (options) => {
+    try {
+        const pathModule = await import('path');
+        const fsPromises = await import('fs/promises');
+        const { initParsers } = await import('./languages/tree-sitter/parser.js');
+        const { initializeLanguages } = await import('./languages/index.js');
+        const { LanguageRegistry } = await import('./languages/LanguageRegistry.js');
+        const { loadConfig } = await import('./config/configLoader.js');
+        const provenanceMod = await import('./analyzers/provenance.js');
+        const { buildProvenanceContext, inferReceivers, } = provenanceMod;
+        initializeLanguages();
+        await initParsers();
+        const registry = LanguageRegistry.getInstance();
+        const projectRoot = pathModule.resolve(options.path);
+        // Load config to get detection mode and analyzer settings
+        let config = {};
+        try {
+            const configPath = pathModule.join(projectRoot, '.codeauditor.json');
+            await fsPromises.access(configPath);
+            config = await loadConfig({ configPath });
+        }
+        catch {
+            // No config — use defaults
+        }
+        const detectionMode = options.mode ||
+            config?.analyzerOptions?.schema?.detection?.mode ||
+            config?.analyzerOptions?.['data-access']?.detection?.mode ||
+            'hybrid';
+        // Gather files
+        const { findFiles } = await import('./utils/fileDiscovery.js');
+        const files = await findFiles(projectRoot);
+        const provenanced = [];
+        const validatorIdentifiers = [];
+        const inferred = [];
+        // Per-file scan
+        for (const filePath of files.slice(0, 500)) {
+            const relPath = pathModule.relative(projectRoot, filePath);
+            const adapter = registry.getAdapterForFile(filePath);
+            if (!adapter)
+                continue;
+            try {
+                const sourceCode = await fsPromises.readFile(filePath, 'utf-8');
+                const ast = await adapter.parse(filePath, sourceCode);
+                if (!ast?.root)
+                    continue;
+                const schemaCfg = config?.analyzerOptions?.schema ?? {};
+                const daCfg = config?.analyzerOptions?.['data-access'] ?? {};
+                // Build provenance context using schema analyzer config (most complete)
+                const ctx = buildProvenanceContext(ast, adapter, sourceCode, {
+                    mode: detectionMode,
+                    dbReceiverNames: schemaCfg.dbReceiverNames ?? daCfg.dbReceiverNames,
+                    dbBindingNames: schemaCfg.dbBindingNames ?? daCfg.dbBindingNames,
+                    dbCallMethods: schemaCfg.dbCallMethods ?? daCfg.dbCallMethods,
+                });
+                // Collect DB-provenanced
+                for (const [id, evidence] of ctx.dbProvenanced) {
+                    provenanced.push({
+                        identifier: id,
+                        file: relPath,
+                        reason: evidence.reason,
+                        source: evidence.source,
+                        chain: evidence.chain.length > 0 ? evidence.chain : undefined,
+                    });
+                }
+                // Collect validator-provenanced
+                for (const [id, evidence] of ctx.validatorProvenanced) {
+                    validatorIdentifiers.push({
+                        identifier: id,
+                        file: relPath,
+                        reason: evidence.reason,
+                        source: evidence.source,
+                        chain: evidence.chain.length > 0 ? evidence.chain : undefined,
+                    });
+                }
+                // Run inference
+                if (ctx.dbProvenanced.size > 0) {
+                    const inf = inferReceivers(ctx.dbProvenanced, ast, adapter, sourceCode);
+                    for (const ev of inf.evidence) {
+                        inferred.push({
+                            identifier: ev.identifier,
+                            file: relPath,
+                            reason: ev.reason,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Skip unparseable files
+            }
+        }
+        // Persist provenance to code index for cross-file consumption (Spec-21 R2)
+        try {
+            const db = CodeIndexDB.getInstance();
+            await db.initialize();
+            // Store per-file provenance
+            const byFile = new Map();
+            for (const p of provenanced) {
+                const entry = byFile.get(p.file) || (byFile.set(p.file, { dbProvenanced: [], validatorProvenanced: [] }), byFile.get(p.file));
+                entry.dbProvenanced.push(p);
+            }
+            for (const v of validatorIdentifiers) {
+                const entry = byFile.get(v.file) || (byFile.set(v.file, { dbProvenanced: [], validatorProvenanced: [] }), byFile.get(v.file));
+                entry.validatorProvenanced.push(v);
+            }
+            for (const [file, data] of byFile) {
+                db.storeFileProvenance(file, data);
+            }
+            // Store inferred receivers
+            db.storeInferredReceivers(inferred);
+        }
+        catch {
+            // Index not available — skip persistence
+        }
+        if (options.json) {
+            process.stdout.write(JSON.stringify({
+                mode: detectionMode,
+                projectRoot,
+                filesScanned: files.slice(0, 500).length,
+                dbProvenanced: provenanced,
+                validatorProvenanced: validatorIdentifiers,
+                inferred,
+            }, null, 2) + '\n');
+        }
+        else {
+            console.log(chalk.bold(`Detection mode: ${chalk.cyan(detectionMode)}`));
+            console.log(chalk.gray(`Scanned ${files.slice(0, 500).length} files`));
+            console.log();
+            if (provenanced.length > 0) {
+                console.log(chalk.bold('DB-Provenanced Identifiers:'));
+                for (const p of provenanced) {
+                    const reasonColor = p.reason === 'fallback'
+                        ? chalk.yellow
+                        : p.reason === 'package'
+                            ? chalk.green
+                            : chalk.cyan;
+                    console.log(`  ${chalk.white(p.identifier)} ${chalk.gray(`(${p.file})`)}`);
+                    console.log(`    ${reasonColor(`reason: ${p.reason}`)} — ${chalk.gray(p.source)}`);
+                    if (p.chain) {
+                        console.log(`    ${chalk.gray(`chain: ${p.chain.join(' → ')}`)}`);
+                    }
+                }
+                console.log();
+            }
+            if (inferred.length > 0) {
+                console.log(chalk.bold('Inferred Receivers:'));
+                for (const i of inferred) {
+                    console.log(`  ${chalk.white(i.identifier)} ${chalk.gray(`(${i.file})`)}`);
+                    console.log(`    ${chalk.magenta(i.reason)}`);
+                }
+                console.log();
+            }
+            if (validatorIdentifiers.length > 0) {
+                console.log(chalk.bold('Validator-Provenanced Identifiers:'));
+                for (const v of validatorIdentifiers) {
+                    console.log(`  ${chalk.white(v.identifier)} ${chalk.gray(`(${v.file})`)}`);
+                    console.log(`    ${chalk.green(`reason: ${v.reason}`)} — ${chalk.gray(v.source)}`);
+                }
+                console.log();
+            }
+            if (provenanced.length === 0 && inferred.length === 0 && validatorIdentifiers.length === 0) {
+                console.log(chalk.gray('No DB-provenanced, inferred, or validator-provenanced identifiers found.'));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
 // Search command
 program
     .command('search <query>')
@@ -788,6 +1312,456 @@ tasksCmd
         process.exit(1);
     }
 });
+// ── Ledger command — Spec 11 R1 ──────────────────────────────────────────
+// ── Hotspots command (Spec 13 R2/R3) ─────────────────────────────────────────
+program
+    .command('hotspots')
+    .description('Rank files and functions by hotspot score (churn × complexity)')
+    .option('--limit <n>', 'Max entries to show')
+    .option('--path <dir>', 'Target directory (triggers spot churn extraction if index is empty)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const rawDb = db.rawDb;
+        // Trigger a fast churn extraction if no hotspot scores exist yet
+        const existing = rawDb.prepare('SELECT COUNT(*) AS cnt FROM hotspot_scores').get();
+        if (existing.cnt === 0 && options.path) {
+            const { extractChurn } = await import('./churn/churnExtractor.js');
+            const { computeHotspots } = await import('./hotspots/hotspotScorer.js');
+            try {
+                extractChurn(rawDb, options.path, { churnWindowMonths: 12 });
+                computeHotspots(rawDb);
+            }
+            catch {
+                // Graceful: no git repo or extraction failure
+            }
+        }
+        const rows = rawDb.prepare(`
+        SELECT target, type, score, churn_pct, complexity_pct, commit_count,
+               distinct_authors, dominant_author, dominant_author_share,
+               bus_factor_risk, complexity
+        FROM hotspot_scores
+        ORDER BY score DESC
+        ${options.limit ? 'LIMIT ?' : ''}
+      `).all(...(options.limit ? [parseInt(options.limit, 10)] : []));
+        if (options.json) {
+            const entries = rows.map((r) => ({
+                target: r.target,
+                type: r.type,
+                score: Math.round(r.score * 1000) / 1000,
+                churnPercentile: Math.round(r.churn_pct * 1000) / 1000,
+                complexityPercentile: Math.round(r.complexity_pct * 1000) / 1000,
+                commitCount: r.commit_count,
+                distinctAuthors: r.distinct_authors,
+                dominantAuthor: r.dominant_author,
+                dominantAuthorShare: Math.round((r.dominant_author_share ?? 0) * 1000) / 1000,
+                busFactorRisk: !!r.bus_factor_risk,
+                complexity: r.complexity,
+            }));
+            process.stdout.write(JSON.stringify(entries, null, 2) + '\n');
+        }
+        else if (rows.length === 0) {
+            console.log(chalk.gray('No hotspot data found. Run a full sync with --path in a git repo first.'));
+        }
+        else {
+            console.log(chalk.blue(`Hotspots (${rows.length}):\n`));
+            for (const r of rows) {
+                const icon = r.bus_factor_risk ? chalk.red(' ⚠ BUS-FACTOR') : '';
+                const typeColor = r.type === 'function' ? chalk.cyan : chalk.yellow;
+                const scorePct = Math.round(r.score * 100);
+                const bar = scorePct > 0 ? '█'.repeat(Math.max(1, Math.round(scorePct / 5))) : '';
+                console.log(`  ${typeColor(`[${r.type}]`)} ${r.target}` +
+                    `\n    score: ${chalk.bold(`${scorePct}%`)} ${chalk.gray(bar)}` +
+                    `  churn: ${r.commit_count} commits (${r.distinct_authors} authors)` +
+                    `  complexity: ${r.complexity}` +
+                    `${r.dominant_author ? `  owner: ${r.dominant_author} (${Math.round(r.dominant_author_share * 100)}%)` : ''}` +
+                    `${icon}`);
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+// ── Risk command — Spec 14 R2 ───────────────────────────────────────
+program
+    .command('risk')
+    .description('Rank functions by architectural risk (PageRank × betweenness × complexity × untested)')
+    .option('--limit <n>', 'Max entries to show', '20')
+    .option('--path <dir>', 'Project path', process.cwd())
+    .option('--json', 'Output as JSON')
+    .option('--format <format>', 'Output format: dot (call-graph neighborhood of top functions)')
+    .action(async (options) => {
+    try {
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const rawDb = db.rawDb;
+        const { computeRisk, buildCallGraphFromCache } = await import('./graph/callGraph.js');
+        const { graph: callGraph } = buildCallGraphFromCache(rawDb);
+        const riskEntries = computeRisk(rawDb, callGraph.adjacency, callGraph.nodeIds, callGraph.nodeNames, callGraph.nodePaths);
+        const limit = parseInt(options.limit, 10) || 20;
+        const top = riskEntries.slice(0, limit);
+        if (options.format === 'dot') {
+            // DOT output: call-graph neighborhood of top-N risk functions
+            const { callGraphToDot } = await import('./graph/outputFormatter.js');
+            // Collect IDs for top risk functions
+            const topIds = new Set();
+            for (const e of top) {
+                const rows = rawDb.prepare('SELECT id FROM functions WHERE name = ? AND file_path = ?').all(e.functionName, e.filePath);
+                for (const r of rows)
+                    topIds.add(r.id);
+            }
+            const dot = callGraphToDot(callGraph, {
+                label: `Call Graph — Top ${top.length} Risk Functions`,
+                maxNodes: 60,
+                rankdir: 'LR',
+                showWeights: true,
+            });
+            process.stdout.write(dot);
+        }
+        else if (options.json) {
+            process.stdout.write(JSON.stringify(top.map(e => ({
+                functionName: e.functionName,
+                filePath: e.filePath,
+                pageRankPercentile: Math.round(e.pageRankPercentile * 1000) / 1000,
+                betweennessPercentile: Math.round(e.betweennessPercentile * 1000) / 1000,
+                complexityPercentile: Math.round(e.complexityPercentile * 1000) / 1000,
+                untested: e.untested,
+                riskScore: Math.round(e.riskScore * 1000) / 1000,
+            })), null, 2) + '\n');
+        }
+        else if (top.length === 0) {
+            console.log(chalk.gray('No risk data available. Run a full sync (code-audit index sync) first.'));
+        }
+        else {
+            console.log(chalk.blue(`Risk Rankings (${top.length} of ${riskEntries.length}):\n`));
+            console.log(chalk.gray('Rank  Function                            File                                PR%    BW%    CX%   Untested   Risk'));
+            console.log(chalk.gray('────  ────────                            ────                                ───    ───    ───   ────────   ────'));
+            for (let i = 0; i < top.length; i++) {
+                const e = top[i];
+                const fnName = e.functionName.length > 36 ? e.functionName.slice(0, 33) + '...' : e.functionName.padEnd(36);
+                const fp = (e.filePath || '').length > 36 ? '...' + (e.filePath || '').slice(-33) : (e.filePath || '').padEnd(36);
+                const prPct = String(Math.round(e.pageRankPercentile * 100)).padStart(4);
+                const bwPct = String(Math.round(e.betweennessPercentile * 100)).padStart(4);
+                const cxPct = String(Math.round(e.complexityPercentile * 100)).padStart(4);
+                const untested = e.untested ? chalk.red(' ✗      ') : chalk.green(' ✓      ');
+                const riskScore = String((Math.round(e.riskScore * 1000) / 1000).toFixed(3)).padStart(6);
+                console.log(`  ${chalk.dim(String(i + 1).padStart(3))}  ${chalk.bold(fnName)}  ${chalk.green(fp)}  ${prPct}  ${bwPct}  ${cxPct}  ${untested}  ${chalk.yellow(riskScore)}`);
+            }
+            console.log(chalk.gray('\nPR% = PageRank percentile, BW% = Betweenness percentile, CX% = Complexity percentile'));
+            console.log(chalk.gray('Risk = max(PR%, BW%) × CX% × (1 + untested)'));
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+const ledgerCmd = program
+    .command('ledger')
+    .description('View and manage the findings ledger (append-only audit history)');
+ledgerCmd
+    .command('list')
+    .description('List recent audit runs')
+    .option('--limit <n>', 'Max runs to show', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const { listRuns } = await import('./ledger.js');
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const runs = listRuns(db.rawDb);
+        const limit = parseInt(options.limit, 10) || 20;
+        const limited = runs.slice(0, limit);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(limited, null, 2) + '\n');
+        }
+        else if (limited.length === 0) {
+            console.log(chalk.gray('No audit runs in the ledger yet. Run an audit first.'));
+        }
+        else {
+            console.log(chalk.blue(`Ledger runs (${limited.length} of ${runs.length}):`));
+            for (const r of limited) {
+                const dirty = r.gitDirty ? chalk.yellow(' [dirty]') : '';
+                console.log(`  ${chalk.bold(r.runId.slice(0, 8))}  ${r.timestamp}  ${r.surface}/${r.scope}  ${r.findingCount} findings  ${r.durationMs}ms  exit=${r.exitStatus}${dirty}`);
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+ledgerCmd
+    .command('export')
+    .description('Export ledger as JSON')
+    .option('--since <iso>', 'Only runs from this ISO timestamp')
+    .option('--json', 'Output as JSON (always on for export)')
+    .action(async (options) => {
+    try {
+        const { exportLedger } = await import('./ledger.js');
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const data = exportLedger(db.rawDb, options.since);
+        process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+ledgerCmd
+    .command('stats')
+    .description('Show aggregated ledger statistics')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const { getLedgerStats } = await import('./ledger.js');
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const stats = getLedgerStats(db.rawDb);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(stats, null, 2) + '\n');
+        }
+        else {
+            console.log(chalk.blue(`Total runs: ${stats.totalRuns}`));
+            for (const [analyzer, a] of Object.entries(stats.perAnalyzer)) {
+                console.log(chalk.bold(`\n${analyzer} (${a.total} findings):`));
+                for (const [rule, count] of Object.entries(a.perRule)) {
+                    console.log(`  ${rule}: ${count}`);
+                }
+                const sev = a.severityDistribution;
+                if (Object.keys(sev).length > 0) {
+                    console.log(`  severity: ${Object.entries(sev).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+ledgerCmd
+    .command('trends')
+    .description('Compare consecutive full-audit runs and report new vs fixed findings per rule')
+    .option('--since <runId>', 'Only consider runs after this run ID')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const { getTrends } = await import('./ledger.js');
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const trends = getTrends(db.rawDb, options.since);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(trends, null, 2) + '\n');
+        }
+        else if (!trends) {
+            console.log(chalk.gray('Need at least 2 full-audit runs of the same target for trend analysis.'));
+        }
+        else {
+            console.log(chalk.blue(`Trends for ${chalk.bold(trends.target)}`));
+            console.log(chalk.gray(`  ${trends.runPairs.length} run pairs from ${trends.timeRange.start} to ${trends.timeRange.end}\n`));
+            // Sort rules by |net| descending
+            const rules = Object.values(trends.perRule).sort((a, b) => Math.abs(b.net) - Math.abs(a.net));
+            if (rules.length === 0) {
+                console.log(chalk.gray('No trend changes detected — findings are stable across runs.'));
+            }
+            else {
+                for (const r of rules) {
+                    const netIcon = r.net > 0 ? chalk.green(`↓${r.net}`) : r.net < 0 ? chalk.red(`↑${-r.net}`) : chalk.gray('→0');
+                    console.log(`  ${chalk.bold(r.rule)}` +
+                        `  new: ${chalk.red(r.newCount)}` +
+                        `  fixed: ${chalk.green(r.fixedCount)}` +
+                        `  net: ${netIcon}`);
+                }
+            }
+            // Comparison basis
+            console.log(chalk.gray(`\nComparison basis: target=${trends.target}, ${trends.runPairs.length} consecutive full-audit pairs`));
+            if (options.since) {
+                console.log(chalk.gray(`Filter: since run ${options.since.slice(0, 8)}`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+ledgerCmd
+    .command('import')
+    .description('Import D1 interim ledger files from a directory')
+    .requiredOption('--dir <path>', 'Directory of JSON run files')
+    .action(async (options) => {
+    try {
+        const { importLedgerFromDir } = await import('./ledger.js');
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const result = importLedgerFromDir(db.rawDb, options.dir);
+        console.log(chalk.green(`✓ Imported ${result.imported} runs, skipped ${result.skipped}`));
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+// ── Conventions command — Spec 12 R3 ────────────────────────────────────────
+const conventionsCmd = program
+    .command('conventions')
+    .description('List mined codebase conventions and propose enforceable rules');
+conventionsCmd
+    .command('list')
+    .description('List mined conventions from the code index')
+    .option('--domain <domain>', 'Filter by domain: usage-pair, import-form, error-handling, export-shape, naming')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const rawDb = db.rawDb;
+        let sql = 'SELECT * FROM conventions';
+        let params = [];
+        if (options.domain) {
+            sql += ' WHERE domain = ?';
+            params = [options.domain];
+        }
+        sql += ' ORDER BY domain, directory, confidence DESC';
+        const conventions = rawDb.prepare(sql).all(...params);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(conventions, null, 2) + '\n');
+        }
+        else if (conventions.length === 0) {
+            console.log(chalk.gray('No conventions mined yet. Run a full audit or index sync first.'));
+        }
+        else {
+            // Group by domain for display
+            const byDomain = new Map();
+            for (const c of conventions) {
+                const list = byDomain.get(c.domain) ?? [];
+                list.push(c);
+                byDomain.set(c.domain, list);
+            }
+            console.log(chalk.blue(`Mined conventions (${conventions.length} total):\n`));
+            for (const [domain, list] of byDomain) {
+                console.log(chalk.bold(`  ${domain} (${list.length})`));
+                for (const c of list.slice(0, 5)) {
+                    const exemplar = c.exemplar_file
+                        ? ` (exemplar: ${c.exemplar_file}${c.exemplar_line ? `:${c.exemplar_line}` : ''})`
+                        : '';
+                    const pct = Math.round(c.confidence * 100);
+                    const desc = domain === 'usage-pair'
+                        ? `${c.antecedent} → ${c.consequent}`
+                        : domain === 'import-form'
+                            ? `${c.antecedent} → ${c.consequent}`
+                            : domain === 'error-handling'
+                                ? `shape: ${c.pattern}`
+                                : domain === 'export-shape'
+                                    ? `form: ${c.pattern}`
+                                    : `case: ${c.pattern}`; // naming
+                    const dir = c.directory ? `  [${c.directory}]` : '';
+                    console.log(`    ${desc}  ${pct}% (${c.support}/${c.total_cases})${dir}${exemplar}`);
+                }
+                if (list.length > 5) {
+                    console.log(chalk.gray(`    ... and ${list.length - 5} more`));
+                }
+                console.log('');
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+conventionsCmd
+    .command('propose')
+    .description('Emit ready-to-paste .codeauditor.json rules from mined conventions')
+    .option('--domain <domain>', 'Filter by domain: naming or import-form (other domains do not map to rule kinds)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const rawDb = db.rawDb;
+        let sql = 'SELECT * FROM conventions';
+        let params = [];
+        if (options.domain) {
+            sql += ' WHERE domain = ?';
+            params = [options.domain];
+        }
+        sql += ' ORDER BY domain, directory, confidence DESC';
+        const conventions = rawDb.prepare(sql).all(...params);
+        const proposals = [];
+        for (const c of conventions) {
+            switch (c.domain) {
+                case 'naming': {
+                    if (!c.directory || !c.pattern)
+                        continue;
+                    proposals.push({
+                        kind: 'naming',
+                        message: `Use ${c.pattern} naming in ${c.directory}/ (${Math.round(c.confidence * 100)}% convention)`,
+                        description: `Exported symbols in ${c.directory}/ should use ${c.pattern}`,
+                        paths: [`${c.directory}/*`],
+                        pattern: getNamingPattern(c.pattern),
+                        exports: '**',
+                    });
+                    break;
+                }
+                case 'import-form': {
+                    if (!c.antecedent || !c.consequent)
+                        continue;
+                    proposals.push({
+                        kind: 'import-ban',
+                        message: `Import '${c.antecedent}' with module form in ${c.directory || '.'}/ (${Math.round(c.confidence * 100)}% convention)`,
+                        description: `In ${c.directory || '.'}/, imports of '${c.antecedent}' should use ${c.consequent} form`,
+                        module: c.antecedent,
+                        except: [{ source: c.directory || '.', form: c.consequent }],
+                    });
+                    break;
+                }
+                default:
+                    // usage-pair, error-handling, export-shape: no existing rule kind
+                    break;
+            }
+        }
+        if (options.json) {
+            process.stdout.write(JSON.stringify(proposals, null, 2) + '\n');
+        }
+        else if (proposals.length === 0) {
+            console.log(chalk.gray('No proposals available. Only naming and import-form conventions map to rule kinds.'));
+            console.log(chalk.gray('Usage-pair, error-handling, and export-shape are detector-only.'));
+        }
+        else {
+            console.log(chalk.blue(`Proposed rules (${proposals.length}):\n`));
+            for (const p of proposals) {
+                console.log(chalk.green(`  // ${p.message}`));
+                console.log(JSON.stringify(p, null, 4).split('\n').map(l => `  ${l}`).join('\n'));
+                console.log('');
+            }
+            console.log(chalk.gray('# Copy the rule objects above into the "rules" array in .codeauditor.json'));
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+/**
+ * Map a case name to a regex pattern for the naming rule kind.
+ */
+function getNamingPattern(caseName) {
+    switch (caseName) {
+        case 'PascalCase': return '^[A-Z][a-zA-Z0-9]*$';
+        case 'camelCase': return '^[a-z][a-zA-Z0-9]*$';
+        case 'UPPER_SNAKE': return '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$';
+        case 'snake_case': return '^[a-z][a-z0-9]*(_[a-z0-9]+)*$';
+        case 'kebab-case': return '^[a-z][a-z0-9]*(-[a-z0-9]+)*$';
+        default: return '^.*$';
+    }
+}
 // Install command — copy skill folder to agent-specific paths
 program
     .command('install')
@@ -812,6 +1786,155 @@ program
         process.exit(1);
     }
 });
+// ── Architecture command — Spec 14 R3/R4 ────────────────────────────────
+program
+    .command('architecture')
+    .description('Analyze import graph: community detection, directory purity, Martin instability metrics')
+    .option('--path <dir>', 'Project path', process.cwd())
+    .option('--json', 'Output as JSON')
+    .option('--format <format>', 'Output format: dot or mermaid (import graph colored by community)')
+    .action(async (options) => {
+    try {
+        const db = CodeIndexDB.getInstance();
+        await db.initialize();
+        const rawDb = db.rawDb;
+        const { buildImportGraphFromCache, detectCommunities, computeDirectoryPurity, computeMartinMetrics, } = await import('./graph/importGraph.js');
+        const importGraph = buildImportGraphFromCache(rawDb);
+        if (importGraph.filePaths.size === 0) {
+            if (options.json) {
+                process.stdout.write(JSON.stringify({ error: 'No import graph data. Run a full sync first.' }) + '\n');
+            }
+            else {
+                console.log(chalk.gray('No import graph data. Run a full sync (code-audit index sync) first.'));
+            }
+            return;
+        }
+        const communities = detectCommunities(importGraph.adjacency, importGraph.filePaths);
+        const purity = computeDirectoryPurity(communities.communities, importGraph.filePaths);
+        const martin = computeMartinMetrics(rawDb, importGraph);
+        if (options.format === 'dot' || options.format === 'mermaid') {
+            // Emit import graph colored by community
+            const { importGraphToDot, importGraphToMermaid } = await import('./graph/outputFormatter.js');
+            if (options.format === 'dot') {
+                const dot = importGraphToDot(importGraph, {
+                    label: 'Import Graph — Colored by Community',
+                    communities: communities.communities,
+                    rankdir: 'LR',
+                    showWeights: true,
+                    legend: true,
+                });
+                process.stdout.write(dot);
+            }
+            else {
+                const mermaid = importGraphToMermaid(importGraph, {
+                    label: 'Import Graph — Colored by Community',
+                    communities: communities.communities,
+                    showWeights: true,
+                });
+                process.stdout.write(mermaid);
+            }
+            return;
+        }
+        if (options.json) {
+            process.stdout.write(JSON.stringify({
+                communityCount: communities.communityCount,
+                modularity: Math.round(communities.modularity * 10000) / 10000,
+                directoryPurity: purity.directoryPurities.map(d => ({
+                    directory: d.directory,
+                    totalFiles: d.totalFiles,
+                    pluralityCommunity: d.pluralityCommunity,
+                    pluralityCount: d.pluralityCount,
+                    purity: Math.round(d.purity * 10000) / 10000,
+                })),
+                splitCandidates: purity.splitCandidates.map(s => ({
+                    directory: s.directory,
+                    communities: s.communities,
+                    fileCounts: s.fileCounts,
+                })),
+                mergeCandidates: purity.mergeCandidates.map(m => ({
+                    directories: m.directories,
+                    community: m.community,
+                    fileCount: m.fileCount,
+                })),
+                agreementScore: Math.round(purity.agreementScore * 10000) / 10000,
+                martinMetrics: martin.map(m => ({
+                    directory: m.directory,
+                    ce: m.ce,
+                    ca: m.ca,
+                    instability: Math.round(m.instability * 10000) / 10000,
+                    abstractness: Math.round(m.abstractness * 10000) / 10000,
+                    distanceFromMain: Math.round(m.distanceFromMain * 10000) / 10000,
+                })),
+            }, null, 2) + '\n');
+        }
+        else {
+            // Community summary
+            console.log(chalk.blue('🏗️  Architecture Analysis\n'));
+            console.log(chalk.bold('Community Detection (Louvain):'));
+            console.log(chalk.gray(`  ${communities.communityCount} communities detected (modularity: ${communities.modularity.toFixed(4)})`));
+            // Directory Purity
+            if (purity.directoryPurities.length > 0) {
+                console.log(chalk.bold('\nDirectory Purity (agreement score: ') + chalk.yellow(purity.agreementScore.toFixed(2)) + chalk.bold(')\n'));
+                console.log(chalk.gray('  Directory                                  Files  Plurality  Purity'));
+                console.log(chalk.gray('  ─────────                                  ─────  ─────────  ──────'));
+                for (const d of purity.directoryPurities) {
+                    const dirName = d.directory.length > 40 ? '...' + d.directory.slice(-37) : d.directory.padEnd(40);
+                    const files = String(d.totalFiles).padStart(5);
+                    const comm = String(d.pluralityCommunity).padStart(9);
+                    const pur = (d.purity * 100).toFixed(0).padStart(4) + '%';
+                    const purColor = d.purity >= 0.8 ? chalk.green(pur) : d.purity >= 0.5 ? chalk.yellow(pur) : chalk.red(pur);
+                    console.log(`  ${chalk.dim(dirName)}  ${files}  ${comm}  ${purColor}`);
+                }
+            }
+            // Split Candidates
+            if (purity.splitCandidates.length > 0) {
+                console.log(chalk.bold('\n🔀 Split Candidates (directories spanning ≥2 communities):'));
+                for (const s of purity.splitCandidates) {
+                    console.log(chalk.yellow(`  ${s.directory}`));
+                    for (let i = 0; i < s.communities.length; i++) {
+                        console.log(chalk.gray(`    Community ${s.communities[i]}: ${s.fileCounts[i]} files`));
+                    }
+                }
+            }
+            // Merge Candidates
+            if (purity.mergeCandidates.length > 0) {
+                console.log(chalk.bold('\n🔗 Merge Candidates (one community dominating ≥2 directories):'));
+                for (const m of purity.mergeCandidates) {
+                    const dirs = m.directories.join(', ');
+                    console.log(chalk.green(`  Community ${m.community}: ${dirs} (${m.fileCount} files)`));
+                }
+            }
+            // Martin Metrics
+            console.log(chalk.bold('\nMain-Sequence Distance (Martin Metrics):\n'));
+            if (martin.length === 0) {
+                console.log(chalk.gray('  No directory-level metrics available.'));
+            }
+            else {
+                console.log(chalk.gray('  Directory                                  Ce   Ca     I     A    |D|'));
+                console.log(chalk.gray('  ─────────                                  ──   ──   ────  ────  ────'));
+                // Sort by distance from main sequence descending
+                const sorted = [...martin].sort((a, b) => b.distanceFromMain - a.distanceFromMain);
+                for (const m of sorted.slice(0, 30)) {
+                    const dirName = m.directory.length > 40 ? '...' + m.directory.slice(-37) : m.directory.padEnd(40);
+                    const ce = String(m.ce).padStart(3);
+                    const ca = String(m.ca).padStart(3);
+                    const inst = m.instability.toFixed(2).padStart(5);
+                    const abst = m.abstractness.toFixed(2).padStart(5);
+                    const dist = m.distanceFromMain.toFixed(2).padStart(5);
+                    const distColor = m.distanceFromMain <= 0.3 ? chalk.green(dist) : m.distanceFromMain <= 0.5 ? chalk.yellow(dist) : chalk.red(dist);
+                    console.log(`  ${chalk.dim(dirName)}  ${ce}  ${ca}  ${inst}  ${abst}  ${distColor}`);
+                }
+                console.log(chalk.gray('\n  Ce = efferent couplings, Ca = afferent couplings'));
+                console.log(chalk.gray('  I = Ce/(Ca+Ce), A = abstractness, |D| = |A+I−1|'));
+                console.log(chalk.gray('  Ideal: |D| → 0 (close to main sequence)'));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
 // Cursor hook adapter — postToolUse (Write matcher) → scoped audit → additional_context + exit 2
 // Verified 2026-07-20: cursor.com/docs/hooks + cursor.com/docs/reference/third-party-hooks
 program
@@ -839,6 +1962,87 @@ program
         process.exit(1);
     }
 });
+// ── Coverage command — Spec 15 R4 ─────────────────────────────────────
+const coverageCmd = program
+    .command('coverage')
+    .description('Import and report test coverage data');
+coverageCmd
+    .command('import')
+    .description('Import a coverage file (lcov .info or Istanbul JSON)')
+    .argument('<path>', 'Path to the coverage file')
+    .option('--project-root <path>', 'Project root for resolving relative paths', process.cwd())
+    .action(async (filePath, options) => {
+    try {
+        const { importCoverageFile } = await import('./coverage/coverageService.js');
+        const result = await importCoverageFile(filePath, options.projectRoot);
+        console.log(chalk.green(`Imported ${result.format} coverage:`));
+        console.log(`  Format:        ${result.format}`);
+        console.log(`  Files:         ${result.filesImported}`);
+        console.log(`  Entries:       ${result.entriesImported}`);
+        console.log(`  Source:        ${result.source}`);
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+coverageCmd
+    .command('by-risk', { isDefault: true })
+    .description('Show coverage rate by risk decile')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const { generateCoverageReport } = await import('./coverage/coverageService.js');
+        const report = await generateCoverageReport();
+        if (options.json) {
+            process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+            return;
+        }
+        console.log(chalk.blue(`Coverage Report:\n`));
+        console.log(`  Total functions:     ${report.totalFunctions}`);
+        console.log(`  Covered functions:   ${report.coveredFunctions}`);
+        console.log(`  Coverage rate:       ${(report.coverageRate * 100).toFixed(1)}%`);
+        if (report.staleImport) {
+            console.log(chalk.yellow(`  ⚠ Coverage data is stale — sync index and re-import`));
+        }
+        console.log(chalk.blue(`\n  By Risk Decile:`));
+        if (report.byRiskDecile.length === 0) {
+            console.log(chalk.gray('    No data available. Run a full audit with hotspot scoring first.'));
+        }
+        else {
+            for (const d of report.byRiskDecile) {
+                const bar = renderBar(d.rate, 20);
+                console.log(`    Decile ${String(d.decile).padStart(2)}: ${bar} ${(d.rate * 100).toFixed(0)}% ` +
+                    `(${d.covered}/${d.total})`);
+            }
+        }
+        console.log(chalk.blue(`\n  Untested Top-Risk Functions:`));
+        if (report.untestedTopDecile.length === 0) {
+            console.log(chalk.green('    All top-risk functions have coverage.'));
+        }
+        else {
+            for (const fn of report.untestedTopDecile.slice(0, 10)) {
+                console.log(`    ${chalk.yellow('⚠')} ${fn.functionName} (risk: ${fn.riskScore.toFixed(3)}) — ${fn.filePath}`);
+            }
+            if (report.untestedTopDecile.length > 10) {
+                console.log(chalk.gray(`    ... and ${report.untestedTopDecile.length - 10} more`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+/**
+ * Render a simple ASCII bar chart.
+ */
+function renderBar(value, width) {
+    const filled = Math.round(value * width);
+    const empty = width - filled;
+    const color = value > 0.8 ? chalk.green : value > 0.5 ? chalk.yellow : chalk.red;
+    return color('█'.repeat(filled) + '░'.repeat(empty));
+}
 // Parse command line arguments
 program.parse(process.argv);
 // If no command was provided, show help