auditor-lambda 0.2.16 → 0.2.17

package/dispatch/lens-definitions.json

@@ -0,0 +1,38 @@
+{
+  "correctness": {
+    "description": "Logic errors, incorrect algorithm implementations, off-by-one bugs, type mismatches, wrong return values, incorrect state transitions, missing null/undefined guards, misuse of APIs. Focus on code that does the wrong thing.",
+    "do_not_report": "Style issues, naming problems, missing tests, or findings that belong to other lenses."
+  },
+  "maintainability": {
+    "description": "Code that is hard to change safely: excessive function length, deep nesting, tight coupling between unrelated modules, poor naming, magic constants, duplicated logic, inconsistent abstractions, unclear public APIs.",
+    "do_not_report": "Correctness bugs, test gaps, or operational concerns."
+  },
+  "tests": {
+    "description": "Test coverage gaps for important paths, tests that assert incorrect behavior (pinning bugs as expected), fragile or non-deterministic tests, missing negative/edge-case tests, tests that silently pass on stale builds (e.g. importing compiled dist/ rather than source).",
+    "do_not_report": "Source code bugs — report only issues with the tests themselves."
+  },
+  "security": {
+    "description": "Injection vulnerabilities (SQL, shell, path traversal), authentication/authorization flaws, secret exposure, insecure deserialization, privilege escalation, unsafe use of eval or child processes with user input.",
+    "do_not_report": "Performance or correctness issues that are not security-relevant."
+  },
+  "reliability": {
+    "description": "Failure modes without recovery, missing timeouts, unhandled promise rejections, race conditions, resource leaks (file handles, sockets, timers), incorrect retry logic, cascading failure risks.",
+    "do_not_report": "Correctness bugs that do not affect reliability under failure conditions."
+  },
+  "performance": {
+    "description": "Algorithmic inefficiencies (O(n²) where O(n) is possible), unnecessary re-computation, missing caching, synchronous blocking in hot paths, excessive memory allocation.",
+    "do_not_report": "Correctness bugs unrelated to performance."
+  },
+  "data_integrity": {
+    "description": "Missing input validation at trust boundaries, schema violations, inconsistent field naming across related schemas, data loss scenarios, missing required fields, enum values that are present in some schemas but not others.",
+    "do_not_report": "UI or presentation issues; operational or deployment concerns."
+  },
+  "operability": {
+    "description": "Missing or low-quality log output, error messages that don't help operators diagnose problems, missing progress indicators for long operations, no elapsed-time reporting, lack of dry-run or preview modes for destructive operations.",
+    "do_not_report": "Correctness bugs or deployment configuration."
+  },
+  "config_deployment": {
+    "description": "CI/CD pipeline correctness (wrong triggers, missing branch filters, floating version pins), deployment safety (no gate before publish, missing rollback), insecure secret handling in configs, mutable action tags that should be pinned to commit SHAs.",
+    "do_not_report": "Runtime code issues; findings that belong to other lenses."
+  }
+}

package/dispatch/merge-results.mjs

@@ -0,0 +1,84 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { validateResult } from "./validate.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+
+// Parse --run-id
+const runIdIdx = process.argv.indexOf("--run-id");
+if (runIdIdx === -1 || !process.argv[runIdIdx + 1]) {
+  console.error("Usage: node dispatch/merge-results.mjs --run-id <run_id>");
+  process.exit(1);
+}
+const run_id = process.argv[runIdIdx + 1];
+
+const artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+const taskResultsDir = join(artifactsDir, "runs", run_id, "task-results");
+const auditResultsPath = join(artifactsDir, "runs", run_id, "audit-results.json");
+const failedTasksPath = join(artifactsDir, "runs", run_id, "failed-tasks.json");
+const tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json");
+
+// Build fileLineCounts map
+const lineCounts = {};
+if (existsSync(tasksPath)) {
+  try {
+    const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
+    for (const task of tasks) {
+      lineCounts[task.task_id] = task.file_line_counts;
+    }
+  } catch {
+    // proceed with empty map
+  }
+}
+
+if (!existsSync(taskResultsDir)) {
+  console.error(`task-results directory not found: ${taskResultsDir}`);
+  process.exit(1);
+}
+
+const files = readdirSync(taskResultsDir).filter(f => f.endsWith(".json"));
+
+const passing = [];
+const failing = [];
+
+for (const filename of files) {
+  const filePath = join(taskResultsDir, filename);
+  let resultObj;
+  try {
+    resultObj = JSON.parse(readFileSync(filePath, "utf8"));
+  } catch (e) {
+    failing.push({ task_id: filename, errors: [`Invalid JSON: ${e.message}`] });
+    continue;
+  }
+
+  const taskId = resultObj?.task_id;
+  const fileLineCounts = (taskId && lineCounts[taskId]) ? lineCounts[taskId] : {};
+  const { valid, errors } = validateResult(resultObj, fileLineCounts);
+
+  if (valid) {
+    passing.push(resultObj);
+  } else {
+    failing.push({ task_id: taskId ?? filename, errors });
+  }
+}
+
+writeFileSync(auditResultsPath, JSON.stringify(passing, null, 2));
+
+if (failing.length > 0) {
+  writeFileSync(failedTasksPath, JSON.stringify(failing, null, 2));
+  console.warn(`${failing.length} task(s) failed validation and were excluded:`);
+  for (const f of failing) {
+    console.warn(`  ✗ ${f.task_id}: ${f.errors[0]}`);
+  }
+}
+
+const total = files.length;
+console.log(`✓ ${passing.length}/${total} tasks valid → ${auditResultsPath}`);
+if (failing.length > 0) {
+  console.log("  Re-run those tasks in the next cycle.");
+}
+
+process.exit(0);

package/dispatch/prepare-dispatch.mjs

@@ -0,0 +1,155 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+
+// Parse --run-id
+const runIdIdx = process.argv.indexOf("--run-id");
+if (runIdIdx === -1 || !process.argv[runIdIdx + 1]) {
+  console.error("Usage: node dispatch/prepare-dispatch.mjs --run-id <run_id>");
+  process.exit(1);
+}
+const run_id = process.argv[runIdIdx + 1];
+
+const artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+const runDir = join(artifactsDir, "runs", run_id);
+const tasksPath = join(runDir, "pending-audit-tasks.json");
+const dispatchPlanPath = join(runDir, "dispatch-plan.json");
+
+if (!existsSync(tasksPath)) {
+  console.error(`File not found: ${tasksPath}`);
+  process.exit(1);
+}
+
+const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
+const lensDefinitions = JSON.parse(
+  readFileSync(join(__dirname, "lens-definitions.json"), "utf8")
+);
+const auditResultSchema = JSON.parse(
+  readFileSync(join(PROJECT_ROOT, "schemas", "audit_result.schema.json"), "utf8")
+);
+const findingSchema = JSON.parse(
+  readFileSync(join(PROJECT_ROOT, "schemas", "finding.schema.json"), "utf8")
+);
+
+function buildPrompt(task, lensDef, auditResultSchema, findingSchema, outputPath, runId, artifactsDir) {
+  const fallback = {
+    task_id: task.task_id,
+    unit_id: task.unit_id,
+    pass_id: task.pass_id,
+    lens: task.lens,
+    file_coverage: task.file_paths.map(p => ({ path: p, total_lines: task.file_line_counts[p] })),
+    findings: [],
+    notes: ["Validation failed after 3 attempts — empty result written as fallback."]
+  };
+
+  return `You are a code auditor. Perform a bounded audit of the files listed below under the specified lens.
+
+## Task metadata
+${JSON.stringify(task, null, 2)}
+
+## Files to read
+Read each path in task.file_paths using your Read tool. The repo root is the current working directory — paths are repo-relative (e.g. "src/foo.ts").
+
+file_line_counts gives the expected total line count for each file. Use those exact values for file_coverage[].total_lines in your result.
+
+## Lens: ${task.lens}
+${lensDef.description}
+
+Do NOT report: ${lensDef.do_not_report}
+
+## Output format
+Write your result as a single JSON **object** (not an array) to this exact path:
+  ${outputPath}
+
+The result must conform to the following schema:
+
+### audit_result.schema.json
+${JSON.stringify(auditResultSchema, null, 2)}
+
+### finding.schema.json
+${JSON.stringify(findingSchema, null, 2)}
+
+## Hard constraints (violations will fail validation)
+1. NEVER set line_end higher than the file's actual line count.
+   Use file_line_counts as your reference. If in doubt, leave line_end omitted.
+2. Every finding MUST have ALL required fields:
+   id, title, category, severity, confidence, lens, summary, affected_files, evidence
+3. lens on every finding must be exactly "${task.lens}"
+4. No fields outside the schema. Forbidden: "recommendation", "tags", "description" (use "summary").
+5. evidence[] must contain at least one specific file:line reference.
+   Format: "path/to/file.ts:42 - brief description of what you see there"
+6. affected_files[] entries are OBJECTS with a "path" key — NOT plain strings.
+   Example: {"path": "src/foo.ts", "line_start": 10, "line_end": 20, "symbol": "myFunc"}
+7. Only reference file paths that appear in this task's file_paths.
+8. findings: [] is correct when you genuinely find nothing. Do not invent findings.
+
+## Validation step (required)
+After writing your result, run:
+  node dispatch/validate-result.mjs ${runId} ${task.task_id}
+
+- If it exits 0: you are done. Stop.
+- If it exits non-zero: read the error output, fix the JSON, rewrite the file, run again.
+- Repeat up to 3 times.
+
+If you cannot produce a valid result after 3 attempts, write this fallback (substituting real values):
+${JSON.stringify(fallback, null, 2)}
+
+Then validate the fallback passes before finishing.`;
+}
+
+mkdirSync(join(runDir, "task-results"), { recursive: true });
+
+const plan = [];
+let largestTask = null;
+let largestLines = 0;
+
+for (const task of tasks) {
+  const sanitizedId = task.task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const outputPath = join(runDir, "task-results", sanitizedId + ".json");
+  const lensDef = lensDefinitions[task.lens];
+
+  if (!lensDef) {
+    console.warn(`Warning: no lens definition for '${task.lens}' (task ${task.task_id})`);
+  }
+
+  const totalFileLines = Object.values(task.file_line_counts).reduce((a, b) => a + b, 0);
+  const description = `Audit ${task.unit_id} (${task.file_paths.length} file(s), ~${totalFileLines} lines) — ${task.lens} lens`;
+  const prompt = buildPrompt(
+    task,
+    lensDef ?? { description: task.lens, do_not_report: "N/A" },
+    auditResultSchema,
+    findingSchema,
+    outputPath,
+    run_id,
+    artifactsDir
+  );
+
+  if (totalFileLines > largestLines) {
+    largestLines = totalFileLines;
+    largestTask = task.task_id;
+  }
+
+  if (totalFileLines > 1500) {
+    console.warn(`Warning: large task ${task.task_id} (~${totalFileLines} lines) may hit quota limits`);
+  }
+
+  plan.push({ task_id: task.task_id, description, output_path: outputPath, prompt });
+}
+
+writeFileSync(dispatchPlanPath, JSON.stringify(plan, null, 2));
+
+console.log(`Wrote dispatch-plan.json — ${plan.length} tasks ready for dispatch`);
+if (largestTask) {
+  console.log(`Largest task: ${largestTask} (~${largestLines} lines)`);
+}
+console.log("");
+console.log("--- ORCHESTRATOR INSTRUCTIONS ---");
+console.log("Read dispatch-plan.json. For each entry, fire one Agent call with:");
+console.log("  description: <entry.description>");
+console.log("  prompt: <entry.prompt>");
+console.log(`Fire all ${plan.length} calls in a single message for parallel execution.`);
+console.log(`When all complete, run: node dispatch/merge-results.mjs --run-id ${run_id}`);

package/dispatch/validate-result.mjs

@@ -0,0 +1,67 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
+import { validateResult } from "./validate.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+
+const run_id = process.argv[2];
+const task_id = process.argv[3];
+
+if (!run_id || !task_id) {
+  console.error("Usage: node dispatch/validate-result.mjs <run_id> <task_id>");
+  process.exit(1);
+}
+
+// Locate artifacts_dir
+let artifactsDir = join(PROJECT_ROOT, ".audit-artifacts");
+const sessionConfigPath = join(artifactsDir, "session-config.json");
+if (existsSync(sessionConfigPath)) {
+  try {
+    const cfg = JSON.parse(readFileSync(sessionConfigPath, "utf8"));
+    if (cfg.artifacts_dir) artifactsDir = cfg.artifacts_dir;
+  } catch {
+    // use default
+  }
+}
+
+const sanitized = task_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+const resultPath = join(artifactsDir, "runs", run_id, "task-results", sanitized + ".json");
+
+if (!existsSync(resultPath)) {
+  console.error(`File not found: ${resultPath}`);
+  process.exit(1);
+}
+
+let resultObj;
+try {
+  resultObj = JSON.parse(readFileSync(resultPath, "utf8"));
+} catch (e) {
+  console.error(`Invalid JSON in ${resultPath}: ${e.message}`);
+  process.exit(1);
+}
+
+const tasksPath = join(artifactsDir, "runs", run_id, "pending-audit-tasks.json");
+let fileLineCounts = {};
+if (existsSync(tasksPath)) {
+  try {
+    const tasks = JSON.parse(readFileSync(tasksPath, "utf8"));
+    const task = tasks.find(t => t.task_id === task_id);
+    fileLineCounts = task?.file_line_counts ?? {};
+  } catch {
+    // use empty
+  }
+}
+
+const { valid, errors } = validateResult(resultObj, fileLineCounts);
+
+if (valid) {
+  console.log("✓ valid:", task_id);
+  process.exit(0);
+} else {
+  console.error("✗ invalid:", task_id);
+  console.error(JSON.stringify(errors, null, 2));
+  process.exit(1);
+}

package/dispatch/validate.mjs

@@ -0,0 +1,88 @@
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import Ajv2020 from "ajv/dist/2020.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, "..");
+const SCHEMAS_DIR = join(PROJECT_ROOT, "schemas");
+
+function loadSchema(name) {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), "utf8"));
+}
+
+let _ajv = null;
+let _validateFn = null;
+
+function getValidator() {
+  if (_validateFn) return _validateFn;
+  _ajv = new Ajv2020({ strict: false, allErrors: true });
+  _ajv.addSchema(loadSchema("finding.schema.json"));
+  _validateFn = _ajv.compile(loadSchema("audit_result.schema.json"));
+  return _validateFn;
+}
+
+function formatAjvError(e) {
+  const path = e.instancePath || "(root)";
+  return `${path}: ${e.message}${e.params ? " (" + JSON.stringify(e.params) + ")" : ""}`;
+}
+
+/**
+ * @param {object} resultObj  — parsed JSON from a task-results file
+ * @param {Record<string, number>} fileLineCounts — from the task's file_line_counts
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateResult(resultObj, fileLineCounts) {
+  const validate = getValidator();
+  const schemaValid = validate(resultObj);
+
+  if (!schemaValid) {
+    return { valid: false, errors: validate.errors.map(formatAjvError) };
+  }
+
+  const errors = [];
+
+  // Line range constraint
+  for (const finding of resultObj.findings) {
+    for (const entry of finding.affected_files) {
+      if (entry.line_end !== undefined) {
+        const coverage = resultObj.file_coverage.find(fc => fc.path === entry.path);
+        if (!coverage) {
+          errors.push(`affected_files path '${entry.path}' not in file_coverage`);
+        } else if (entry.line_end > coverage.total_lines) {
+          errors.push(
+            `finding '${finding.id}': line_end ${entry.line_end} exceeds total_lines ${coverage.total_lines} for ${entry.path}`
+          );
+        }
+      }
+    }
+  }
+
+  // Lens consistency
+  for (const finding of resultObj.findings) {
+    if (finding.lens !== resultObj.lens) {
+      errors.push(
+        `finding '${finding.id}': lens '${finding.lens}' does not match task lens '${resultObj.lens}'`
+      );
+    }
+  }
+
+  // affected_files paths in scope
+  const allowedPaths = new Set(resultObj.file_coverage.map(fc => fc.path));
+  for (const finding of resultObj.findings) {
+    for (const entry of finding.affected_files) {
+      if (!allowedPaths.has(entry.path)) {
+        errors.push(
+          `finding '${finding.id}': affected path '${entry.path}' not in task file_coverage`
+        );
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",
@@ -11,6 +11,7 @@
     "dist/**",
     "audit-code.mjs",
     "audit-code-wrapper-lib.mjs",
+    "dispatch/**",
     "schemas/**",
     "skills/audit-code/**",
     "scripts/postinstall.mjs",

package/scripts/postinstall.mjs

@@ -1,19 +1,27 @@
 #!/usr/bin/env node
 import { homedir } from 'os';
 import { join, dirname } from 'path';
-import { mkdirSync, copyFileSync, existsSync } from 'fs';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 
-const pkgRoot = dirname(fileURLToPath(new URL('.', import.meta.url)));
-const sourceFile = join(pkgRoot, '..', 'skills', 'audit-code', 'audit-code.prompt.md');
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const sourceFile = join(pkgRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
 const destDir = join(homedir(), '.claude', 'commands');
 const destFile = join(destDir, 'audit-code.md');
 
+if (!existsSync(sourceFile)) {
+  console.warn(`audit-code: skill source not found at ${sourceFile} — skipping Claude command install`);
+  process.exit(0);
+}
+
 try {
   mkdirSync(destDir, { recursive: true });
-  copyFileSync(sourceFile, destFile);
-  console.log(`audit-code: installed /audit-code Claude command → ${destFile}`);
+  const action = existsSync(destFile) ? 'updated' : 'installed';
+  // Read then write to avoid Windows file-lock issues with copyFileSync
+  writeFileSync(destFile, readFileSync(sourceFile));
+  console.log(`audit-code: ${action} /audit-code Claude command → ${destFile}`);
 } catch (err) {
-  // Non-fatal — CLI still works, just no slash command autocomplete
   console.warn(`audit-code: could not install Claude command (${err.message})`);
+  console.warn(`  To install manually, run:`);
+  console.warn(`    cp "${sourceFile}" "${destFile}"`);
 }