code-auditor-mcp 4.1.0 → 5.0.1

package/dist/languages/typescript/database-packages.json

@@ -0,0 +1,19 @@
+{
+    "better-sqlite3": ["Database"],
+    "drizzle-orm": ["drizzle", "sql"],
+    "@prisma/client": ["PrismaClient"],
+    "pg": ["Pool", "Client", "PoolClient"],
+    "mysql2": ["Pool", "Connection", "PoolConnection", "createPool", "createConnection"],
+    "postgres": ["Sql"],
+    "kysely": ["Kysely"],
+    "knex": ["Knex"],
+    "mongodb": ["MongoClient", "Db", "Collection"],
+    "mongoose": ["Connection", "connect"],
+    "@libsql/client": ["createClient", "Client"],
+    "@planetscale/database": ["connect", "Connection", "Client"],
+    "@neondatabase/serverless": ["neon", "Pool", "Client"],
+    "@vercel/postgres": ["sql", "db", "createClient", "createPool"],
+    "bun:sqlite": ["Database"],
+    "node:sqlite": ["DatabaseSync", "StatementSync"],
+    "@cloudflare/workers-types": ["D1Database", "D1PreparedStatement"]
+}

package/dist/ledger.d.ts

@@ -144,6 +144,17 @@ export interface StalenessResult {
         current: number | null;
     };
 }
+/**
+ * Write an audit run and its findings to the ledger.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runInput - The run's input metadata (git, command, surface, scope, target).
+ * @param violations - The violations found during the run.
+ * @param durationMs - The run duration in milliseconds.
+ * @param exitStatus - The process exit status for the run.
+ * @param opts - Optional run ID (attach) and rule coverage data.
+ * @returns The run ID that was written.
+ */
 export declare function writeAuditToLedger(db: SqliteDatabase, runInput: LedgerRunInput, violations: Violation[], durationMs: number, exitStatus: number, opts?: {
     runId?: string;
     coverage?: RuleCoverage[];
@@ -151,27 +162,80 @@ export declare function writeAuditToLedger(db: SqliteDatabase, runInput: LedgerR
 /**
  * Create a detached-run row in `queued` (or another initial) status without
  * findings. Returns the run id, which is the job id for `--detach`/MCP.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runInput - The run's input metadata.
+ * @param opts - Optional initial status and project root.
+ * @returns The new run ID.
  */
 export declare function createLedgerRun(db: SqliteDatabase, runInput: LedgerRunInput, opts?: {
     status?: LedgerRunStatus;
     projectRoot?: string;
 }): string;
-/** Patch mutable lifecycle columns on a run row. */
+/**
+ * Patch mutable lifecycle columns on a run row.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run ID to patch.
+ * @param patch - The lifecycle columns to update.
+ */
 export declare function patchLedgerRun(db: SqliteDatabase, runId: string, patch: LedgerRunPatch): void;
-/** Update the exit status of a ledger run — called by CLI/MCP after determining it. */
+/**
+ * Update the exit status of a ledger run — called by CLI/MCP after determining it.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run ID to update.
+ * @param exitStatus - The exit status to record.
+ */
 export declare function updateLedgerRunStatus(db: SqliteDatabase, runId: string, exitStatus: number): void;
 export declare function getLedgerRun(db: SqliteDatabase, runId: string): LedgerRunDetail | null;
+/**
+ * List ledger runs, optionally filtered to a project root.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param projectRoot - Optional project root to filter runs by.
+ * @returns The matching runs in reverse chronological order.
+ */
 export declare function listLedgerRuns(db: SqliteDatabase, projectRoot?: string): LedgerRunDetail[];
+/**
+ * Query the findings recorded for a ledger run.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run whose findings to query.
+ * @param q - Optional filters, grouping, and pagination.
+ * @returns Either the matching findings or grouped counts.
+ */
 export declare function queryLedgerFindings(db: SqliteDatabase, runId: string, q?: LedgerFindingsQuery): LedgerFindingRecord[] | Array<{
     group: string;
     count: number;
 }>;
+/**
+ * Query the rule coverage recorded for a ledger run.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run whose coverage to query.
+ * @param q - Optional rule, analyzer, and state filters.
+ * @returns The matching coverage rows.
+ */
 export declare function queryLedgerCoverage(db: SqliteDatabase, runId: string, q?: LedgerCoverageQuery): LedgerCoverageRow[];
+/**
+ * Hash a set of files into an aggregate content hash and manifest.
+ *
+ * @param files - The file paths to hash.
+ * @param projectRoot - Optional root used to relativize paths.
+ * @returns The aggregate hash, file count, manifest, and newest mtime.
+ */
 export declare function hashFileSet(files: string[], projectRoot?: string): FileSetHash;
 /**
  * Compare a run's recorded content against the working tree. Cheap-first: a
  * stat-only pass (count + newest mtime) gates the full content re-hash; only
  * when those diverge (or `full` is requested) are file contents re-read.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run whose recorded content is compared.
+ * @param projectRoot - The project root to compare against.
+ * @param opts - Optional `full` flag to force a full re-hash.
+ * @returns The staleness result with changed files and hashes.
  */
 export declare function computeStaleness(db: SqliteDatabase, runId: string, projectRoot: string, opts?: {
     full?: boolean;
@@ -198,6 +262,11 @@ export interface RunningLeaseEvaluation {
  * runner is busy: a queued job reads the pool and sleeps rather than grabbing
  * `BEGIN IMMEDIATE` every cycle, so it never contends with the running job's
  * write transactions. The actual reclaim/claim write happens later, under lock.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param projectRoot - The project root whose running leases are evaluated.
+ * @param ttlMs - The heartbeat staleness threshold in milliseconds.
+ * @returns The running count, cutoff, and reclaimable candidates.
  */
 export declare function evaluateStaleRunning(db: SqliteDatabase, projectRoot: string, ttlMs: number): RunningLeaseEvaluation;
 /**
@@ -206,6 +275,11 @@ export declare function evaluateStaleRunning(db: SqliteDatabase, projectRoot: st
  * caller's transaction, so a heartbeat refreshed between evaluation and this
  * write is not wrongly reclaimed. Does not open its own transaction — callers
  * wrap it in one (or rely on it being a single implicit transaction otherwise).
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param reclaimable - The reclaim candidates to mark failed.
+ * @param cutoff - The stale cutoff timestamp used to re-check each row.
+ * @returns The number of runs marked failed.
  */
 export declare function markRunsFailed(db: SqliteDatabase, reclaimable: ReclaimCandidate[], cutoff: string): number;
 /**
@@ -224,10 +298,38 @@ export declare function reclaimStaleRunning(db: SqliteDatabase, projectRoot: str
  * Delete all but the newest `keepN` runs for a project root. Findings and
  * coverage cascade via `ON DELETE CASCADE` (foreign_keys is ON). Returns the
  * number of runs pruned.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param projectRoot - The project root whose runs are pruned.
+ * @param keepN - The number of newest runs to keep.
+ * @returns The number of runs pruned.
  */
 export declare function pruneLedgerRuns(db: SqliteDatabase, projectRoot: string, keepN: number): number;
+/**
+ * Build ledger run input by auto-detecting git info for a target.
+ *
+ * @param command - The invoking command name.
+ * @param surface - The invoking surface (cli, mcp, library, hook, daemon).
+ * @param scope - The audit scope.
+ * @param target - The audited project path.
+ * @param toolVersion - The code-auditor package version.
+ * @returns The assembled run input.
+ */
 export declare function detectRunInput(command: string, surface: LedgerRunInput['surface'], scope: string, target: string, toolVersion: string): LedgerRunInput;
+/**
+ * List ledger runs as summaries with finding counts.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @returns Run summaries in reverse chronological order.
+ */
 export declare function listRuns(db: SqliteDatabase): LedgerRunSummary[];
+/**
+ * Export ledger runs and their findings, optionally from a timestamp.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param since - Optional ISO timestamp lower bound.
+ * @returns The exported runs and findings.
+ */
 export declare function exportLedger(db: SqliteDatabase, since?: string): {
     runs: LedgerRunRecord[];
     findings: LedgerFindingRecord[];
@@ -260,8 +362,15 @@ export interface TrendReport {
  *
  * @param db        The better-sqlite3 database handle.
  * @param sinceRunId  Only consider runs after this run ID.
+ * @returns The trend report, or null when fewer than 2 comparable runs exist.
  */
 export declare function getTrends(db: SqliteDatabase, sinceRunId?: string): TrendReport | null;
+/**
+ * Aggregate per-analyzer and per-rule finding statistics across the ledger.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @returns The aggregated ledger statistics.
+ */
 export declare function getLedgerStats(db: SqliteDatabase): LedgerStats;
 /**
  * D1 interim archive format (Directive D1): directory of JSON files per run.
@@ -285,6 +394,13 @@ export interface D1InterimRun {
         symbol?: string;
     }>;
 }
+/**
+ * Import legacy D1 interim JSON run files from a directory into the ledger.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param dirPath - The directory containing the JSON run files.
+ * @returns Counts of imported and skipped runs.
+ */
 export declare function importLedgerFromDir(db: SqliteDatabase, dirPath: string): {
     imported: number;
     skipped: number;

package/dist/ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"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"}

package/dist/ledger.js

@@ -59,7 +59,29 @@ function getToolGitSha() {
     }
 }
 // ── Writing ───────────────────────────────────────────────────────────────
+/**
+ * Write an audit run and its findings to the ledger.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runInput - The run's input metadata (git, command, surface, scope, target).
+ * @param violations - The violations found during the run.
+ * @param durationMs - The run duration in milliseconds.
+ * @param exitStatus - The process exit status for the run.
+ * @param opts - Optional run ID (attach) and rule coverage data.
+ * @returns The run ID that was written.
+ */
 export function writeAuditToLedger(db, runInput, violations, durationMs, exitStatus, opts) {
+    return db.transaction(() => writeAuditToLedgerRaw(db, runInput, violations, durationMs, exitStatus, opts))();
+}
+/**
+ * Transaction-less core of {@link writeAuditToLedger}: runs the run/finding/
+ * coverage inserts without opening its own transaction, returning the run id.
+ * `importLedgerFromDir` wraps its whole file loop in one transaction and calls
+ * this per run — calling {@link writeAuditToLedger} there would nest
+ * transactions (better-sqlite3 rejects nesting), and the per-run inserts are
+ * already batched by the outer transaction.
+ */
+function writeAuditToLedgerRaw(db, runInput, violations, durationMs, exitStatus, opts) {
     const isAttach = !!opts?.runId;
     const runId = opts?.runId ?? randomUUID();
     const timestamp = new Date().toISOString();
@@ -78,41 +100,43 @@ export function writeAuditToLedger(db, runInput, violations, durationMs, exitSta
       (run_id, analyzer, rule_id, state, count, reason)
     VALUES (?, ?, ?, ?, ?, ?)
   `);
-    const tx = db.transaction(() => {
-        if (isAttach) {
-            // Attach to a pre-existing run (detached lifecycle): record results and
-            // close the lifecycle. The run row itself was created by createLedgerRun.
-            db.prepare(`
-        UPDATE findings_ledger_runs
-        SET duration_ms = ?, exit_status = ?, finished_at = ?, status = 'completed'
-        WHERE run_id = ?
-      `).run(durationMs, exitStatus, timestamp, runId);
-        }
-        else {
-            insertRun.run(runId, timestamp, runInput.gitSha ?? null, runInput.gitDirty ? 1 : 0, runInput.toolVersion, runInput.toolGitSha ?? null, runInput.command, runInput.surface, runInput.scope, runInput.target, durationMs, exitStatus);
-        }
-        for (const v of violations) {
-            const symbol = extractSymbol(v);
-            const fp = fingerprint({
-                analyzer: v.analyzer || 'unknown',
-                rule: v.rule ?? '',
-                file: v.file,
-                symbol,
-            });
-            insertFinding.run(runId, v.analyzer || 'unknown', v.rule ?? '', v.severity, v.message, v.file, v.line ?? null, symbol, fp);
-        }
-        if (opts?.coverage) {
-            for (const c of opts.coverage) {
-                insertCoverage.run(runId, c.analyzer, c.ruleId, c.state, c.count, c.reason ?? null);
-            }
+    if (isAttach) {
+        // Attach to a pre-existing run (detached lifecycle): record results and
+        // close the lifecycle. The run row itself was created by createLedgerRun.
+        db.prepare(`
+      UPDATE findings_ledger_runs
+      SET duration_ms = ?, exit_status = ?, finished_at = ?, status = 'completed'
+      WHERE run_id = ?
+    `).run(durationMs, exitStatus, timestamp, runId);
+    }
+    else {
+        insertRun.run(runId, timestamp, runInput.gitSha ?? null, runInput.gitDirty ? 1 : 0, runInput.toolVersion, runInput.toolGitSha ?? null, runInput.command, runInput.surface, runInput.scope, runInput.target, durationMs, exitStatus);
+    }
+    for (const v of violations) {
+        const symbol = extractSymbol(v);
+        const fp = fingerprint({
+            analyzer: v.analyzer || 'unknown',
+            rule: v.rule ?? '',
+            file: v.file,
+            symbol,
+        });
+        insertFinding.run(runId, v.analyzer || 'unknown', v.rule ?? '', v.severity, v.message, v.file, v.line ?? null, symbol, fp);
+    }
+    if (opts?.coverage) {
+        for (const c of opts.coverage) {
+            insertCoverage.run(runId, c.analyzer, c.ruleId, c.state, c.count, c.reason ?? null);
         }
-    });
-    tx();
+    }
     return runId;
 }
 /**
  * Create a detached-run row in `queued` (or another initial) status without
  * findings. Returns the run id, which is the job id for `--detach`/MCP.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runInput - The run's input metadata.
+ * @param opts - Optional initial status and project root.
+ * @returns The new run ID.
  */
 export function createLedgerRun(db, runInput, opts = {}) {
     const runId = randomUUID();
@@ -125,7 +149,13 @@ export function createLedgerRun(db, runInput, opts = {}) {
   `).run(runId, timestamp, runInput.gitSha ?? null, runInput.gitDirty ? 1 : 0, runInput.toolVersion, runInput.toolGitSha ?? null, runInput.command, runInput.surface, runInput.scope, runInput.target, status, opts.projectRoot ?? null);
     return runId;
 }
-/** Patch mutable lifecycle columns on a run row. */
+/**
+ * Patch mutable lifecycle columns on a run row.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run ID to patch.
+ * @param patch - The lifecycle columns to update.
+ */
 export function patchLedgerRun(db, runId, patch) {
     const sets = [];
     const values = [];
@@ -164,7 +194,13 @@ export function patchLedgerRun(db, runId, patch) {
     values.push(runId);
     db.prepare(`UPDATE findings_ledger_runs SET ${sets.join(', ')} WHERE run_id = ?`).run(...values);
 }
-/** Update the exit status of a ledger run — called by CLI/MCP after determining it. */
+/**
+ * Update the exit status of a ledger run — called by CLI/MCP after determining it.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run ID to update.
+ * @param exitStatus - The exit status to record.
+ */
 export function updateLedgerRunStatus(db, runId, exitStatus) {
     db.prepare('UPDATE findings_ledger_runs SET exit_status = ? WHERE run_id = ?').run(exitStatus, runId);
 }
@@ -224,19 +260,30 @@ export function getLedgerRun(db, runId) {
     const row = db.prepare(`SELECT ${RUN_DETAIL_SELECT} FROM findings_ledger_runs WHERE run_id = ?`).get(runId);
     return row ? mapRunRow(row) : null;
 }
+/**
+ * List ledger runs, optionally filtered to a project root.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param projectRoot - Optional project root to filter runs by.
+ * @returns The matching runs in reverse chronological order.
+ */
 export function listLedgerRuns(db, projectRoot) {
-    const params = [];
-    let where = '';
-    if (projectRoot) {
-        where = 'WHERE project_root = ?';
-        params.push(projectRoot);
-    }
+    const params = projectRoot ? [projectRoot] : [];
+    const where = projectRoot ? 'WHERE project_root = ?' : '';
     const rows = db.prepare(`
     SELECT ${RUN_DETAIL_SELECT} FROM findings_ledger_runs ${where}
     ORDER BY timestamp DESC
   `).all(...params);
     return rows.map(mapRunRow);
 }
+/**
+ * Query the findings recorded for a ledger run.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run whose findings to query.
+ * @param q - Optional filters, grouping, and pagination.
+ * @returns Either the matching findings or grouped counts.
+ */
 export function queryLedgerFindings(db, runId, q = {}) {
     const where = ['run_id = ?'];
     const params = [runId];
@@ -291,6 +338,14 @@ export function queryLedgerFindings(db, runId, q = {}) {
         fingerprint: String(r.fingerprint ?? ''),
     }));
 }
+/**
+ * Query the rule coverage recorded for a ledger run.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run whose coverage to query.
+ * @param q - Optional rule, analyzer, and state filters.
+ * @returns The matching coverage rows.
+ */
 export function queryLedgerCoverage(db, runId, q = {}) {
     const where = ['run_id = ?'];
     const params = [runId];
@@ -321,6 +376,13 @@ export function queryLedgerCoverage(db, runId, q = {}) {
     }));
 }
 // ── Spec 41 — Provenance & staleness ───────────────────────────────────────
+/**
+ * Hash a set of files into an aggregate content hash and manifest.
+ *
+ * @param files - The file paths to hash.
+ * @param projectRoot - Optional root used to relativize paths.
+ * @returns The aggregate hash, file count, manifest, and newest mtime.
+ */
 export function hashFileSet(files, projectRoot) {
     const hashes = [];
     let newestMtime = null;
@@ -356,6 +418,12 @@ export function hashFileSet(files, projectRoot) {
  * Compare a run's recorded content against the working tree. Cheap-first: a
  * stat-only pass (count + newest mtime) gates the full content re-hash; only
  * when those diverge (or `full` is requested) are file contents re-read.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param runId - The run whose recorded content is compared.
+ * @param projectRoot - The project root to compare against.
+ * @param opts - Optional `full` flag to force a full re-hash.
+ * @returns The staleness result with changed files and hashes.
  */
 export function computeStaleness(db, runId, projectRoot, opts = {}) {
     const run = getLedgerRun(db, runId);
@@ -517,6 +585,11 @@ function isSameProcessAlive(pid, recordedStartedAt) {
  * runner is busy: a queued job reads the pool and sleeps rather than grabbing
  * `BEGIN IMMEDIATE` every cycle, so it never contends with the running job's
  * write transactions. The actual reclaim/claim write happens later, under lock.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param projectRoot - The project root whose running leases are evaluated.
+ * @param ttlMs - The heartbeat staleness threshold in milliseconds.
+ * @returns The running count, cutoff, and reclaimable candidates.
  */
 export function evaluateStaleRunning(db, projectRoot, ttlMs) {
     const cutoff = new Date(Date.now() - ttlMs).toISOString();
@@ -561,6 +634,11 @@ export function evaluateStaleRunning(db, projectRoot, ttlMs) {
  * caller's transaction, so a heartbeat refreshed between evaluation and this
  * write is not wrongly reclaimed. Does not open its own transaction — callers
  * wrap it in one (or rely on it being a single implicit transaction otherwise).
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param reclaimable - The reclaim candidates to mark failed.
+ * @param cutoff - The stale cutoff timestamp used to re-check each row.
+ * @returns The number of runs marked failed.
  */
 export function markRunsFailed(db, reclaimable, cutoff) {
     if (reclaimable.length === 0)
@@ -602,6 +680,11 @@ export function reclaimStaleRunning(db, projectRoot, ttlMs) {
  * Delete all but the newest `keepN` runs for a project root. Findings and
  * coverage cascade via `ON DELETE CASCADE` (foreign_keys is ON). Returns the
  * number of runs pruned.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param projectRoot - The project root whose runs are pruned.
+ * @param keepN - The number of newest runs to keep.
+ * @returns The number of runs pruned.
  */
 export function pruneLedgerRuns(db, projectRoot, keepN) {
     const rows = db.prepare(`
@@ -614,6 +697,16 @@ export function pruneLedgerRuns(db, projectRoot, keepN) {
     return toDelete.length;
 }
 // ── Auto-detect git info ──────────────────────────────────────────────────
+/**
+ * Build ledger run input by auto-detecting git info for a target.
+ *
+ * @param command - The invoking command name.
+ * @param surface - The invoking surface (cli, mcp, library, hook, daemon).
+ * @param scope - The audit scope.
+ * @param target - The audited project path.
+ * @param toolVersion - The code-auditor package version.
+ * @returns The assembled run input.
+ */
 export function detectRunInput(command, surface, scope, target, toolVersion) {
     const git = getGitInfo(target);
     return {
@@ -628,6 +721,12 @@ export function detectRunInput(command, surface, scope, target, toolVersion) {
     };
 }
 // ── Reading ───────────────────────────────────────────────────────────────
+/**
+ * List ledger runs as summaries with finding counts.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @returns Run summaries in reverse chronological order.
+ */
 export function listRuns(db) {
     const rows = db.prepare(`
     SELECT
@@ -659,13 +758,16 @@ export function listRuns(db) {
         toolGitSha: r.toolGitSha ?? null,
     }));
 }
+/**
+ * Export ledger runs and their findings, optionally from a timestamp.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param since - Optional ISO timestamp lower bound.
+ * @returns The exported runs and findings.
+ */
 export function exportLedger(db, since) {
-    const runParams = [];
-    let runWhere = '';
-    if (since) {
-        runWhere = 'WHERE timestamp >= ?';
-        runParams.push(since);
-    }
+    const runParams = since ? [since] : [];
+    const runWhere = since ? 'WHERE timestamp >= ?' : '';
     const runs = db.prepare(`
     SELECT
       run_id AS runId,
@@ -725,6 +827,7 @@ export function exportLedger(db, since) {
  *
  * @param db        The better-sqlite3 database handle.
  * @param sinceRunId  Only consider runs after this run ID.
+ * @returns The trend report, or null when fewer than 2 comparable runs exist.
  */
 export function getTrends(db, sinceRunId) {
     // 1. Fetch full-scope runs, optionally filtered by sinceRunId
@@ -837,6 +940,12 @@ export function getTrends(db, sinceRunId) {
         perRule,
     };
 }
+/**
+ * Aggregate per-analyzer and per-rule finding statistics across the ledger.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @returns The aggregated ledger statistics.
+ */
 export function getLedgerStats(db) {
     const totalRuns = db.prepare('SELECT COUNT(*) AS cnt FROM findings_ledger_runs').get().cnt;
     const findingRows = db.prepare(`
@@ -858,6 +967,13 @@ export function getLedgerStats(db) {
     }
     return { totalRuns, perAnalyzer };
 }
+/**
+ * Import legacy D1 interim JSON run files from a directory into the ledger.
+ *
+ * @param db - The better-sqlite3 database handle.
+ * @param dirPath - The directory containing the JSON run files.
+ * @returns Counts of imported and skipped runs.
+ */
 export function importLedgerFromDir(db, dirPath) {
     if (!existsSync(dirPath)) {
         throw new Error(`Directory not found: ${dirPath}`);
@@ -865,6 +981,7 @@ export function importLedgerFromDir(db, dirPath) {
     const files = readdirSync(dirPath).filter((f) => f.endsWith('.json'));
     let imported = 0;
     let skipped = 0;
+    const parsedRuns = [];
     for (const file of files) {
         try {
             const raw = readFileSync(join(dirPath, file), 'utf-8');
@@ -890,13 +1007,18 @@ export function importLedgerFromDir(db, dirPath) {
                 scope: data.scope || 'full',
                 target: data.target || dirPath,
             };
-            writeAuditToLedger(db, runInput, violations, 0, 0);
-            imported++;
+            parsedRuns.push({ runInput, violations });
         }
         catch {
             skipped++;
         }
     }
+    db.transaction(() => {
+        for (const run of parsedRuns) {
+            writeAuditToLedgerRaw(db, run.runInput, run.violations, 0, 0);
+            imported++;
+        }
+    })();
     return { imported, skipped };
 }
 //# sourceMappingURL=ledger.js.map