code-auditor-mcp 3.1.1 → 3.4.1

package/dist/auditRunner.js

@@ -2,15 +2,20 @@
  * Audit Runner (Functional)
  * Main orchestrator for running code audits
  */
+import { promises as fs } from 'fs';
 import { statSync, readFileSync } from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
+import { randomUUID } from 'node:crypto';
 import { AuditAbortedError, AuditHandoffError, } from './types.js';
 import { discoverFiles } from './utils/fileDiscovery.js';
 import { loadConfig } from './config/configLoader.js';
 import { generateReport } from './reporting/reportGenerator.js';
 import { extractFunctionsFromFile } from './functionScanner.js';
 import { isMcpDebugEnabled, logMcpDebug, logMcpInfo } from './mcpDiagnostics.js';
+import { loadBaseline, matchFindings, hashBaseline } from './baseline.js';
+import { computeImpact, LATENCY_BUDGET_MS } from './graph/blastRadius.js';
 // Import universal analyzers
 import { initializeLanguages } from './languages/index.js';
 import { UniversalSOLIDAnalyzer } from './analyzers/universal/UniversalSOLIDAnalyzer.js';
@@ -18,12 +23,24 @@ import { UniversalDRYAnalyzer } from './analyzers/universal/UniversalDRYAnalyzer
 import { UniversalDataAccessAnalyzer } from './analyzers/universal/UniversalDataAccessAnalyzer.js';
 import { UniversalDocumentationAnalyzer } from './analyzers/universal/UniversalDocumentationAnalyzer.js';
 import { UniversalSchemaAnalyzer } from './analyzers/universal/UniversalSchemaAnalyzer.js';
+import { UniversalStylesAnalyzer } from './analyzers/universal/UniversalStylesAnalyzer.js';
+import { UniversalConventionsAnalyzer } from './analyzers/universal/UniversalConventionsAnalyzer.js';
+import { CrossDomainAnalyzer } from './analyzers/crossDomain/CrossDomainAnalyzer.js';
+import { initializeOrmAdapters } from './analyzers/orm/index.js';
+import { syncStyleIndex } from './styles/styleIndexer.js';
 import { reactAnalyzer } from './analyzers/reactAnalyzer.js';
 import { invariantsAnalyzer } from './analyzers/invariantsAnalyzer.js';
 import { hasRules } from './invariants/ruleEngine.js';
 import { CodeIndexDB } from './codeIndexDB.js';
+import { writeAuditToLedger, detectRunInput } from './ledger.js';
+// Package version — read once at module load
+const __auditRunnerDirname = path.dirname(fileURLToPath(import.meta.url));
+const _pkg = JSON.parse(readFileSync(path.join(__auditRunnerDirname, '..', 'package.json'), 'utf-8'));
+const TOOL_VERSION = String(_pkg.version || '0.0.0');
 // Initialize the canonical language system once
 initializeLanguages();
+// Initialize ORM adapters for cross-domain schema extraction (Spec 15 R2)
+initializeOrmAdapters();
 /**
  * Shared progress callback adapter: translates universal analyzer's (number) into
  * the object-based callback that auditRunner passes downstream.
@@ -75,6 +92,13 @@ const DEFAULT_ANALYZERS = {
                 universalConfig.checkInterfaceSegregation = config.checkInterfaceSegregation;
             if (config.checkLiskovSubstitution !== undefined)
                 universalConfig.checkLiskovSubstitution = config.checkLiskovSubstitution;
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
             const result = await analyzer.analyze(files, universalConfig, {
                 progressCallback: createProgressAdapter('solid', progressCallback),
                 ...options,
@@ -127,6 +151,16 @@ const DEFAULT_ANALYZERS = {
             // R4.3: directAccess — "flag" (default) or "allow"
             if (config.directAccess !== undefined)
                 universalConfig.directAccess = config.directAccess;
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
+            // Spec 21: Forward shared provenance timing accumulator
+            if (config._provenanceTiming !== undefined)
+                universalConfig._provenanceTiming = config._provenanceTiming;
             return analyzer.analyze(files, universalConfig, {
                 progressCallback: createProgressAdapter('data-access', progressCallback),
                 ...options,
@@ -157,6 +191,13 @@ const DEFAULT_ANALYZERS = {
                 fileHeaders: config.fileHeaders ?? config.requireFileDocs ?? false, // R1.5
                 headerSkipGlobs: config.headerSkipGlobs, // R1.5 (undefined → analyzer default)
             };
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
             return analyzer.analyze(files, universalConfig, {
                 progressCallback: createProgressAdapter('documentation', progressCallback),
                 ...options,
@@ -190,7 +231,6 @@ const DEFAULT_ANALYZERS = {
                 // If database isn't available, continue without schemas
             }
             const universalConfig = {
-                enableTableUsageTracking: config.enableTableUsageTracking ?? true,
                 checkMissingReferences: config.checkMissingReferences ?? true,
                 checkNamingConventions: config.checkNamingConventions ?? true,
                 detectUnusedTables: config.detectUnusedTables ?? false,
@@ -205,6 +245,16 @@ const DEFAULT_ANALYZERS = {
                 dbBindingNames: config.dbBindingNames ?? ['env.DB'], // R2.2
                 fileGateGlobs: config.fileGateGlobs, // R2.2 (let analyzer use defaults)
             };
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
+            // Spec 21: Forward shared provenance timing accumulator
+            if (config._provenanceTiming !== undefined)
+                universalConfig._provenanceTiming = config._provenanceTiming;
             const result = await analyzer.analyze(files, universalConfig);
             return {
                 ...result,
@@ -217,6 +267,98 @@ const DEFAULT_ANALYZERS = {
             };
         },
     },
+    'styles': {
+        name: 'styles',
+        description: 'Detects style fragmentation, value drift, token bypass, dead classes, off-scale values, mechanism fragmentation, and z-index sprawl',
+        category: 'style',
+        analyze: async (files, config, options, progressCallback) => {
+            const analyzer = new UniversalStylesAnalyzer();
+            const universalConfig = {};
+            if (config.minCorpus !== undefined)
+                universalConfig.minCorpus = config.minCorpus;
+            if (config.colorDeltaE !== undefined)
+                universalConfig.colorDeltaE = config.colorDeltaE;
+            if (config.outlierMaxShare !== undefined)
+                universalConfig.outlierMaxShare = config.outlierMaxShare;
+            if (config.modeMinCount !== undefined)
+                universalConfig.modeMinCount = config.modeMinCount;
+            if (config.scaleProperties !== undefined)
+                universalConfig.scaleProperties = config.scaleProperties;
+            if (config.zIndexMaxDistinct !== undefined)
+                universalConfig.zIndexMaxDistinct = config.zIndexMaxDistinct;
+            if (config.mechanismFragmentationMinMechanisms !== undefined)
+                universalConfig.mechanismFragmentationMinMechanisms = config.mechanismFragmentationMinMechanisms;
+            if (config.declarationSetMinDeclarations !== undefined)
+                universalConfig.declarationSetMinDeclarations = config.declarationSetMinDeclarations;
+            if (config.declarationSetSimilarityThreshold !== undefined)
+                universalConfig.declarationSetSimilarityThreshold = config.declarationSetSimilarityThreshold;
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
+            return analyzer.analyze(files, universalConfig, {
+                progressCallback: createProgressAdapter('styles', progressCallback),
+                ...options,
+            });
+        },
+    },
+    'conventions': {
+        name: 'conventions',
+        description: 'Mines codebase conventions and flags deviations at suggestion severity',
+        category: 'style',
+        analyze: async (files, config, options, progressCallback) => {
+            const analyzer = new UniversalConventionsAnalyzer();
+            const universalConfig = {};
+            if (config.minCorpus !== undefined)
+                universalConfig.minCorpus = config.minCorpus;
+            if (config.pairConfidence !== undefined)
+                universalConfig.pairConfidence = config.pairConfidence;
+            if (config.modeShare !== undefined)
+                universalConfig.modeShare = config.modeShare;
+            if (config.maxConventionsPerDomain !== undefined)
+                universalConfig.maxConventionsPerDomain = config.maxConventionsPerDomain;
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
+            return analyzer.analyze(files, universalConfig, {
+                progressCallback: createProgressAdapter('conventions', progressCallback),
+                ...options,
+            });
+        },
+    },
+    'cross-domain': {
+        name: 'cross-domain',
+        description: 'Detects cross-domain issues (schema lifecycle, validation bypass, coverage gaps)',
+        category: 'architecture',
+        analyze: async (files, config, options, progressCallback) => {
+            const analyzer = new CrossDomainAnalyzer();
+            const universalConfig = {};
+            if (config.schemaLifecycle !== undefined)
+                universalConfig.schemaLifecycle = config.schemaLifecycle;
+            if (config.validatorBypass !== undefined)
+                universalConfig.validatorBypass = config.validatorBypass;
+            if (config.coverage !== undefined)
+                universalConfig.coverage = config.coverage;
+            // Forward base-class properties (Spec-20 path profiles + severity overrides)
+            if (config.severityOverrides !== undefined)
+                universalConfig.severityOverrides = config.severityOverrides;
+            if (config.pathProfiles !== undefined)
+                universalConfig.pathProfiles = config.pathProfiles;
+            if (config.projectRoot !== undefined)
+                universalConfig.projectRoot = config.projectRoot;
+            return analyzer.analyze(files, universalConfig, {
+                progressCallback: createProgressAdapter('cross-domain', progressCallback),
+                ...options,
+            });
+        },
+    },
 };
 /**
  * Create an audit runner with the given options
@@ -240,7 +382,20 @@ export function createAuditRunner(options = {}) {
      * Run the audit
      */
     async function run(runOptions) {
-        const mergedOptions = { ...options, ...runOptions };
+        // Auto-load .codeauditor.json from project root so the programmatic API
+        // respects the same config the CLI surface reads. RunOptions (caller)
+        // override file config, and createAuditRunner options override both.
+        const rootForConfig = runOptions?.projectRoot || options.projectRoot || process.cwd();
+        let fileConfig = {};
+        try {
+            const configPath = path.join(rootForConfig, '.codeauditor.json');
+            await fs.access(configPath);
+            fileConfig = await loadConfig({ configPath });
+        }
+        catch {
+            // No config file — proceed with defaults
+        }
+        const mergedOptions = { ...fileConfig, ...options, ...runOptions };
         const startTime = Date.now();
         // ── Scope resolution ─────────────────────────────────────────────
         const scope = mergedOptions.scope ?? 'all';
@@ -305,6 +460,44 @@ export function createAuditRunner(options = {}) {
                 });
             }
         }
+        // ── Blast-radius impact (Spec 14 R6) ──────────────────────────────
+        // Compute transitive-caller impact for changed functions.
+        // If latency exceeds the 100ms budget, skip and emit a warning;
+        // the feature is disabled-by-default when over budget.
+        let blastRadius;
+        if (isScoped && changedFunctions && changedFunctions.length > 0) {
+            try {
+                const db = CodeIndexDB.getInstance();
+                const rawDb = db.rawDb;
+                const functionIds = [];
+                for (const fn of changedFunctions) {
+                    const row = rawDb.prepare('SELECT id FROM functions WHERE name = ? AND file_path = ?').get(fn.name, fn.filePath);
+                    if (row)
+                        functionIds.push(row.id);
+                }
+                if (functionIds.length > 0) {
+                    const impact = computeImpact(rawDb, functionIds);
+                    if (impact.latencyMs > LATENCY_BUDGET_MS) {
+                        logMcpInfo('blast-radius', `latency ${impact.latencyMs}ms exceeds ${LATENCY_BUDGET_MS}ms budget — blast radius disabled for this run`, {});
+                    }
+                    else {
+                        blastRadius = impact;
+                        logMcpInfo('blast-radius', 'computed', {
+                            editedFunctionCount: impact.editedFunctionCount,
+                            transitiveCallers: impact.transitiveCallers,
+                            reachableExports: impact.reachableExports,
+                            latencyMs: impact.latencyMs,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                // Blast radius is advisory — non-fatal
+                logMcpInfo('blast-radius', 'computation failed (continuing)', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+        }
         const handoffRemaining = [];
         const maxPerRun = mergedOptions.maxFilesPerRun;
         if (typeof maxPerRun === 'number' && maxPerRun > 0 && files.length > maxPerRun) {
@@ -391,6 +584,32 @@ export function createAuditRunner(options = {}) {
         // Run analyzers
         const analyzerResults = {};
         const enabledAnalyzers = getEnabledAnalyzers(mergedOptions, analyzerRegistry);
+        // ── Style index sync (Spec 10) ────────────────────────────────────
+        // Sync style declarations, tokens, and class usage before the
+        // styles analyzer runs, mirroring the function index sync pattern.
+        if (enabledAnalyzers.includes('styles')) {
+            try {
+                const styleDb = CodeIndexDB.getInstance();
+                await styleDb.initialize();
+                const styleSyncResult = await syncStyleIndex(styleDb.rawDb, files, root, { scoped: isScoped });
+                logMcpInfo('style-index', 'style index sync complete', {
+                    changed: styleSyncResult.changed,
+                    skipped: styleSyncResult.skipped,
+                    removed: styleSyncResult.removed,
+                    errors: styleSyncResult.errors,
+                });
+            }
+            catch (err) {
+                // Non-fatal: styles analyzer will run with whatever is in the index
+                logMcpInfo('style-index', 'style index sync failed (continuing)', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+        }
+        // Spec 21: Shared timing accumulator for provenance resolution.
+        // Injected into data-access and schema analyzers so they can report
+        // per-file buildProvenanceContext() wall time (hook-latency measurement).
+        const provenanceTiming = { totalMs: 0 };
         logMcpInfo('analysis', 'enabled analyzers', {
             names: enabledAnalyzers,
             fileCount: files.length,
@@ -421,11 +640,28 @@ export function createAuditRunner(options = {}) {
                     analyzer: analyzerName,
                     message: `Running ${analyzerName} analyzer...`
                 });
-                // Build analyzer config; inject full index for DRY on scoped runs
-                const analyzerConfig = { ...(mergedOptions.analyzerConfigs?.[analyzerName] || {}) };
+                // Build analyzer config; inject full index for DRY on scoped runs.
+                // Skip pathProfiles for invariants (Spec-20 R3): no backdoor
+                // around declared laws — invariants severity is absolute.
+                const isInvariants = analyzerName === 'invariants';
+                const analyzerConfig = {
+                    ...(mergedOptions.analyzerConfigs?.[analyzerName] || {}),
+                };
+                if (!isInvariants) {
+                    analyzerConfig.pathProfiles = mergedOptions.pathProfiles;
+                    analyzerConfig.projectRoot = root;
+                    analyzerConfig.severityOverrides = mergedOptions.severityOverrides;
+                }
                 if (analyzerName === 'dry' && isScoped && fullFunctionIndex) {
                     analyzerConfig.fullFunctionIndex = fullFunctionIndex;
                 }
+                // Spec 21: Pass shared provenance timing accumulator to analyzers
+                // that call buildProvenanceContext() (data-access and schema).
+                // The analyzers accumulate per-file timing into this object;
+                // we read it back after all analyzers complete.
+                if (analyzerName === 'data-access' || analyzerName === 'schema') {
+                    analyzerConfig._provenanceTiming = provenanceTiming;
+                }
                 logMcpInfo('analysis', `running ${analyzerName}`, { fileCount: files.length });
                 try {
                     const result = await analyzer.analyze(files, analyzerConfig, mergedOptions, (progress) => {
@@ -474,6 +710,208 @@ export function createAuditRunner(options = {}) {
                 orderedAnalyzerResults[analyzerName] = analyzerResults[analyzerName];
             }
         }
+        // ── Spec 13 R5 Phase 1: Persist seeded DRY pairs ──────────────────
+        // Store pairs from DRY analysis in dry_pair_history for divergence tracking.
+        // Pair identity is fingerprint-based (file + nodeType + line),
+        // NOT content-hash-based — so a diverging clone stays the same pair.
+        let dryPersistRunId = null;
+        try {
+            const dryResult = orderedAnalyzerResults['dry'];
+            const dryPairs = dryResult?.dryPairs;
+            if (dryPairs && dryPairs.length > 0) {
+                const indexDb = CodeIndexDB.getInstance();
+                await indexDb.initialize();
+                dryPersistRunId = randomUUID();
+                const insertStmt = indexDb.rawDb.prepare(`
+          INSERT OR IGNORE INTO dry_pair_history
+            (pair_fingerprint, file1, symbol1, line1, content_hash1,
+             file2, symbol2, line2, content_hash2, similarity, timestamp, run_id)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?)
+        `);
+                const tx = indexDb.rawDb.transaction(() => {
+                    for (const pair of dryPairs) {
+                        insertStmt.run(pair.pairFingerprint, pair.file1, pair.symbol1, pair.line1, pair.contentHash1, pair.file2, pair.symbol2, pair.line2, pair.contentHash2, pair.similarity, dryPersistRunId);
+                    }
+                });
+                tx();
+            }
+        }
+        catch {
+            // dry_pair_history persistence is advisory — non-fatal
+        }
+        // ── Baseline classification (Spec 18 R1) ────────────────────────────
+        const projectRoot = path.resolve(mergedOptions.projectRoot || process.cwd());
+        const baseline = loadBaseline(projectRoot);
+        let baselineMetadata;
+        if (baseline) {
+            const allViolations = Object.values(orderedAnalyzerResults).flatMap((r) => r.violations);
+            // For scoped runs, limit "fixed" to in-scope files
+            const scopedFiles = isScoped ? files : undefined;
+            const classified = matchFindings(allViolations, baseline, scopedFiles);
+            // Tag violations with their baseline status
+            for (const v of classified.new) {
+                v.new = true;
+            }
+            for (const v of classified.known) {
+                v.new = false;
+            }
+            baselineMetadata = {
+                present: true,
+                hash: hashBaseline(baseline),
+                newCount: classified.new.length,
+                fixedCount: classified.fixed.length,
+                knownCount: classified.known.length,
+                previousKnownCount: baseline.metadata.totalFindings,
+            };
+            logMcpInfo('baseline', 'baseline classification complete', {
+                new: classified.new.length,
+                fixed: classified.fixed.length,
+                known: classified.known.length,
+            });
+        }
+        // ── Spec 13 R2 — Hotspot scoring & finding reordering ──────────────
+        // Attach hotspot scores to violations and reorder within severity tiers.
+        // Falls back gracefully when no churn/hotspot data exists.
+        try {
+            const indexDb = CodeIndexDB.getInstance();
+            await indexDb.initialize();
+            // Build hotspot lookup: target -> score
+            const hotspotRows = indexDb.rawDb
+                .prepare('SELECT target, type, score FROM hotspot_scores')
+                .all();
+            if (hotspotRows.length > 0) {
+                const hotspotByTarget = new Map();
+                const hotspotByFile = new Map();
+                for (const row of hotspotRows) {
+                    hotspotByTarget.set(row.target, row.score);
+                    if (row.type === 'file') {
+                        hotspotByFile.set(row.target, row.score);
+                    }
+                }
+                // Attach hotspot to each violation and reorder within each analyzer
+                for (const analyzerName of Object.keys(orderedAnalyzerResults)) {
+                    const result = orderedAnalyzerResults[analyzerName];
+                    const violations = result.violations;
+                    // Attach hotspot scores
+                    for (const v of violations) {
+                        const funcName = v.functionName;
+                        const file = v.file;
+                        // Try function-level hotspot first: "filePath::functionName"
+                        const funcTarget = funcName ? `${file}::${funcName}` : undefined;
+                        v.hotspot = (funcTarget ? hotspotByTarget.get(funcTarget) : undefined)
+                            ?? hotspotByFile.get(file)
+                            ?? 0;
+                    }
+                    // Reorder within severity tiers: sort by hotspot descending,
+                    // preserving original order as tiebreaker.
+                    const severityOrder = {
+                        critical: 0,
+                        warning: 1,
+                        suggestion: 2,
+                        info: 3,
+                    };
+                    const indexed = violations.map((v, i) => ({ v, i }));
+                    indexed.sort((a, b) => {
+                        const sevA = severityOrder[a.v.severity] ?? 99;
+                        const sevB = severityOrder[b.v.severity] ?? 99;
+                        if (sevA !== sevB)
+                            return sevA - sevB;
+                        // Within same severity: higher hotspot first
+                        const hsA = a.v.hotspot ?? 0;
+                        const hsB = b.v.hotspot ?? 0;
+                        if (hsA !== hsB)
+                            return hsB - hsA;
+                        // Tiebreaker: original order
+                        return a.i - b.i;
+                    });
+                    result.violations = indexed.map(x => x.v);
+                }
+            }
+        }
+        catch {
+            // Hotspot reordering is advisory — failure is non-fatal
+        }
+        // ── Spec 13 R5 Phase 2: Divergence tracking pass ──────────────────
+        // For every pair in dry_pair_history, compare the last 2 similarity
+        // measurements. If similarity has declined by ≥ divergenceThreshold
+        // for divergenceRuns consecutive runs, emit dry/diverging-clone.
+        //
+        // New rows are inserted by Phase 1 for pairs the DRY analyzer re-detects
+        // this run. Pairs that weren't re-detected don't get a new measurement
+        // this pass — full source re-read is deferred to the 20% case.
+        try {
+            const divergenceCfg = mergedOptions.analyzerConfigs?.dry?.divergence
+                ?? mergedOptions.divergence
+                ?? { divergenceThreshold: 0.05, divergenceRuns: 2, minPairSimilarity: 0.5 };
+            const threshold = divergenceCfg.divergenceThreshold ?? 0.05;
+            const requiredDeclines = divergenceCfg.divergenceRuns ?? 2;
+            if (threshold > 0) {
+                const indexDb = CodeIndexDB.getInstance();
+                await indexDb.initialize();
+                // Get all distinct pair fingerprints
+                const fingerprints = indexDb.rawDb
+                    .prepare('SELECT DISTINCT pair_fingerprint FROM dry_pair_history')
+                    .all();
+                if (fingerprints.length > 0) {
+                    const getRows = indexDb.rawDb.prepare(`
+            SELECT similarity, timestamp
+            FROM dry_pair_history
+            WHERE pair_fingerprint = ?
+            ORDER BY timestamp ASC
+          `);
+                    const divergingViolations = [];
+                    for (const { pair_fingerprint: fp } of fingerprints) {
+                        const rows = getRows.all(fp);
+                        if (rows.length < requiredDeclines + 1)
+                            continue;
+                        // Check last `requiredDeclines` consecutive pairs for decline
+                        let consecutiveDeclines = 0;
+                        for (let i = rows.length - requiredDeclines; i < rows.length; i++) {
+                            if (rows[i].similarity < rows[i - 1].similarity - threshold) {
+                                consecutiveDeclines++;
+                            }
+                        }
+                        if (consecutiveDeclines >= requiredDeclines) {
+                            // Get file/line info from the last row
+                            const lastRow = indexDb.rawDb.prepare(`
+                SELECT file1, file2, line1, line2 FROM dry_pair_history
+                WHERE pair_fingerprint = ?
+                ORDER BY timestamp DESC LIMIT 1
+              `).get(fp);
+                            if (lastRow) {
+                                const currentSim = rows[rows.length - 1].similarity;
+                                const prevSim = rows[rows.length - 2].similarity;
+                                const drop = Math.round((prevSim - currentSim) * 1000) / 1000;
+                                divergingViolations.push({
+                                    file: lastRow.file1,
+                                    line: lastRow.line1,
+                                    severity: 'suggestion',
+                                    message: `Clone pair has diverged: similarity dropped ${drop} (from ${prevSim.toFixed(3)} to ${currentSim.toFixed(3)}) across ${requiredDeclines} consecutive runs (pair: ${fp.slice(0, 12)}…). Review ${lastRow.file1}:${lastRow.line1} and ${lastRow.file2}:${lastRow.line2} for diverged logic.`,
+                                    analyzer: 'dry',
+                                    rule: 'dry/diverging-clone',
+                                });
+                            }
+                        }
+                    }
+                    if (divergingViolations.length > 0) {
+                        // Append to the dry analyzer result, or create one if none exists
+                        if (orderedAnalyzerResults['dry']) {
+                            orderedAnalyzerResults['dry'].violations.push(...divergingViolations);
+                        }
+                        else {
+                            orderedAnalyzerResults['dry'] = {
+                                violations: divergingViolations,
+                                filesProcessed: 0,
+                                executionTime: 0,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Divergence tracking is advisory — non-fatal
+        }
         // Generate summary
         const summary = generateSummary(orderedAnalyzerResults, files.length);
         // Create result
@@ -488,6 +926,9 @@ export function createAuditRunner(options = {}) {
                 analyzersRun: enabledAnalyzers,
                 configUsed: mergedOptions,
                 scope: scopeResultType,
+                provenanceResolutionMs: provenanceTiming.totalMs,
+                ...(blastRadius && { blastRadius }),
+                ...(baselineMetadata && { baseline: baselineMetadata }),
                 ...(collectedFunctions.length > 0 && {
                     collectedFunctions,
                     fileToFunctionsMap: Object.fromEntries(fileToFunctionsMap)
@@ -502,6 +943,25 @@ export function createAuditRunner(options = {}) {
         if (handoffRemaining.length > 0) {
             throw new AuditHandoffError(`${handoffRemaining.length} file(s) deferred to the next worker chunk`, result, handoffRemaining);
         }
+        // Spec 11 R1 — write to findings ledger (non-fatal: ledger is advisory)
+        const ledgerRunId = (async () => {
+            try {
+                const indexDb = CodeIndexDB.getInstance();
+                await indexDb.initialize();
+                const violations = Object.values(orderedAnalyzerResults).flatMap(ar => ar.violations);
+                // Hook-contract guard: no violation may carry an empty file path or line 0.
+                // A sentinel violation with file:'' broke the Claude Code hook's JSON consumer
+                // (Spec 15 regression). This guard is permanent — every analyzer code path
+                // must produce properly anchored violations.
+                validateHookContract(violations);
+                const scopeStr = Array.isArray(scope) ? `files:${scope.length}` : (scope ?? 'all');
+                return writeAuditToLedger(indexDb.rawDb, detectRunInput(process.argv.slice(2).join(' '), options.surface ?? 'cli', scopeStr, root, TOOL_VERSION), violations, Date.now() - startTime, 0);
+            }
+            catch (_err) {
+                // ledger write is non-fatal — audit result is still valid
+                return null;
+            }
+        })();
         return result;
     }
     /**
@@ -692,6 +1152,41 @@ function generateSummary(analyzerResults, filesAnalyzed) {
         topIssues
     };
 }
+/**
+ * Hook-contract regression guard.
+ *
+ * Every violation must carry a non-empty `file` path. A sentinel violation with
+ * `file: ''` (Spec 15 regression, commit 3419ed0) broke the Claude Code hook's
+ * JSON consumer, which expects every violation to anchor to a real file.
+ *
+ * When `line` is present, it must be > 0 — a zero line means the analyzer
+ * failed to locate the finding and shipped an unactionable anchor.
+ *
+ * Contract violations are logged as warnings and dropped from the pipeline
+ * (they are never written to the ledger or surfaced to the hook).
+ *
+ * This guard is permanent — no analyzer code path may produce violations with
+ * empty file paths or line 0.
+ */
+function validateHookContract(violations) {
+    for (let i = violations.length - 1; i >= 0; i--) {
+        const v = violations[i];
+        const problems = [];
+        if (!v.file || v.file.trim() === '') {
+            problems.push('empty file path');
+        }
+        if (v.line !== undefined && v.line === 0) {
+            problems.push('line=0 (unactionable anchor)');
+        }
+        if (problems.length > 0) {
+            console.warn(`[hook-contract] Dropping violation from analyzer '${v.analyzer ?? 'unknown'}': ` +
+                `${problems.join(', ')}. Rule: ${v.rule ?? 'unknown'}. ` +
+                `Message: "${v.message.slice(0, 120)}". ` +
+                `This is a bug in the analyzer — violations must anchor to real files with valid lines.`);
+            violations.splice(i, 1);
+        }
+    }
+}
 /**
  * Report progress
  */