auditor-lambda 0.10.2 → 0.10.7

package/dist/cli/dispatchStatusCommand.js

@@ -0,0 +1,68 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readJsonFile, isFileMissingError } from "@audit-tools/shared";
+import { ACTIVE_DISPATCH_FILENAME, loadDispatchResultMap } from "./dispatch.js";
+import { getArtifactsDir } from "./args.js";
+export async function cmdDispatchStatus(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const activeDispatchPath = join(artifactsDir, ACTIVE_DISPATCH_FILENAME);
+    let activeDispatch = null;
+    try {
+        activeDispatch = await readJsonFile(activeDispatchPath);
+    }
+    catch (e) {
+        if (!isFileMissingError(e))
+            throw e;
+    }
+    if (!activeDispatch) {
+        console.log(JSON.stringify({ status: "no_active_dispatch" }, null, 2));
+        return;
+    }
+    const runDir = join(artifactsDir, "runs", activeDispatch.run_id);
+    const resultMap = await loadDispatchResultMap(runDir);
+    if (!resultMap) {
+        console.log(JSON.stringify({
+            status: "missing_result_map",
+            run_id: activeDispatch.run_id,
+        }, null, 2));
+        return;
+    }
+    const packetIds = [...new Set(resultMap.entries.map((e) => e.packet_id))];
+    const packetStatus = [];
+    for (const pid of packetIds) {
+        if (pid === "__prior_dispatch__")
+            continue;
+        const entries = resultMap.entries.filter((e) => e.packet_id === pid);
+        let completed = 0;
+        const missing = [];
+        for (const entry of entries) {
+            try {
+                await readFile(entry.result_path, "utf8");
+                completed++;
+            }
+            catch {
+                missing.push(entry.task_id);
+            }
+        }
+        packetStatus.push({
+            packet_id: pid,
+            task_count: entries.length,
+            completed_count: completed,
+            missing_task_ids: missing,
+        });
+    }
+    const totalTasks = packetStatus.reduce((s, p) => s + p.task_count, 0);
+    const completedTasks = packetStatus.reduce((s, p) => s + p.completed_count, 0);
+    const completedPackets = packetStatus.filter((p) => p.missing_task_ids.length === 0).length;
+    console.log(JSON.stringify({
+        run_id: activeDispatch.run_id,
+        dispatch_status: activeDispatch.status,
+        created_at: activeDispatch.created_at,
+        total_packets: packetStatus.length,
+        completed_packets: completedPackets,
+        total_tasks: totalTasks,
+        completed_tasks: completedTasks,
+        missing_tasks: totalTasks - completedTasks,
+        packets: packetStatus,
+    }, null, 2));
+}

package/dist/cli/explainTaskCommand.d.ts

@@ -0,0 +1 @@
+export declare function cmdExplainTask(argv: string[]): Promise<void>;

package/dist/cli/explainTaskCommand.js

@@ -0,0 +1,33 @@
+import { loadArtifactBundle } from "../io/artifacts.js";
+import { getArtifactsDir, getFlag } from "./args.js";
+export async function cmdExplainTask(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const taskId = getFlag(argv, "--task-id") ?? argv[3];
+    if (!taskId) {
+        throw new Error("explain-task requires <task_id> or --task-id <task_id>");
+    }
+    const bundle = await loadArtifactBundle(artifactsDir);
+    const task = [...(bundle.audit_tasks ?? []), ...(bundle.requeue_tasks ?? [])].find((item) => item.task_id === taskId);
+    if (!task) {
+        throw new Error(`Unknown task_id '${taskId}'.`);
+    }
+    const coverageEntries = (bundle.coverage_matrix?.files ?? [])
+        .filter((file) => task.file_paths.includes(file.path))
+        .sort((a, b) => a.path.localeCompare(b.path));
+    const matchingResults = (bundle.audit_results ?? []).filter((result) => result.task_id === task.task_id);
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        task_id: task.task_id,
+        task,
+        file_count: task.file_paths.length,
+        coverage_entries: coverageEntries,
+        pending_coverage: coverageEntries
+            .map((file) => ({
+            path: file.path,
+            missing_lenses: file.required_lenses.filter((lens) => !file.completed_lenses.includes(lens)),
+        }))
+            .filter((file) => file.missing_lenses.length > 0),
+        matching_result_count: matchingResults.length,
+        matching_finding_ids: matchingResults.flatMap((result) => result.findings.map((finding) => finding.id)),
+    }, null, 2));
+}

package/dist/cli/importExternalAnalyzerCommand.d.ts

@@ -0,0 +1 @@
+export declare function cmdImportExternalAnalyzer(argv: string[]): Promise<void>;

package/dist/cli/importExternalAnalyzerCommand.js

@@ -0,0 +1,20 @@
+import { readJsonFile } from "@audit-tools/shared";
+import { runAuditStep } from "./auditStep.js";
+import { getArtifactsDir, getFlag, getRootDir } from "./args.js";
+export async function cmdImportExternalAnalyzer(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const sourcePath = getFlag(argv, "--external-analyzer-results", `${artifactsDir}/external_analyzer_results.json`);
+    const externalAnalyzerResults = await readJsonFile(sourcePath);
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "external_analyzer_import_executor",
+        externalAnalyzerPath: sourcePath,
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        tool: externalAnalyzerResults.tool,
+        imported_count: externalAnalyzerResults.results.length,
+        selected_executor: result.selected_executor,
+    }, null, 2));
+}

package/dist/cli/ingestResultsCommand.d.ts

@@ -0,0 +1 @@
+export declare function cmdIngestResults(argv: string[]): Promise<void>;

package/dist/cli/ingestResultsCommand.js

@@ -0,0 +1,34 @@
+import { runAuditStep, ingestBatchAuditResults } from "./auditStep.js";
+import { getArtifactsDir, getBatchResultsDir, getFlag, getRootDir } from "./args.js";
+export async function cmdIngestResults(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const batchResultsDir = getBatchResultsDir(argv);
+    if (batchResultsDir && getFlag(argv, "--results")) {
+        throw new Error("Use either --results <file> or --batch-results <dir>, not both.");
+    }
+    if (batchResultsDir) {
+        const result = await ingestBatchAuditResults({
+            root: getRootDir(argv),
+            artifactsDir,
+            batchDir: batchResultsDir,
+        });
+        console.log(JSON.stringify({
+            artifacts_dir: artifactsDir,
+            imported_files: result.batchFiles,
+            selected_executor: result.selected_executor,
+            progress_summary: result.progress_summary,
+        }, null, 2));
+        return;
+    }
+    const result = await runAuditStep({
+        root: getRootDir(argv),
+        artifactsDir,
+        preferredExecutor: "result_ingestion_executor",
+        auditResultsPath: getFlag(argv, "--results"),
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+    }, null, 2));
+}

package/dist/cli/intakeCommand.d.ts

@@ -0,0 +1 @@
+export declare function cmdIntake(argv: string[]): Promise<void>;

package/dist/cli/intakeCommand.js

@@ -0,0 +1,17 @@
+import { runAuditStep } from "./auditStep.js";
+import { getArtifactsDir, getRootDir, warnIfNotGitRepo } from "./args.js";
+export async function cmdIntake(argv) {
+    const root = getRootDir(argv);
+    warnIfNotGitRepo(root);
+    const artifactsDir = getArtifactsDir(argv);
+    const result = await runAuditStep({
+        root,
+        artifactsDir,
+        preferredExecutor: "intake_executor",
+    });
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        selected_executor: result.selected_executor,
+        progress_summary: result.progress_summary,
+    }, null, 2));
+}

package/dist/cli/lineIndex.js

@@ -8,9 +8,8 @@ import { countLines } from "./args.js";
 const LINE_COUNT_BATCH_SIZE = 25;
 export async function buildLineIndex(root, repoManifest) {
     const entries = [];
-    const batchSize = LINE_COUNT_BATCH_SIZE;
-    for (let i = 0; i < repoManifest.files.length; i += batchSize) {
-        const batch = repoManifest.files.slice(i, i + batchSize);
+    for (let i = 0; i < repoManifest.files.length; i += LINE_COUNT_BATCH_SIZE) {
+        const batch = repoManifest.files.slice(i, i + LINE_COUNT_BATCH_SIZE);
         const results = await Promise.all(batch.map(async (file) => {
             try {
                 return [
@@ -18,7 +17,8 @@ export async function buildLineIndex(root, repoManifest) {
                     await countLines(resolve(root, file.path)),
                 ];
             }
-            catch {
+            catch (err) {
+                console.warn(`[lineIndex] Failed to count lines for '${file.path}': ${err instanceof Error ? err.message : String(err)}`);
                 return [file.path, 0];
             }
         }));
@@ -28,14 +28,21 @@ export async function buildLineIndex(root, repoManifest) {
 }
 export async function buildLineIndexForPaths(root, paths) {
     const uniquePaths = [...new Set(paths)].sort();
-    const entries = await Promise.all(uniquePaths.map(async (path) => {
-        try {
-            return [path, await countLines(resolve(root, path))];
-        }
-        catch {
-            return [path, 0];
-        }
-    }));
+    const entries = [];
+    const batchSize = LINE_COUNT_BATCH_SIZE;
+    for (let i = 0; i < uniquePaths.length; i += batchSize) {
+        const batch = uniquePaths.slice(i, i + batchSize);
+        const results = await Promise.all(batch.map(async (path) => {
+            try {
+                return [path, await countLines(resolve(root, path))];
+            }
+            catch (err) {
+                console.warn(`[lineIndex] Failed to count lines for '${path}': ${err instanceof Error ? err.message : String(err)}`);
+                return [path, 0];
+            }
+        }));
+        entries.push(...results);
+    }
     return Object.fromEntries(entries);
 }
 export async function addFileLineCountHints(root, tasks) {

package/dist/cli/mergeAndIngestCommand.js

@@ -1,11 +1,12 @@
-import { readFile, readdir } from "node:fs/promises";
+import { readFile, readdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { isFileMissingError, readJsonFile, writeJsonFile } from "@audit-tools/shared";
 import { validateAuditResults } from "../validation/auditResults.js";
 import { runAuditStep } from "./auditStep.js";
 import { DISPATCH_RESULT_MAP_FILENAME, ACTIVE_DISPATCH_FILENAME, loadDispatchResultMap, entriesByTaskId, buildPendingAuditTasks, } from "./dispatch.js";
 import { addFileLineCountHints } from "./lineIndex.js";
-import { isCanonicalResultFilename, getArtifactsDir, getFlag } from "./args.js";
+import { isCanonicalResultFilename, taskResultPath, getArtifactsDir, getFlag } from "./args.js";
 import { buildWorkerResult } from "./workerResult.js";
 import { PACKET_SCHEMA_FILENAMES } from "../io/runArtifacts.js";
 // Schema pointer files prepare-dispatch copies into task-results/ for optional
@@ -38,8 +39,31 @@ export async function cmdMergeAndIngest(argv) {
             throw e;
     }
     if (priorSummary) {
-        console.log(JSON.stringify({ ...priorSummary, idempotent_replay: true }, null, 2));
-        return;
+        // A completion marker can go stale. Selective deepening appends new pending
+        // tasks to the SAME run-id, and — in the no-progress-loop bug — their answers
+        // already sit on disk under canonical per-task names while the marker says the
+        // run is done. If any pending task has a recoverable on-disk result, the marker
+        // no longer reflects reality: discard it and re-process so those answers ingest
+        // instead of replaying a no-op forever. A genuinely terminal run (no pending
+        // tasks, or pending tasks not yet answered — e.g. a new round handled under a
+        // different run-id) still replays cleanly.
+        let pendingWithResults = 0;
+        try {
+            const pending = await readJsonFile(tasksPath);
+            for (const task of pending) {
+                if (existsSync(taskResultPath(taskResultsDir, task.task_id))) {
+                    pendingWithResults++;
+                }
+            }
+        }
+        catch { /* no pending-tasks file — treat as terminal and replay */ }
+        if (pendingWithResults === 0) {
+            console.log(JSON.stringify({ ...priorSummary, idempotent_replay: true }, null, 2));
+            return;
+        }
+        process.stderr.write(`[merge-and-ingest] completion marker for ${runId} is stale: ` +
+            `${pendingWithResults} pending task(s) have un-ingested on-disk results; re-processing.\n`);
+        await rm(mergeCompletePath, { force: true });
     }
     const workerTask = await readJsonFile(taskPath);
     const resultMap = await loadDispatchResultMap(runDir);
@@ -116,36 +140,48 @@ export async function cmdMergeAndIngest(argv) {
     }
     for (const task of allTasks) {
         const entry = entryByTaskId.get(task.task_id);
-        if (!entry) {
-            // No result-map entry => this pending task was not dispatched this round.
-            // Leave it pending for the next dispatch; it is not a failure.
-            notDispatched.push(task.task_id);
-            continue;
-        }
-        const filePath = entry.result_path;
         let obj;
-        try {
-            obj = JSON.parse(await readFile(filePath, "utf8"));
-        }
-        catch (e) {
-            if (isFileMissingError(e)) {
-                const fallback = fallbackByTaskId.get(task.task_id);
-                if (fallback) {
-                    process.stderr.write(`[merge-and-ingest] Recovered result for '${task.task_id}' from unexpected file (matched by task_id)\n`);
-                    obj = fallback;
+        if (entry) {
+            const filePath = entry.result_path;
+            try {
+                obj = JSON.parse(await readFile(filePath, "utf8"));
+            }
+            catch (e) {
+                if (isFileMissingError(e)) {
+                    const fallback = fallbackByTaskId.get(task.task_id);
+                    if (fallback) {
+                        process.stderr.write(`[merge-and-ingest] Recovered result for '${task.task_id}' from unexpected file (matched by task_id)\n`);
+                        obj = fallback;
+                    }
+                    else {
+                        failing.push({
+                            task_id: task.task_id,
+                            errors: ["Missing audit result for assigned task."],
+                        });
+                        continue;
+                    }
                 }
                 else {
-                    failing.push({
-                        task_id: task.task_id,
-                        errors: ["Missing audit result for assigned task."],
-                    });
+                    failing.push({ task_id: task.task_id, errors: [`Invalid JSON: ${e.message}`] });
                     continue;
                 }
             }
-            else {
-                failing.push({ task_id: task.task_id, errors: [`Invalid JSON: ${e.message}`] });
+        }
+        else {
+            // No result-map entry => this pending task was not dispatched this round.
+            // But its answer may already exist on disk under a canonical per-task name
+            // (e.g. a selective-deepening task answered in a prior round whose dispatch
+            // manifest was later regenerated empty — the no-progress loop this guards
+            // against). Recover it by task_id so it ingests instead of looping forever
+            // as "pending"; only when no such file exists is the task genuinely held
+            // back for the next dispatch (not a failure).
+            const fallback = fallbackByTaskId.get(task.task_id);
+            if (!fallback) {
+                notDispatched.push(task.task_id);
                 continue;
             }
+            process.stderr.write(`[merge-and-ingest] Recovered un-dispatched task '${task.task_id}' from on-disk result file (matched by task_id)\n`);
+            obj = fallback;
         }
         const record = obj && typeof obj === "object" && !Array.isArray(obj)
             ? obj
@@ -278,6 +314,12 @@ export async function cmdMergeAndIngest(argv) {
     // failures stay replayable for retry, and a canary (notDispatched > 0) must NOT
     // be marked complete or the fan-out merge on the same run-id would short-circuit
     // to an idempotent replay and silently drop the fan-out results.
+    //
+    // Selective deepening appends new pending tasks to the SAME run-id; this marker
+    // can therefore go stale once those tasks are later dispatched and answered. The
+    // replay guard at the top detects that (a pending task with an on-disk result)
+    // and re-processes, so a premature marker self-heals instead of stranding the
+    // deepening answers behind an idempotent replay (the no-progress loop).
     if (failing.length === 0 && notDispatched.length === 0) {
         await writeJsonFile(mergeCompletePath, summaryPayload);
     }

package/dist/cli/nextStepCommand.d.ts

@@ -1 +1,140 @@
+import type { AnalyzerSetting, GraphEdge } from "@audit-tools/shared";
+import { type ArtifactBundle } from "../io/artifacts.js";
+import type { AuditState } from "../types/auditState.js";
+import { type AdvanceAuditResult } from "../orchestrator/advance.js";
+import { decideNextStep } from "../orchestrator/nextStep.js";
+import type { AnalyzerPlanEntry } from "../extractors/analyzers/types.js";
+/**
+ * Read a JSON file from the `incoming/` subdirectory of `artifactsDir`.
+ * Returns `{ value, path }` when the file exists and parses successfully.
+ * Returns `undefined` when the file is absent (ENOENT-family errors).
+ * Re-throws all other IO errors unchanged.
+ */
+export declare function tryConsumeIncoming<T>(artifactsDir: string, filename: string): Promise<{
+    value: T;
+    path: string;
+} | undefined>;
+type NextStepParams = {
+    root: string;
+    artifactsDir: string;
+    selfCliPath: string;
+    timeoutMs: number;
+    maxRuns: number;
+    opentoken?: boolean;
+    narrativeEnabled?: boolean;
+    analyzers?: Record<string, AnalyzerSetting>;
+    graphLlmEdgeReasoning?: boolean;
+    since?: string;
+};
+type TerminalStepResult = {
+    kind: "complete";
+    state: AuditState;
+    bundle: ArtifactBundle;
+    finalReportPath: string;
+} | {
+    kind: "blocked";
+    state: AuditState;
+    bundle: ArtifactBundle;
+    reason: string;
+};
+/**
+ * Build the terminal step for a deterministic loop that has stopped advancing
+ * (hit the run backstop or the finalization cycle guard). A rendered report is
+ * the deliverable: if synthesis already produced one — or the state is formally
+ * complete — present it instead of reporting the stopped loop as a bare
+ * "blocked" failure. A completed audit must never surface as blocked just
+ * because finalization kept churning (e.g. a runtime_validation <-> synthesis
+ * ping-pong, or revision churn from filesystem retries) after the report was
+ * written. With no report yet, the stop is a genuine block.
+ */
+export declare function buildTerminalStep(params: Pick<NextStepParams, "root" | "artifactsDir">, bundle: ArtifactBundle, state: AuditState, blockedReason: string): Promise<TerminalStepResult>;
+type GraphEnrichmentBranchResult = {
+    action: "continue";
+} | {
+    action: "return";
+    result: {
+        kind: "analyzer_install";
+        state: AuditState;
+        bundle: ArtifactBundle;
+        unresolved: AnalyzerPlanEntry[];
+    };
+} | {
+    action: "return";
+    result: {
+        kind: "edge_reasoning";
+        state: AuditState;
+        bundle: ArtifactBundle;
+        candidates: GraphEdge[];
+    };
+} | {
+    action: "fallthrough";
+};
+/**
+ * Handle the `graph_enrichment_executor` incoming-artifact polling block.
+ * Checks for pending analyzer install decisions and edge-reasoning results.
+ * Returns an action object:
+ *   - `continue`    → caller should `continue` the for-loop (already consumed an artifact).
+ *   - `return`      → caller should return the embedded result to cmdNextStep.
+ *   - `fallthrough` → no incoming artifacts; fall through to the deterministic executor.
+ */
+export declare function handleGraphEnrichmentBranch(params: Pick<NextStepParams, "root" | "artifactsDir" | "graphLlmEdgeReasoning" | "since" | "opentoken">, bundle: ArtifactBundle, state: AuditState, analyzersRef: {
+    value: Record<string, AnalyzerSetting> | undefined;
+}): Promise<GraphEnrichmentBranchResult>;
+type BranchActionResult = {
+    action: "continue";
+} | {
+    action: "return";
+    result: {
+        kind: "design_review";
+        state: AuditState;
+        bundle: ArtifactBundle;
+    };
+};
+/**
+ * Handle the `design_review` incoming-artifact polling block.
+ * Returns `continue` if an incoming findings file was consumed, or `return`
+ * with a design_review kind when the host turn is still needed.
+ */
+export declare function handleDesignReviewBranch(params: Pick<NextStepParams, "artifactsDir">, bundle: ArtifactBundle, state: AuditState): Promise<BranchActionResult>;
+type SynthesisNarrativeBranchResult = {
+    action: "continue";
+} | {
+    action: "return";
+    result: {
+        kind: "synthesis_narrative";
+        state: AuditState;
+        bundle: ArtifactBundle;
+    };
+};
+/**
+ * Handle the `synthesis_narrative_executor` incoming-artifact polling block.
+ * Returns `continue` if an incoming narrative file was consumed, or `return`
+ * with a synthesis_narrative kind when the host turn is still needed (and
+ * narrative is enabled), or `continue` when narrative is disabled (so the
+ * deterministic omit runs below).
+ */
+export declare function handleSynthesisNarrativeBranch(params: Pick<NextStepParams, "root" | "artifactsDir" | "narrativeEnabled" | "opentoken">, bundle: ArtifactBundle, state: AuditState): Promise<SynthesisNarrativeBranchResult>;
+/**
+ * Execute one deterministic audit step and record its progress. Throws (with
+ * cause) if the executor fails, preserving the existing throw-with-cause pattern.
+ */
+export declare function executeAndRecord(params: Pick<NextStepParams, "root" | "artifactsDir" | "graphLlmEdgeReasoning" | "since" | "opentoken" | "maxRuns">, analyzers: Record<string, AnalyzerSetting> | undefined, decision: ReturnType<typeof decideNextStep>, index: number, lastSummary: string): Promise<AdvanceAuditResult>;
+/**
+ * Check for a finalization cycle: when iterations outrun distinct artifact
+ * states by FINALIZATION_CYCLE_TOLERANCE, the deterministic executors are
+ * revisiting states rather than progressing. Returns a terminal-step result
+ * when a cycle is detected, or undefined when the run is still progressing.
+ */
+export declare function checkFinalizationCycle(ctx: {
+    index: number;
+    obligationTrail: string[];
+    seenStateSignatures: Set<string>;
+    tolerance: number;
+    params: Pick<NextStepParams, "artifactsDir" | "maxRuns" | "root">;
+    bundle: ArtifactBundle;
+    state: AuditState;
+    result: AdvanceAuditResult;
+    selectedObligation: string | null | undefined;
+}): Promise<TerminalStepResult | undefined>;
 export declare function cmdNextStep(argv: string[]): Promise<void>;
+export {};