code-auditor-mcp 3.4.13 → 3.4.15

package/dist/cli.js

@@ -27,6 +27,40 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new Command();
+// Spec 44 R4 — file accounting summary line + `--explain-skipped` breakdown.
+// The full per-reason file lists live in the JSON report (`metadata.fileAccounting`);
+// the CLI preview is bounded to the first ~20 files per reason.
+function printFileAccounting(result, explainSkipped) {
+    const fa = result?.metadata?.fileAccounting;
+    if (!fa)
+        return;
+    const reasons = fa.reasons ?? {};
+    const reasonNames = Object.keys(reasons);
+    const reasonCount = reasonNames.length;
+    const partialSeg = fa.partiallyAnalyzed > 0
+        ? ` · ${fa.partiallyAnalyzed.toLocaleString()} partially analyzed`
+        : '';
+    console.log(chalk.gray(`${fa.analyzed.toLocaleString()} analyzed` +
+        `${partialSeg}` +
+        ` · ${fa.dropped.toLocaleString()} dropped` +
+        ` (${reasonCount} reason${reasonCount !== 1 ? 's' : ''})`));
+    if (!explainSkipped || reasonCount === 0)
+        return;
+    console.log(chalk.gray('\n── Skipped files (by reason) ────────────────'));
+    for (const name of reasonNames.sort((a, b) => reasons[b].count - reasons[a].count)) {
+        const { count, files } = reasons[name];
+        const partialCount = files.filter((f) => f.partial).length;
+        const label = partialCount > 0
+            ? `${name}: ${count.toLocaleString()} (${partialCount.toLocaleString()} partially analyzed)`
+            : `${name}: ${count.toLocaleString()}`;
+        console.log(`  ${label}`);
+        for (const f of files.slice(0, 20)) {
+            console.log(`    ${f.filePath}${f.partial ? '  (partially analyzed)' : ''}`);
+        }
+        if (files.length > 20)
+            console.log(`    … and ${files.length - 20} more`);
+    }
+}
 // Configure the main program
 program
     .name('code-auditor')
@@ -45,9 +79,20 @@ program
     .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')
     .option('--preset <id>', 'Apply a shareable preset (repeatable)', (v, prev) => prev.concat([v]), [])
+    .option('--detach', 'Run the audit in a detached background process and print the job ID')
+    .option('--partition-strategy <strategy>', 'Partition strategy for detached runs: none, auto, or top-level')
+    .option('--max-partitions <n>', 'Maximum number of partition shards (detached runs)')
+    .option('--shard-timeout-ms <ms>', 'Per-shard timeout in milliseconds (detached runs)')
+    .option('--explain-skipped', 'Print a per-reason breakdown of files dropped from analysis')
     .action(async (options) => {
     console.log(chalk.blue('🔍 Code Quality Audit Tool'));
     console.log(chalk.gray('══════════════════════════════════════════════════'));
+    // Spec 41 — `--detach` hands off to a forked worker; the parent never parses
+    // or hashes, so it must route out before `initParsers()`.
+    if (options.detach) {
+        await runDetachedAudit(options);
+        return;
+    }
     try {
         await initParsers();
         // Validate --fail-on severity
@@ -150,6 +195,8 @@ program
             console.log(`Warnings: ${result.summary.warnings}`);
             console.log(`Suggestions: ${result.summary.suggestions}`);
         }
+        // Spec 44 R4 — file accounting: analyzed/dropped totals + optional breakdown.
+        printFileAccounting(result, !!options.explainSkipped);
         // Spec 32 — unparsed files are never silent. A run where any file failed
         // to parse (WASM abort, read error, …) must surface the count + reasons.
         const unparsedFiles = result.metadata?.unparsedFiles ?? [];
@@ -162,6 +209,17 @@ program
                 console.error(`    … and ${unparsedFiles.length - 20} more`);
             }
         }
+        // Spec 43 R5 follow-up — extensions present on disk that discovery skipped.
+        // Informational: surfaces "what isn't being analyzed here" so an unlisted
+        // extension (e.g. `.mdx`) never vanishes silently at discovery. Not an
+        // error — a skipped extension is not necessarily a defect (`.md`/`.svg`
+        // are legitimately not source), unlike `unparsedFiles` above.
+        const skippedExtensions = result.metadata?.skippedExtensions ?? [];
+        if (skippedExtensions.length > 0) {
+            console.log(chalk.gray(`\n── Not analyzed (skipped extensions) ────────`));
+            const parts = skippedExtensions.map(s => `${s.ext} (${s.count})`);
+            console.log(`  ${parts.join(', ')}`);
+        }
         // Spec 36 R7 — suppressions are reported: how many exist, where, and how
         // many are unnecessary (or reasonless). Both are errors, surfaced here.
         const suppressions = result.metadata?.suppressions;
@@ -321,6 +379,7 @@ program
     .option('--quiet', 'Suppress output when zero violations')
     .option('--fail-on-zero-files', 'Exit code 2 when any enabled analyzer matches zero source files', true)
     .option('--stdin', 'Read file paths from stdin (one per line)')
+    .option('--explain-skipped', 'Print a per-reason breakdown of files dropped from analysis')
     .option('-p, --path <projectPath>', 'Project root path', process.cwd())
     .action(async (paths, options) => {
     try {
@@ -404,7 +463,7 @@ program
             // consumer routes around. Findings only, each with file:line.
             console.log(chalk.blue('🔍 Diff-Scoped Code Audit'));
             console.log(chalk.gray('══════════════════════════════════════════════════'));
-            console.log(chalk.gray(`Files analyzed: ${result.metadata.filesAnalyzed}`));
+            printFileAccounting(result, !!options.explainSkipped);
             if (violations.length > 0) {
                 console.log(chalk.gray('\n── Violations ────────────────────────────────────'));
                 for (const v of violations) {
@@ -1792,6 +1851,339 @@ ledgerCmd
         process.exit(1);
     }
 });
+// ── Spec 41 — Detached runs & queryable findings (CLI) ──────────────────────
+// `audit --detach` forks workers/auditJobRunner; `status`/`result`/`jobs` read
+// the persisted ledger. One job model (the ledger run), one write path — these
+// are thin wrappers over ledger.ts + mcpAuditJobs.ts, not a second store.
+/** Full analyzer set — matches createAuditRunner's registry, so `--detach` produces
+ *  the same per-rule coverage as a synchronous `audit` (73 rows on recall). */
+const DETACHED_DEFAULT_ANALYZERS = [
+    'solid',
+    'dry',
+    'data-access',
+    'react',
+    'documentation',
+    'invariants',
+    'schema',
+    'styles',
+    'conventions',
+    'cross-domain',
+];
+/** Lease TTL used by read-path reclaim, mirroring mcpAuditJobs.jobLeaseTtlMs. */
+const CLI_JOB_LEASE_TTL_MS = Number(process.env.CODE_AUDITOR_JOB_LEASE_TTL_MS) || 30_000;
+function spec41StatusBadge(status) {
+    switch (status) {
+        case 'completed':
+            return chalk.green('completed');
+        case 'running':
+            return chalk.cyan('running');
+        case 'queued':
+            return chalk.blue('queued');
+        case 'failed':
+            return chalk.red('failed');
+        default:
+            return status;
+    }
+}
+function spec41SeverityColor(severity) {
+    if (severity === 'critical')
+        return chalk.red;
+    if (severity === 'warning')
+        return chalk.yellow;
+    return chalk.gray;
+}
+/**
+ * Render a run's staleness: the cheap marker (changed count) plus, when stale,
+ * the per-file diff. The cheap stat-only pass in `computeStaleness` populates
+ * `changedFiles` on divergence, so this list is the full `--stale` deliverable
+ * regardless of whether the caller requested `full`. Bounded so a mass-change
+ * doesn't flood the terminal; the JSON path always carries the complete list.
+ */
+function spec41RenderStaleness(staleness) {
+    if (!staleness) {
+        console.log(chalk.gray('  stale:    n/a'));
+        return;
+    }
+    if (!staleness.stale) {
+        console.log(chalk.gray('  stale:    no (working tree unchanged)'));
+        return;
+    }
+    console.log(chalk.yellow(`  stale:    ${staleness.changedFiles.length} file(s) changed since run`));
+    const maxFiles = 20;
+    for (const f of staleness.changedFiles.slice(0, maxFiles)) {
+        console.log(chalk.yellow(`            + ${f}`));
+    }
+    if (staleness.changedFiles.length > maxFiles) {
+        console.log(chalk.gray(`            … and ${staleness.changedFiles.length - maxFiles} more`));
+    }
+}
+/**
+ * Spec 41 — `audit --detach`. Persists a `queued` run, opens a per-run log as
+ * the child's stderr, and forks workers/auditJobRunner detached. Returns with
+ * the job id; the parent never parses or hashes, so it stays sub-second even
+ * on a minutes-long corpus.
+ */
+async function runDetachedAudit(options) {
+    // `spawn` + no IPC channel: `fork()` establishes an IPC channel, and `unref()`
+    // does NOT let the parent exit while that channel is open (Node: "unless there
+    // is an established IPC channel"). The runner talks to the ledger through the
+    // DB, never back to the parent, so there is no channel to keep — and without
+    // one the parent exits immediately, keeping `--detach` sub-second.
+    const { spawn } = await import('node:child_process');
+    const { openSync } = await import('node:fs');
+    const { createAuditJob } = await import('./services/auditJobService.js');
+    const { patchLedgerRun } = await import('./ledger.js');
+    const { resolveJobRunnerEntrypoint } = await import('./mcpAuditJobs.js');
+    const { assertAuditPathExists } = await import('./mcpToolErrors.js');
+    const { getPersistedStorageRoot } = await import('./dataPaths.js');
+    const auditPath = resolve(options.path || process.cwd());
+    const { isFile } = await assertAuditPathExists(auditPath);
+    const projectRoot = isFile ? dirname(auditPath) : auditPath;
+    const db = CodeIndexDB.getInstance(undefined, projectRoot);
+    await db.initialize();
+    const job = createAuditJob(db.rawDb, projectRoot, { surface: 'cli', command: 'audit --detach' });
+    // The log is the diagnosable trace when the child dies before its first DB
+    // patch (e.g. inside initParsers()). Lives next to the index db.
+    const logsDir = join(getPersistedStorageRoot(projectRoot), 'logs');
+    await fs.mkdir(logsDir, { recursive: true });
+    const logPath = join(logsDir, `${job.jobId}.log`);
+    const logFd = openSync(logPath, 'a');
+    const argsJson = JSON.stringify({
+        path: auditPath,
+        ...(options.partitionStrategy && { partitionStrategy: options.partitionStrategy }),
+        ...(options.maxPartitions && { maxPartitions: Number(options.maxPartitions) }),
+        ...(options.shardTimeoutMs && { shardTimeoutMs: Number(options.shardTimeoutMs) }),
+    });
+    const defaultsJson = JSON.stringify({
+        defaultAnalyzers: DETACHED_DEFAULT_ANALYZERS,
+        defaultMinSeverity: 'warning',
+        defaultGenerateCodeMap: false,
+    });
+    patchLedgerRun(db.rawDb, job.jobId, { stderrLog: logPath });
+    const child = spawn(process.execPath, [resolveJobRunnerEntrypoint(), job.jobId, argsJson, defaultsJson], {
+        detached: true,
+        stdio: ['ignore', 'ignore', logFd],
+        env: process.env,
+    });
+    child.unref();
+    console.log(chalk.green(`✓ Audit detached (job ${job.jobId})`));
+    console.log(chalk.gray(`  Monitor: code-auditor status ${job.jobId}`));
+    console.log(chalk.gray(`  Results: code-auditor result ${job.jobId}`));
+    console.log(chalk.gray(`  Log:     ${logPath}`));
+}
+program
+    .command('status <jobId>')
+    .description('Show a detached audit job status, progress, and staleness')
+    .option('-p, --path <path>', 'Project root containing the job (default: cwd)', process.cwd())
+    .option('--json', 'Output as JSON')
+    .action(async (jobId, options) => {
+    try {
+        const { getLedgerRun, reclaimStaleRunning, computeStaleness } = await import('./ledger.js');
+        const projectRoot = resolve(options.path);
+        const db = CodeIndexDB.getInstance(undefined, projectRoot);
+        await db.initialize();
+        reclaimStaleRunning(db.rawDb, projectRoot, CLI_JOB_LEASE_TTL_MS);
+        const run = getLedgerRun(db.rawDb, jobId);
+        if (!run) {
+            console.error(chalk.red(`Job not found: ${jobId}`));
+            process.exit(1);
+        }
+        const staleness = run.projectRoot ? computeStaleness(db.rawDb, jobId, run.projectRoot) : null;
+        if (options.json) {
+            process.stdout.write(JSON.stringify({ ...run, staleness }, null, 2) + '\n');
+            return;
+        }
+        let progress = '';
+        if (run.progressJson) {
+            try {
+                const p = JSON.parse(run.progressJson);
+                progress = [p.phase, p.message].filter(Boolean).join(' — ');
+                if (p.total != null)
+                    progress += ` (${p.current ?? 0}/${p.total})`;
+            }
+            catch {
+                progress = '';
+            }
+        }
+        console.log(chalk.blue(`Job ${jobId}`));
+        console.log(`  status:   ${spec41StatusBadge(run.status)}`);
+        console.log(`  path:     ${run.projectRoot ?? run.target}`);
+        console.log(`  created:  ${run.timestamp}`);
+        if (run.startedAt)
+            console.log(`  started:  ${run.startedAt}`);
+        if (run.finishedAt)
+            console.log(`  finished: ${run.finishedAt}`);
+        if (run.durationMs)
+            console.log(`  duration: ${run.durationMs}ms`);
+        if (progress)
+            console.log(`  progress: ${progress}`);
+        if (run.error)
+            console.log(chalk.red(`  error:    ${run.error}`));
+        if (run.stderrLog)
+            console.log(chalk.gray(`  log:      ${run.stderrLog}`));
+        if (run.contentHash)
+            console.log(chalk.gray(`  content:  ${run.contentHash.slice(0, 12)} (${run.filesCount} files)`));
+        spec41RenderStaleness(staleness);
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+program
+    .command('result <jobId>')
+    .description('Query a detached audit run: findings or per-rule coverage')
+    .option('-p, --path <path>', 'Project root containing the job (default: cwd)', process.cwd())
+    .option('--rule <rule>', 'Filter by rule id')
+    .option('--analyzer <analyzer>', 'Filter by analyzer')
+    .option('--file <file>', 'Filter by file path (substring match)')
+    .option('--severity <severity>', 'Filter by severity (critical|warning|suggestion)')
+    .option('--state [state]', 'Query coverage by state (fired|clean|notApplicable|unassessed); omit value for all')
+    .option('--count', 'Group findings by analyzer/rule with counts')
+    .option('--limit <n>', 'Max findings to return (0 = unbounded)', '50')
+    .option('--offset <n>', 'Findings offset', '0')
+    .option('--stale', 'Force full content re-hash for staleness')
+    .option('--json', 'Output as JSON')
+    .action(async (jobId, options) => {
+    try {
+        const { getLedgerRun, queryLedgerFindings, queryLedgerCoverage, computeStaleness } = await import('./ledger.js');
+        const projectRoot = resolve(options.path);
+        const db = CodeIndexDB.getInstance(undefined, projectRoot);
+        await db.initialize();
+        const run = getLedgerRun(db.rawDb, jobId);
+        if (!run) {
+            console.error(chalk.red(`Job not found: ${jobId}`));
+            process.exit(1);
+        }
+        const staleness = run.projectRoot
+            ? computeStaleness(db.rawDb, jobId, run.projectRoot, { full: !!options.stale })
+            : null;
+        // A finding read must never be silent about the tree it was computed
+        // against (Spec 41 R3): carry the staleness marker in human output too.
+        if (!options.json)
+            spec41RenderStaleness(staleness);
+        if (options.state !== undefined) {
+            const stateFilter = typeof options.state === 'string' ? options.state : undefined;
+            const rows = queryLedgerCoverage(db.rawDb, jobId, {
+                ...(stateFilter ? { state: stateFilter } : {}),
+                ...(options.rule ? { rule: options.rule } : {}),
+                ...(options.analyzer ? { analyzer: options.analyzer } : {}),
+            });
+            if (options.json) {
+                process.stdout.write(JSON.stringify({ runId: jobId, staleness, coverage: rows }, null, 2) + '\n');
+            }
+            else {
+                console.log(chalk.blue(stateFilter ? `Coverage — ${stateFilter}` : 'Coverage — all states'));
+                for (const r of rows) {
+                    const reason = r.reason ? chalk.gray(`  (${r.reason})`) : '';
+                    console.log(`  ${r.analyzer}/${r.ruleId}: ${r.state} × ${r.count}${reason}`);
+                }
+                if (rows.length === 0)
+                    console.log(chalk.gray('  (no rows)'));
+            }
+            return;
+        }
+        const findingFilter = {
+            ...(options.rule ? { rule: options.rule } : {}),
+            ...(options.analyzer ? { analyzer: options.analyzer } : {}),
+            ...(options.file ? { file: options.file } : {}),
+            ...(options.severity ? { severity: options.severity } : {}),
+        };
+        if (options.count) {
+            const groups = queryLedgerFindings(db.rawDb, jobId, { ...findingFilter, count: true });
+            if (options.json) {
+                process.stdout.write(JSON.stringify({ runId: jobId, staleness, groups }, null, 2) + '\n');
+            }
+            else {
+                console.log(chalk.blue('Findings by analyzer/rule'));
+                for (const g of groups)
+                    console.log(`  ${g.count}\t${g.group}`);
+                if (groups.length === 0)
+                    console.log(chalk.gray('  (no findings)'));
+            }
+            return;
+        }
+        const limit = options.limit === '0' ? 0 : parseInt(options.limit, 10) || 50;
+        const offset = parseInt(options.offset, 10) || 0;
+        const findings = queryLedgerFindings(db.rawDb, jobId, { ...findingFilter, limit, offset });
+        if (options.json) {
+            const nextOffset = limit > 0 && findings.length === limit ? offset + limit : null;
+            process.stdout.write(JSON.stringify({ runId: jobId, staleness, count: findings.length, nextOffset, findings }, null, 2) + '\n');
+        }
+        else {
+            console.log(chalk.blue(`Findings (${findings.length} shown)`));
+            for (const f of findings) {
+                const loc = f.line != null ? `${f.file}:${f.line}` : f.file;
+                const paint = spec41SeverityColor(f.severity);
+                console.log(`  ${paint(f.severity)} ${chalk.gray(loc)} [${f.analyzer}/${f.rule}] ${f.message}`);
+            }
+            if (findings.length === 0)
+                console.log(chalk.gray('  (no findings)'));
+            if (limit > 0 && findings.length === limit) {
+                console.log(chalk.gray(`  next offset: ${offset + limit} (use --offset ${offset + limit})`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+program
+    .command('jobs')
+    .description('List detached audit jobs with staleness badges')
+    .option('-p, --path <path>', 'Project root (default: cwd)', process.cwd())
+    .option('--prune', 'Delete all but the newest runs for this project')
+    .option('--keep <n>', 'Runs to keep when --prune is set', '10')
+    .option('--limit <n>', 'Runs to display (staleness computed for these)', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const { listLedgerRuns, reclaimStaleRunning, pruneLedgerRuns, computeStaleness } = await import('./ledger.js');
+        const projectRoot = resolve(options.path);
+        const db = CodeIndexDB.getInstance(undefined, projectRoot);
+        await db.initialize();
+        reclaimStaleRunning(db.rawDb, projectRoot, CLI_JOB_LEASE_TTL_MS);
+        if (options.prune) {
+            const keep = parseInt(options.keep, 10) || 10;
+            const n = pruneLedgerRuns(db.rawDb, projectRoot, keep);
+            console.log(chalk.green(`✓ Pruned ${n} run(s) — keeping ${keep} newest`));
+        }
+        const limit = parseInt(options.limit, 10) || 20;
+        const runs = listLedgerRuns(db.rawDb, projectRoot).slice(0, limit);
+        const withStaleness = runs.map((run) => {
+            let staleness = null;
+            if (run.projectRoot && run.contentHash) {
+                staleness = computeStaleness(db.rawDb, run.runId, run.projectRoot);
+            }
+            return { ...run, staleness };
+        });
+        if (options.json) {
+            process.stdout.write(JSON.stringify(withStaleness, null, 2) + '\n');
+            return;
+        }
+        if (withStaleness.length === 0) {
+            console.log(chalk.gray('No jobs yet — run `code-auditor audit --detach` first.'));
+            return;
+        }
+        console.log(chalk.blue(`Jobs (${withStaleness.length} newest)`));
+        for (const run of withStaleness) {
+            const badge = run.staleness?.stale
+                ? chalk.yellow('stale')
+                : run.staleness
+                    ? chalk.green('current')
+                    : chalk.gray('n/a');
+            console.log(`  ${spec41StatusBadge(run.status)}  ${chalk.cyan(run.runId)}  [${badge}]`);
+            console.log(`    ${run.projectRoot ?? run.target}  ${run.timestamp}`);
+            if (run.error)
+                console.log(`    ${chalk.red(run.error)}`);
+        }
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
 // ── Conventions command — Spec 12 R3 ────────────────────────────────────────
 const conventionsCmd = program
     .command('conventions')