auditor-lambda 0.1.0 → 0.2.2

package/dist/cli.js

@@ -1,6 +1,6 @@
-import { mkdir } from "node:fs/promises";
+import { access, mkdir } from "node:fs/promises";
 import { createReadStream } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { buildRepoManifest } from "./extractors/fileInventory.js";
 import { buildFileDisposition } from "./extractors/disposition.js";
 import { buildCriticalFlowManifest } from "./extractors/flows.js";
@@ -12,6 +12,7 @@ import { initializeCoverageFromPlan } from "./orchestrator/planning.js";
 import { loadArtifactBundle, writeCoreArtifacts, } from "./io/artifacts.js";
 import { readJsonFile, writeJsonFile } from "./io/json.js";
 import { validateArtifactBundle } from "./validation/artifacts.js";
+import { validateAuditResults, formatAuditResultIssues, } from "./validation/auditResults.js";
 import { validateConfiguredProviderEnvironment, validateSessionConfig, } from "./validation/sessionConfig.js";
 import { buildSynthesisReport } from "./reporting/synthesis.js";
 import { deriveAuditState } from "./orchestrator/state.js";
@@ -23,8 +24,11 @@ import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./superv
 import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
 import { buildRunId, ensureSupervisorDirs, getRunPaths, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
 import { renderWorkerPrompt } from "./prompts/renderWorkerPrompt.js";
+import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "./providers/constants.js";
 const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
 const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
+const DEFAULT_MAX_RUNS = 1000;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 const sampleFiles = [
     { path: "src/api/auth.ts", size_bytes: 1240, hash: "abc123" },
     { path: "src/lib/session.ts", size_bytes: 980, hash: "def456" },
@@ -47,8 +51,39 @@ function getRootDir(argv) {
     return resolve(getFlag(argv, "--root", "."));
 }
 function getMaxRuns(argv) {
-    const raw = Number(getFlag(argv, "--max-runs", "25"));
-    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 25;
+    const raw = Number(getFlag(argv, "--max-runs", String(DEFAULT_MAX_RUNS)));
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_MAX_RUNS;
+}
+function getAgentBatchSize(argv, sessionConfig) {
+    const fromArg = getFlag(argv, "--agent-batch-size");
+    if (fromArg !== undefined) {
+        const parsed = Number(fromArg);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    if (typeof sessionConfig.agent_task_batch_size === "number" && sessionConfig.agent_task_batch_size > 0) {
+        return Math.floor(sessionConfig.agent_task_batch_size);
+    }
+    return 1;
+}
+function getParallelWorkers(argv, sessionConfig) {
+    const fromArg = getFlag(argv, "--parallel");
+    if (fromArg !== undefined) {
+        const parsed = Number(fromArg);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    if (typeof sessionConfig.parallel_workers === "number" && sessionConfig.parallel_workers > 0) {
+        return Math.floor(sessionConfig.parallel_workers);
+    }
+    return 1;
+}
+function chunkArray(arr, size) {
+    const chunks = [];
+    for (let i = 0; i < arr.length; i += size) {
+        chunks.push(arr.slice(i, i + size));
+    }
+    return chunks;
 }
 function getUiMode(argv, fallback = "headless") {
     const raw = getFlag(argv, "--ui");
@@ -79,6 +114,7 @@ async function emitEnvelope(params) {
         bundle: params.bundle,
         providerName: params.providerName,
         progressSummary: params.progress_summary,
+        isConfigError: params.isConfigError,
     });
     await writeAuditCodeHandoffArtifacts(handoff);
     console.log(JSON.stringify(buildEnvelope({
@@ -93,7 +129,7 @@ async function emitEnvelope(params) {
     }), null, 2));
 }
 function buildManualReviewBlocker(providerName) {
-    return providerName === "local-subprocess"
+    return providerName === LOCAL_SUBPROCESS_PROVIDER_NAME
         ? "Automatic local-subprocess work is exhausted. Remaining audit tasks require explicit audit results or an interactive provider such as claude-code, opencode, or subprocess-template."
         : "Automatic work is exhausted. Remaining audit tasks require explicit audit results or an interactive provider.";
 }
@@ -125,8 +161,9 @@ function buildBlockedAuditState(params) {
 }
 async function countLines(path) {
     return new Promise((resolve, reject) => {
-        let lines = 1;
+        let lines = 0;
         let byteCount = 0;
+        let lastByte = -1;
         const stream = createReadStream(path);
         stream.on("data", (chunk) => {
             const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
@@ -134,9 +171,15 @@ async function countLines(path) {
             for (let i = 0; i < buffer.length; ++i) {
                 if (buffer[i] === 10)
                     lines++;
+                lastByte = buffer[i];
             }
         });
-        stream.on("end", () => resolve(byteCount === 0 ? 0 : lines));
+        stream.on("end", () => {
+            if (byteCount === 0)
+                return resolve(0);
+            // Files not ending with \n have one final line not counted above
+            resolve(lastByte !== 10 ? lines + 1 : lines);
+        });
         stream.on("error", reject);
     });
 }
@@ -160,6 +203,34 @@ async function buildLineIndex(root, repoManifest) {
     }
     return Object.fromEntries(entries);
 }
+const PROJECT_SIGNALS = [
+    "package.json",
+    "go.mod",
+    "Cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "Makefile",
+    "CMakeLists.txt",
+];
+async function detectProjectRoot(root) {
+    for (const signal of PROJECT_SIGNALS) {
+        try {
+            await access(join(root, signal));
+            return signal;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    return null;
+}
+function buildPendingAuditTasks(bundle) {
+    const completedTaskIds = new Set((bundle.audit_results ?? []).map((result) => result.task_id));
+    return (bundle.audit_tasks ?? []).filter((task) => !completedTaskIds.has(task.task_id));
+}
 async function runAuditStep(options) {
     const bundle = await loadArtifactBundle(options.artifactsDir);
     const auditResults = options.auditResultsPath
@@ -282,10 +353,41 @@ async function cmdRunToCompletion(argv) {
     const provider = createFreshSessionProvider(getFlag(argv, "--provider"), sessionConfig);
     const uiMode = getUiMode(argv, sessionConfig.ui_mode ?? "headless");
     const maxRuns = getMaxRuns(argv);
-    const timeoutMs = sessionConfig.timeout_ms ?? 30 * 60 * 1000;
+    const agentBatchSize = getAgentBatchSize(argv, sessionConfig);
+    const parallelWorkers = getParallelWorkers(argv, sessionConfig);
+    const timeoutMs = sessionConfig.timeout_ms ?? DEFAULT_TIMEOUT_MS;
     const selfCliPath = resolve(process.argv[1] ?? "");
     await mkdir(artifactsDir, { recursive: true });
     await ensureSupervisorDirs(artifactsDir);
+    const earlyBundle = await loadArtifactBundle(artifactsDir);
+    if (!earlyBundle.unit_manifest) {
+        const foundSignal = await detectProjectRoot(root);
+        if (!foundSignal) {
+            const blocker = `No recognisable project signals found in ${root}. Expected one of: ${PROJECT_SIGNALS.join(", ")}. Check that --root points to the repository root, not a subdirectory or an unrelated path.`;
+            const earlyState = deriveAuditState(earlyBundle);
+            const blockedState = buildBlockedAuditState({
+                state: earlyState,
+                obligationId: null,
+                executor: null,
+                blocker,
+            });
+            await emitEnvelope({
+                root,
+                artifactsDir,
+                bundle: { ...earlyBundle, audit_state: blockedState },
+                audit_state: blockedState,
+                selected_obligation: null,
+                selected_executor: null,
+                progress_made: false,
+                artifacts_written: [],
+                progress_summary: blocker,
+                next_likely_step: null,
+                providerName: provider.name,
+                isConfigError: true,
+            });
+            return;
+        }
+    }
     let pendingAuditResultsPath = getFlag(argv, "--results");
     let pendingRuntimeUpdatesPath = getFlag(argv, "--updates");
     let pendingExternalAnalyzerPath = getFlag(argv, "--external-analyzer-results");
@@ -316,7 +418,7 @@ async function cmdRunToCompletion(argv) {
             obligationId = "runtime_validation_current";
             runtimeUpdatesPath = pendingRuntimeUpdatesPath;
         }
-        if (preferredExecutor === "agent" && provider.name === "local-subprocess") {
+        if (preferredExecutor === "agent" && provider.name === LOCAL_SUBPROCESS_PROVIDER_NAME) {
             const blocker = buildManualReviewBlocker(provider.name);
             const blockedState = buildBlockedAuditState({
                 state: bundle.audit_state ?? decision.state,
@@ -328,6 +430,32 @@ async function cmdRunToCompletion(argv) {
                 ...bundle,
                 audit_state: blockedState,
             });
+            const blockRunId = buildRunId(obligationId, runCount + 1);
+            const blockPaths = getRunPaths(artifactsDir, blockRunId);
+            const blockPendingTasks = buildPendingAuditTasks(bundle).slice(0, agentBatchSize);
+            const blockPendingTasksPath = join(blockPaths.runDir, "pending-audit-tasks.json");
+            const blockAuditResultsPath = join(blockPaths.runDir, "audit-results.json");
+            const blockTask = {
+                contract_version: "audit-code-worker/v1alpha1",
+                run_id: blockRunId,
+                repo_root: root,
+                artifacts_dir: artifactsDir,
+                obligation_id: obligationId,
+                preferred_executor: preferredExecutor,
+                result_path: blockPaths.resultPath,
+                worker_command: [
+                    process.execPath,
+                    selfCliPath,
+                    "worker-run",
+                    "--task",
+                    blockPaths.taskPath,
+                ],
+                audit_results_path: blockAuditResultsPath,
+                pending_audit_tasks_path: blockPendingTasksPath,
+            };
+            const blockPrompt = renderWorkerPrompt(blockTask);
+            await writeWorkerTaskFiles(blockTask, blockPrompt, blockPaths, artifactsDir);
+            await writeJsonFile(blockPendingTasksPath, blockPendingTasks);
             await emitEnvelope({
                 root,
                 artifactsDir,
@@ -369,9 +497,132 @@ async function cmdRunToCompletion(argv) {
             });
             return;
         }
+        if (preferredExecutor === "agent" && parallelWorkers > 1) {
+            const allPendingTasks = buildPendingAuditTasks(bundle);
+            const taskGroups = chunkArray(allPendingTasks.slice(0, parallelWorkers * agentBatchSize), agentBatchSize);
+            const workerSlots = [];
+            for (const group of taskGroups) {
+                runCount += 1;
+                const slotRunId = buildRunId(obligationId, runCount);
+                const slotPaths = getRunPaths(artifactsDir, slotRunId);
+                const slotAuditResultsPath = join(slotPaths.runDir, "audit-results.json");
+                const slotPendingTasksPath = join(slotPaths.runDir, "pending-audit-tasks.json");
+                const slotTask = {
+                    contract_version: "audit-code-worker/v1alpha1",
+                    run_id: slotRunId,
+                    repo_root: root,
+                    artifacts_dir: artifactsDir,
+                    obligation_id: obligationId,
+                    preferred_executor: "agent",
+                    result_path: slotPaths.resultPath,
+                    worker_command: [process.execPath, selfCliPath, "worker-run", "--task", slotPaths.taskPath],
+                    audit_results_path: slotAuditResultsPath,
+                    pending_audit_tasks_path: slotPendingTasksPath,
+                    skip_worker_command: true,
+                };
+                const slotPrompt = renderWorkerPrompt(slotTask);
+                await writeWorkerTaskFiles(slotTask, slotPrompt, slotPaths, artifactsDir);
+                await writeJsonFile(slotPendingTasksPath, group);
+                workerSlots.push({ runId: slotRunId, paths: slotPaths, auditResultsPath: slotAuditResultsPath, pendingTasksPath: slotPendingTasksPath, group });
+            }
+            const parallelStartedAt = new Date().toISOString();
+            await Promise.allSettled(workerSlots.map((slot) => provider.launch({
+                repoRoot: root,
+                runId: slot.runId,
+                obligationId,
+                promptPath: slot.paths.promptPath,
+                taskPath: slot.paths.taskPath,
+                resultPath: slot.paths.resultPath,
+                stdoutPath: slot.paths.stdoutPath,
+                stderrPath: slot.paths.stderrPath,
+                uiMode,
+                timeoutMs,
+            })));
+            // Result ingestion is intentionally sequential even though agent launch
+            // was parallel. Writing to coverage_matrix.json is not atomic, so
+            // concurrent ingest calls would race and corrupt coverage state.
+            let batchProgress = false;
+            for (const slot of workerSlots) {
+                const parallelEndedAt = new Date().toISOString();
+                let slotStatus = "no_progress";
+                try {
+                    const auditResults = await readJsonFile(slot.auditResultsPath);
+                    const pendingTaskIds = new Set(slot.group.map((t) => t.task_id));
+                    const matchedCount = auditResults.filter((r) => pendingTaskIds.has(r.task_id)).length;
+                    if (slot.group.length > 0 && matchedCount === 0) {
+                        throw new Error("Worker did not emit any audit results for the assigned tasks.");
+                    }
+                    const issues = validateAuditResults(auditResults, slot.group);
+                    const errors = issues.filter((issue) => issue.severity === "error");
+                    const warnings = issues.filter((issue) => issue.severity === "warning");
+                    if (warnings.length > 0) {
+                        process.stderr.write(`audit-results validation: ${warnings.length} warning(s) for ${slot.runId}:\n` +
+                            formatAuditResultIssues(warnings) + "\n");
+                    }
+                    if (errors.length > 0) {
+                        throw new Error(`audit-results validation failed with ${errors.length} error(s):\n` +
+                            formatAuditResultIssues(errors));
+                    }
+                    const stepResult = await runAuditStep({
+                        root,
+                        artifactsDir,
+                        preferredExecutor: "result_ingestion_executor",
+                        auditResultsPath: slot.auditResultsPath,
+                    });
+                    slotStatus = stepResult.progress_made ? "completed" : "no_progress";
+                    batchProgress ||= stepResult.progress_made;
+                    if (stepResult.progress_made)
+                        anyProgress = true;
+                    for (const a of stepResult.artifacts_written)
+                        artifactsWritten.add(a);
+                }
+                catch {
+                    slotStatus = "failed";
+                }
+                await appendRunLedgerEntry(artifactsDir, {
+                    run_id: slot.runId,
+                    provider: provider.name,
+                    obligation_id: obligationId,
+                    selected_executor: "agent",
+                    status: slotStatus,
+                    started_at: parallelStartedAt,
+                    ended_at: parallelEndedAt,
+                    result_path: slot.paths.resultPath,
+                });
+                artifactsWritten.add("run-ledger.json");
+            }
+            if (!batchProgress) {
+                const bundleAfter = await loadArtifactBundle(artifactsDir);
+                const state = bundleAfter.audit_state ?? deriveAuditState(bundleAfter);
+                await emitEnvelope({
+                    root,
+                    artifactsDir,
+                    bundle: bundleAfter,
+                    audit_state: state,
+                    selected_obligation: obligationId,
+                    selected_executor: "agent",
+                    progress_made: anyProgress,
+                    artifacts_written: Array.from(artifactsWritten),
+                    progress_summary: "Parallel worker batch made no progress.",
+                    next_likely_step: obligationId,
+                    providerName: provider.name,
+                });
+                return;
+            }
+            continue;
+        }
         runCount += 1;
         const runId = buildRunId(obligationId, runCount);
         const paths = getRunPaths(artifactsDir, runId);
+        const pendingAuditTasks = preferredExecutor === "agent"
+            ? buildPendingAuditTasks(bundle).slice(0, agentBatchSize)
+            : undefined;
+        const pendingAuditTasksPath = preferredExecutor === "agent"
+            ? join(paths.runDir, "pending-audit-tasks.json")
+            : undefined;
+        const providerAuditResultsPath = preferredExecutor === "agent"
+            ? join(paths.runDir, "audit-results.json")
+            : auditResultsPath;
         const task = {
             contract_version: "audit-code-worker/v1alpha1",
             run_id: runId,
@@ -387,12 +638,16 @@ async function cmdRunToCompletion(argv) {
                 "--task",
                 paths.taskPath,
             ],
-            audit_results_path: auditResultsPath,
+            audit_results_path: providerAuditResultsPath,
+            pending_audit_tasks_path: pendingAuditTasksPath,
             runtime_updates_path: runtimeUpdatesPath,
             external_analyzer_results_path: externalAnalyzerPath,
         };
         const prompt = renderWorkerPrompt(task);
         await writeWorkerTaskFiles(task, prompt, paths, artifactsDir);
+        if (pendingAuditTasksPath && pendingAuditTasks) {
+            await writeJsonFile(pendingAuditTasksPath, pendingAuditTasks);
+        }
         const startedAt = new Date().toISOString();
         let workerResult;
         try {
@@ -459,7 +714,7 @@ async function cmdRunToCompletion(argv) {
         artifactsWritten.add("run-ledger.json");
         if (externalAnalyzerPath)
             pendingExternalAnalyzerPath = undefined;
-        if (auditResultsPath)
+        if (providerAuditResultsPath)
             pendingAuditResultsPath = undefined;
         if (runtimeUpdatesPath)
             pendingRuntimeUpdatesPath = undefined;
@@ -509,10 +764,39 @@ async function cmdWorkerRun(argv) {
     const task = await readJsonFile(taskPath);
     let workerResult;
     try {
+        if (task.preferred_executor === "agent" && !task.audit_results_path) {
+            throw new Error("agent worker-run requires audit_results_path so provider-assisted review can be ingested.");
+        }
+        if (task.preferred_executor === "agent" && task.audit_results_path) {
+            const pendingTasks = task.pending_audit_tasks_path
+                ? await readJsonFile(task.pending_audit_tasks_path)
+                : [];
+            const auditResults = await readJsonFile(task.audit_results_path);
+            const pendingTaskIds = new Set(pendingTasks.map((item) => item.task_id));
+            const matchedResultCount = auditResults.filter((result) => pendingTaskIds.has(result.task_id)).length;
+            if (pendingTasks.length > 0 && matchedResultCount === 0) {
+                throw new Error("Provider-assisted review did not emit any audit results for the pending audit tasks.");
+            }
+            const issues = validateAuditResults(auditResults, pendingTasks);
+            const errors = issues.filter((issue) => issue.severity === "error");
+            const warnings = issues.filter((issue) => issue.severity === "warning");
+            if (warnings.length > 0) {
+                process.stderr.write(`audit-results validation: ${warnings.length} warning(s):\n` +
+                    formatAuditResultIssues(warnings) +
+                    "\n");
+            }
+            if (errors.length > 0) {
+                throw new Error(`audit-results validation failed with ${errors.length} error(s):\n` +
+                    formatAuditResultIssues(errors));
+            }
+        }
+        const preferredExecutor = task.preferred_executor === "agent"
+            ? "result_ingestion_executor"
+            : task.preferred_executor;
         const result = await runAuditStep({
             root: task.repo_root,
             artifactsDir: task.artifacts_dir,
-            preferredExecutor: task.preferred_executor,
+            preferredExecutor,
             auditResultsPath: task.audit_results_path,
             runtimeUpdatesPath: task.runtime_updates_path,
             externalAnalyzerPath: task.external_analyzer_results_path,

package/dist/coverage.d.ts

@@ -1,5 +1,4 @@
 import type { CoverageFileRecord, CoverageMatrix, Lens, ReviewedLineRange } from "./types.js";
-export declare function mergeRanges(ranges: ReviewedLineRange[]): ReviewedLineRange[];
 export declare function createCoverageMatrix(paths: string[]): CoverageMatrix;
 export declare function markExcludedPath(matrix: CoverageMatrix, path: string, classificationStatus: string): void;
 export declare function applyUnitCoverage(matrix: CoverageMatrix, path: string, unitId: string, requiredLenses: Lens[]): void;

package/dist/coverage.js

@@ -1,29 +1,3 @@
-function sortRanges(ranges) {
-    return [...ranges].sort((a, b) => {
-        if (a.path !== b.path)
-            return a.path.localeCompare(b.path);
-        if (a.start !== b.start)
-            return a.start - b.start;
-        return a.end - b.end;
-    });
-}
-export function mergeRanges(ranges) {
-    const sorted = sortRanges(ranges);
-    const merged = [];
-    for (const range of sorted) {
-        const last = merged[merged.length - 1];
-        if (!last || last.path !== range.path || range.start > last.end + 1) {
-            merged.push({ ...range });
-            continue;
-        }
-        last.end = Math.max(last.end, range.end);
-        last.pass_id = `${last.pass_id},${range.pass_id}`;
-        last.agent_role = [last.agent_role, range.agent_role]
-            .filter(Boolean)
-            .join(",");
-    }
-    return merged;
-}
 export function createCoverageMatrix(paths) {
     return {
         files: paths.map((path) => ({
@@ -33,7 +7,6 @@ export function createCoverageMatrix(paths) {
             audit_status: "pending",
             required_lenses: [],
             completed_lenses: [],
-            reviewed_line_ranges: [],
         })),
     };
 }
@@ -45,7 +18,6 @@ export function markExcludedPath(matrix, path, classificationStatus) {
     record.audit_status = "excluded";
     record.required_lenses = [];
     record.completed_lenses = [];
-    record.reviewed_line_ranges = [];
     record.unit_ids = [];
 }
 export function applyUnitCoverage(matrix, path, unitId, requiredLenses) {
@@ -65,21 +37,18 @@ export function applyReviewedRanges(matrix, reviewedRanges) {
         const record = matrix.files.find((file) => file.path === range.path);
         if (!record || record.audit_status === "excluded")
             continue;
-        record.reviewed_line_ranges.push(range);
-        record.reviewed_line_ranges = mergeRanges(record.reviewed_line_ranges);
         if (range.lens && !record.completed_lenses.includes(range.lens)) {
             record.completed_lenses.push(range.lens);
         }
     }
     for (const file of matrix.files) {
-        const hasAllRequired = file.required_lenses.every((lens) => file.completed_lenses.includes(lens));
-        if (file.audit_status === "excluded") {
+        if (file.audit_status === "excluded")
             continue;
-        }
+        const hasAllRequired = file.required_lenses.every((lens) => file.completed_lenses.includes(lens));
         if (hasAllRequired && file.required_lenses.length > 0) {
             file.audit_status = "complete";
         }
-        else if (file.reviewed_line_ranges.length > 0) {
+        else if (file.completed_lenses.length > 0) {
             file.audit_status = "partial";
         }
     }

package/dist/extractors/bucketing.js

@@ -1,3 +1,4 @@
+import { isNodeModulesOrGit, isTestPath, isInterfacePath, isDataLayerPath, isSecuritySensitivePath, isConcurrencyPath, isScriptPath, isDeploymentConfigPath, isDocPath, isGeneratedPath, } from "./pathPatterns.js";
 function addBucket(buckets, rationale, bucket, reason) {
     if (!buckets.has(bucket)) {
         buckets.add(bucket);
@@ -8,57 +9,35 @@ export function bucketFile(path) {
     const normalized = path.toLowerCase();
     const buckets = new Set();
     const rationale = [];
-    if (normalized.includes("test") ||
-        normalized.includes("spec") ||
-        normalized.includes("__tests__")) {
+    if (isNodeModulesOrGit(normalized)) {
+        addBucket(buckets, rationale, "generated_vendor", "node_modules or .git excluded by convention");
+        return { path, buckets: [...buckets], rationale };
+    }
+    if (isTestPath(normalized)) {
         addBucket(buckets, rationale, "tests", "path suggests tests");
     }
-    if (normalized.includes("route") ||
-        normalized.includes("controller") ||
-        normalized.includes("handler") ||
-        normalized.includes("api/")) {
+    if (isInterfacePath(normalized)) {
         addBucket(buckets, rationale, "interface", "path suggests interface code");
     }
-    if (normalized.includes("model") ||
-        normalized.includes("schema") ||
-        normalized.includes("migration") ||
-        normalized.includes("seed") ||
-        normalized.includes("db/")) {
+    if (isDataLayerPath(normalized)) {
         addBucket(buckets, rationale, "data_layer", "path suggests data-layer code");
     }
-    if (normalized.includes("auth") ||
-        normalized.includes("secret") ||
-        normalized.includes("token") ||
-        normalized.includes("permission") ||
-        normalized.includes("session")) {
+    if (isSecuritySensitivePath(normalized)) {
         addBucket(buckets, rationale, "security_sensitive", "path suggests security-sensitive code");
     }
-    if (normalized.includes("queue") ||
-        normalized.includes("worker") ||
-        normalized.includes("job") ||
-        normalized.includes("cache") ||
-        normalized.includes("retry") ||
-        normalized.includes("lock")) {
+    if (isConcurrencyPath(normalized)) {
         addBucket(buckets, rationale, "concurrency_state", "path suggests concurrency or stateful behavior");
     }
-    if (normalized.includes("script") ||
-        normalized.startsWith("scripts/") ||
-        normalized.startsWith("bin/")) {
+    if (isScriptPath(normalized)) {
         addBucket(buckets, rationale, "tooling_scripts", "path suggests tooling or scripts");
     }
-    if (normalized.includes("docker") ||
-        normalized.includes("terraform") ||
-        normalized.includes("deploy") ||
-        normalized.includes("workflow") ||
-        normalized.includes("k8s") ||
-        normalized.endsWith(".yml") ||
-        normalized.endsWith(".yaml")) {
+    if (isDeploymentConfigPath(normalized)) {
         addBucket(buckets, rationale, "config_deployment", "path suggests config or deployment artifact");
     }
-    if (normalized.endsWith(".md") || normalized.startsWith("docs/")) {
+    if (isDocPath(normalized)) {
         addBucket(buckets, rationale, "docs_specs", "path suggests documentation");
     }
-    if (normalized.includes("vendor") || normalized.includes("generated")) {
+    if (isGeneratedPath(normalized)) {
         addBucket(buckets, rationale, "generated_vendor", "path suggests generated or vendored content");
     }
     if (buckets.size === 0) {

package/dist/extractors/disposition.js

@@ -1,24 +1,23 @@
+import { isNodeModulesOrGit, isBuildOutput, isVendorPath, isBinaryArtifact, isDocPath, } from "./pathPatterns.js";
 function inferDisposition(path) {
     const normalized = path.toLowerCase();
-    if (normalized.startsWith("dist/") || normalized.startsWith("build/")) {
+    if (isNodeModulesOrGit(normalized)) {
+        return { path, status: "excluded", reason: "node_modules or .git excluded by convention." };
+    }
+    if (isBuildOutput(normalized)) {
         return { path, status: "generated", reason: "Build output path." };
     }
-    if (normalized.includes("vendor") || normalized.includes("third_party")) {
+    if (isVendorPath(normalized)) {
         return { path, status: "vendor", reason: "Vendor or third-party path." };
     }
-    if (normalized.endsWith(".png") ||
-        normalized.endsWith(".jpg") ||
-        normalized.endsWith(".jpeg") ||
-        normalized.endsWith(".gif") ||
-        normalized.endsWith(".pdf") ||
-        normalized.endsWith(".zip")) {
+    if (isBinaryArtifact(normalized)) {
         return {
             path,
             status: "binary",
             reason: "Non-source binary-like artifact.",
         };
     }
-    if (normalized.endsWith(".md") || normalized.startsWith("docs/")) {
+    if (isDocPath(normalized)) {
         return { path, status: "doc_only", reason: "Documentation artifact." };
     }
     return {