karajan-code 2.8.0 → 2.9.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.8.0 released** — Audit-driven hardening release. The 2026-04-30 self-audit (`kj audit`) flagged 13 issues across security, code quality, performance, architecture and testing; this release closes all of them in 16 PRs with 0 user-visible API changes. Highlights: (1) **Security**: every `child_process` call in `src/` now uses tokenised arg arrays (no shell expansion) — closed 7 sites that took template strings. (2) **FASE 1 e2e suite**: 7 scenarios + fake-coder/sonar fixtures cover the 5-bug class from the 2026-04-27 demo regression (zombie-HU, saveSession-missing, Repairer unfixable, zombi-status, audit smoke). 23 e2e tests in 6s. (3) **File splits**: `cli.js` 699→113 LOC, `commands/plan.js` 549→14 LOC (shim) + sub-commands, `iteration-loop.js` 513→311 LOC, `pre-loop.js` 626→435 LOC. Each big driver now under the 600-LOC ceiling. (4) **ESLint ratcheted**: 57 warnings closed in `src/`, then `no-unused-vars` / `no-useless-assignment` / `no-useless-escape` / `preserve-caught-error` switched warn→error so regressions fail CI. New rules ban `console.*` outside CLI paths and `globalThis.__KJ_*` outside `test-harness.js`. (5) **BREAKING**: `engines.node` 18→20.10.0 (Node 18 LTS hit EOL 2025-04-30). See [CHANGELOG.md](./CHANGELOG.md) for the full punch list and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
+> **v2.9.0 released** — Audit overhaul release. `kj audit` becomes a stack-aware, two-phase analysis tool. Highlights: (1) **Two-phase mode**: deterministic findings (basalCost + Sonar + OSV + Semgrep + WebPerf) print first; you decide whether to spend tokens on the LLM analysis with `Continue with LLM analysis? [y/N]`. New `--deterministic-only` flag for zero-token runs. (2) **Three new deterministic security collectors**: SonarQube findings as ground truth in the prompt, OSV-Scanner for dependency CVEs (broader DB than `npm audit`), Semgrep for SAST (XSS, SQLi, taint flow, hardcoded secrets — equivalent to `snyk code` but free and local). (3) **Stack-aware prompt**: detects frontend/backend/fullstack and filters dimension heuristics — no more N+1 query nags on Astro projects, no more bundle-size nags on Express APIs. (4) **Accessibility dimension** auto-activates for frontend projects (WCAG 2.x: alt text, labels, ARIA, focus management, contrast hints). (5) **WebPerf section** with frontend perf hints (lazy loading, image format, render-blocking, font-display, critical CSS) plus optional Core Web Vitals verdict integration. (6) **`--report-file` flag** persists audits to `.md` or `.json` with reproducibility header (timestamp, branch, commit, flags). `$KJ_AUDIT_REPORT_DIR` env var for CI. (7) **Token/cost transparency**: every audit ends with provider + model + tokens + estimated USD cost. (8) **CLI/MCP parity bug fixed** — CLI now drives `AuditRole` like MCP does; both paths produce identical prompt content. Plus repo health: 228 dead exports → 3 in 5 atomic PRs, and the `kj audit` detector itself now matches knip ground truth (166 → 4 false positives, 99.7% reduction). 13 audit PRs + 5 dead-export PRs + 106 new tests; full suite 4305/4305 passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/audit/basal-cost.js

@@ -92,14 +92,68 @@ function runDepcheck(projectDir) {
   });
 }
 
+// Regexes hoisted to module scope so they're compiled once instead of per file.
+// Naming: *Re catches static/syntactic patterns; we still rely on the import set
+// being a superset (false negative > false positive in audit context).
+const EXPORT_RE = /export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
+const NAMED_EXPORT_RE = /export\s*\{([^}]+)\}/g;
+const STATIC_NAMED_IMPORT_RE = /import\s+\{([^}]+)\}\s+from/g;
+const DEFAULT_IMPORT_RE = /import\s+(\w+)\s+from/g;
+// Namespace import (`import * as ns from <path>`) — knip-equivalent: mark
+// the target file as fully-consumed because we cannot statically know
+// which `ns.X` accesses happen.
+const NAMESPACE_IMPORT_RE = /import\s+\*\s+as\s+\w+\s+from\s+["']([^"']+)["']/g;
+// Any dynamic `await import(<path>)` — destructured, late-bound, or
+// member-accessed. Conservatively mark the target as fully-consumed:
+// trying to enumerate downstream destructuring/member-access patterns is
+// fragile (the same test may use parenthesised assignment with no const,
+// or bind first and `.foo`-access later). A false-negative here (one
+// extra "live" export we can't prove dead) is always cheaper than a
+// false-positive in audit context.
+const DYNAMIC_IMPORT_RE = /\bawait\s+import\s*\(\s*["']([^"']+)["']\s*\)/g;
+// Re-export bridges (`export { x } from <path>` and `export * from <path>`)
+// — both consume from the target file (the re-exporter is itself another
+// file consumer downstream).
+const RE_EXPORT_NAMED_RE = /export\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+const RE_EXPORT_STAR_RE = /export\s*\*\s*from\s*["']([^"']+)["']/g;
+// Export preceded by a JSDoc block with `@internal` is opt-out: documented as
+// dynamic-import-only or test-fixture surface that the regex passes can't see.
+const INTERNAL_EXPORT_RE = /\/\*\*[\s\S]*?@internal[\s\S]*?\*\/\s*export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
+
+function resolveImportSpecifier(fromFile, specifier) {
+  // Only resolve project-relative paths; bare specifiers (npm packages) and
+  // node: builtins are not in our exportMap and don't matter here.
+  if (!specifier.startsWith(".") && !specifier.startsWith("/")) return null;
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  // Caller will probe both with and without explicit extensions.
+  return base.endsWith(".js") || base.endsWith(".mjs") || base.endsWith(".cjs")
+    || base.endsWith(".ts") || base.endsWith(".tsx")
+    ? base
+    : `${base}.js`;
+}
+
+// Strip every string literal (template, double, single) from the content
+// before scanning for export declarations. Test files routinely embed
+// sample source code inside fixtures (template literals for plugin
+// modules, double-quoted diff lines for prompt tests, etc.). At top level
+// `export ...` is a statement, never an expression, so it can never
+// legitimately appear inside a quoted string in real code — meaning the
+// strip is safe for export detection. We do NOT use this stripped view
+// for import detection: the import regexes anchor on `import {...} from`
+// regardless of the path string, but the namespace/dynamic-import passes
+// need the actual path inside the quotes to resolve the target module.
+function stripStringLiterals(content) {
+  return content
+    .replace(/`[^`]*`/g, "``")
+    .replace(/"(?:\\.|[^"\\])*"/g, '""')
+    .replace(/'(?:\\.|[^'\\])*'/g, "''");
+}
+
 async function findDeadExports(sourceFiles) {
   const exportMap = new Map(); // file -> [exportName]
+  const internalExportsByFile = new Map(); // file -> Set<exportName>
   const importedNames = new Set();
-
-  const exportRe = /export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
-  const namedExportRe = /export\s*\{([^}]+)\}/g;
-  const importRe = /import\s+\{([^}]+)\}\s+from/g;
-  const defaultImportRe = /import\s+(\w+)\s+from/g;
+  const fullyConsumedFiles = new Set(); // resolved file paths reached via `import *` or bound dynamic import
 
   for (const file of sourceFiles) {
     let content;
@@ -108,12 +162,13 @@ async function findDeadExports(sourceFiles) {
     } catch {
       continue;
     }
+    const exportContent = stripStringLiterals(content);
 
     const exports = [];
-    for (const match of content.matchAll(exportRe)) {
+    for (const match of exportContent.matchAll(EXPORT_RE)) {
       exports.push(match[1]);
     }
-    for (const match of content.matchAll(namedExportRe)) {
+    for (const match of exportContent.matchAll(NAMED_EXPORT_RE)) {
       const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/).pop().trim());
       exports.push(...names);
     }
@@ -121,18 +176,46 @@ async function findDeadExports(sourceFiles) {
       exportMap.set(file, exports);
     }
 
-    for (const match of content.matchAll(importRe)) {
+    // Collect `@internal`-tagged exports up front so the dead-pass can skip them.
+    const internalSet = new Set();
+    for (const match of exportContent.matchAll(INTERNAL_EXPORT_RE)) {
+      internalSet.add(match[1]);
+    }
+    if (internalSet.size > 0) {
+      internalExportsByFile.set(file, internalSet);
+    }
+
+    for (const match of content.matchAll(STATIC_NAMED_IMPORT_RE)) {
       const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/)[0].trim());
       for (const name of names) importedNames.add(name);
     }
-    for (const match of content.matchAll(defaultImportRe)) {
+    for (const match of content.matchAll(DEFAULT_IMPORT_RE)) {
       importedNames.add(match[1]);
     }
+    for (const match of content.matchAll(NAMESPACE_IMPORT_RE)) {
+      const resolved = resolveImportSpecifier(file, match[1]);
+      if (resolved) fullyConsumedFiles.add(resolved);
+    }
+    for (const match of content.matchAll(DYNAMIC_IMPORT_RE)) {
+      const resolved = resolveImportSpecifier(file, match[1]);
+      if (resolved) fullyConsumedFiles.add(resolved);
+    }
+    for (const match of content.matchAll(RE_EXPORT_NAMED_RE)) {
+      const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/)[0].trim());
+      for (const name of names) importedNames.add(name);
+    }
+    for (const match of content.matchAll(RE_EXPORT_STAR_RE)) {
+      const resolved = resolveImportSpecifier(file, match[1]);
+      if (resolved) fullyConsumedFiles.add(resolved);
+    }
   }
 
   const dead = [];
   for (const [file, exports] of exportMap) {
+    if (fullyConsumedFiles.has(file)) continue; // module imported via * or bound await import — can't tell which exports are used
+    const internalSet = internalExportsByFile.get(file);
     for (const name of exports) {
+      if (internalSet?.has(name)) continue; // explicitly opted out via @internal
       if (!importedNames.has(name)) {
         dead.push({ file, name });
       }

package/src/audit/deterministic-summary.js

@@ -0,0 +1,200 @@
+/**
+ * Deterministic-only summary formatter for `kj audit` two-phase mode
+ * (KJC-TSK-0364). Renders the data AuditRole.collectDeterministic()
+ * gathers — basalCost, growth delta, stack, Sonar findings, WebPerf —
+ * as a self-contained markdown block the user can read BEFORE deciding
+ * whether to spend tokens on the LLM analysis.
+ *
+ * Kept in src/audit/ (not src/commands/) so the same formatter can be
+ * reused by future MCP tools and other entrypoints.
+ */
+
+import { groupIssuesBySeverity } from "./sonar-findings.js";
+import { groupVulnerabilitiesBySeverity } from "./osv-findings.js";
+import { groupFindingsBySeverity as groupSemgrepBySeverity } from "./semgrep-findings.js";
+
+const MAX_SAMPLE_DEAD_EXPORTS = 10;
+const MAX_SAMPLE_SONAR_PER_SEVERITY = 5;
+const MAX_SAMPLE_OSV_PER_SEVERITY = 5;
+const MAX_SAMPLE_SEMGREP_PER_SEVERITY = 5;
+
+/**
+ * @param {{basalCost?: object, growthDelta?: object, stack?: object, sonarFindings?: object, webperf?: object, osvFindings?: object}} ctx
+ * @returns {string} markdown block
+ */
+export function formatDeterministicSummary(ctx) {
+  const lines = ["## Deterministic Findings", ""];
+  lines.push("These are the rule-based findings (no LLM). They cost zero tokens and are always factually accurate. The interactive prompt below asks if you want to extend this with an LLM analysis (which will cost tokens).");
+  lines.push("");
+
+  if (ctx.stack) lines.push(...formatStackBlock(ctx.stack));
+  if (ctx.basalCost) lines.push(...formatBasalCostBlock(ctx.basalCost, ctx.growthDelta));
+  if (ctx.sonarFindings) lines.push(...formatSonarBlock(ctx.sonarFindings));
+  if (ctx.osvFindings) lines.push(...formatOsvBlock(ctx.osvFindings));
+  if (ctx.semgrepFindings) lines.push(...formatSemgrepBlock(ctx.semgrepFindings));
+  if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
+
+  return lines.join("\n");
+}
+
+function formatSemgrepBlock(semgrepFindings) {
+  if (!semgrepFindings.available) {
+    return ["### Semgrep SAST", `- Status: not available — ${semgrepFindings.reason || "semgrep not installed"}`, ""];
+  }
+  const lines = ["### Semgrep SAST"];
+  lines.push(`- Total findings: ${semgrepFindings.total ?? 0}`);
+  if ((semgrepFindings.total ?? 0) > 0) {
+    const groups = groupSemgrepBySeverity(semgrepFindings.findings || []);
+    for (const [severity, findings] of Object.entries(groups)) {
+      if (findings.length === 0) continue;
+      lines.push(`  - ${severity} (${findings.length}):`);
+      for (const f of findings.slice(0, MAX_SAMPLE_SEMGREP_PER_SEVERITY)) {
+        const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+        lines.push(`    - ${loc} [${f.rule}]`);
+      }
+      if (findings.length > MAX_SAMPLE_SEMGREP_PER_SEVERITY) {
+        lines.push(`    - ... and ${findings.length - MAX_SAMPLE_SEMGREP_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatOsvBlock(osvFindings) {
+  if (!osvFindings.available) {
+    return ["### OSV Vulnerabilities", `- Status: not available — ${osvFindings.reason || "osv-scanner not installed"}`, ""];
+  }
+  const lines = ["### OSV Vulnerabilities (Dependencies)"];
+  lines.push(`- Total open: ${osvFindings.total ?? 0}`);
+  if ((osvFindings.total ?? 0) > 0) {
+    const groups = groupVulnerabilitiesBySeverity(osvFindings.vulnerabilities || []);
+    for (const [severity, vulns] of Object.entries(groups)) {
+      if (vulns.length === 0) continue;
+      lines.push(`  - ${severity} (${vulns.length}):`);
+      for (const v of vulns.slice(0, MAX_SAMPLE_OSV_PER_SEVERITY)) {
+        const where = v.package ? `${v.package}@${v.version || "?"}` : "(unknown)";
+        const fixed = v.fixed ? ` → fixed in ${v.fixed}` : "";
+        lines.push(`    - ${v.id} ${where}${fixed}`);
+      }
+      if (vulns.length > MAX_SAMPLE_OSV_PER_SEVERITY) {
+        lines.push(`    - ... and ${vulns.length - MAX_SAMPLE_OSV_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatStackBlock(stack) {
+  if (!stack || (!stack.frameworks?.length && !stack.language && !stack.isFrontend && !stack.isBackend)) return [];
+  const lines = ["### Project Stack"];
+  if (stack.language) lines.push(`- Language: ${stack.language}`);
+  if (stack.frameworks?.length) lines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+  const tier = stack.isFullstack ? "fullstack (frontend + backend)"
+    : stack.isFrontend ? "frontend-only"
+    : stack.isBackend ? "backend-only"
+    : "unknown";
+  lines.push(`- Tier: ${tier}`);
+  lines.push("");
+  return lines;
+}
+
+function formatBasalCostBlock(basalCost, growthDelta) {
+  const lines = ["### Basal Cost"];
+  lines.push(`- Source: ${basalCost.totalLines} lines across ${basalCost.totalFiles} files`);
+  const deps = basalCost.dependencies || {};
+  if (deps.total) lines.push(`- Dependencies: ${deps.total} (${deps.dependencies} prod + ${deps.devDependencies} dev)`);
+
+  const unused = basalCost.unusedDependencies?.unused;
+  if (Array.isArray(unused) && unused.length > 0) {
+    lines.push(`- Unused dependencies (${unused.length}): ${unused.join(", ")}`);
+  }
+
+  const dead = Array.isArray(basalCost.deadExports) ? basalCost.deadExports : [];
+  if (dead.length > 0) {
+    lines.push(`- Dead exports: ${dead.length}`);
+    for (const de of dead.slice(0, MAX_SAMPLE_DEAD_EXPORTS)) {
+      lines.push(`  - \`${de.name}\` in ${de.file}`);
+    }
+    if (dead.length > MAX_SAMPLE_DEAD_EXPORTS) {
+      lines.push(`  - ... and ${dead.length - MAX_SAMPLE_DEAD_EXPORTS} more`);
+    }
+  } else {
+    lines.push("- Dead exports: 0");
+  }
+
+  if (growthDelta) {
+    lines.push("");
+    lines.push("**Growth since last audit**");
+    lines.push(`- Lines: ${growthDelta.lines >= 0 ? "+" : ""}${growthDelta.lines}`);
+    lines.push(`- Files: ${growthDelta.files >= 0 ? "+" : ""}${growthDelta.files}`);
+    lines.push(`- Dependencies: ${growthDelta.deps >= 0 ? "+" : ""}${growthDelta.deps}`);
+    if (growthDelta.since) lines.push(`- Since: ${growthDelta.since}`);
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatSonarBlock(sonarFindings) {
+  if (!sonarFindings.available) {
+    return ["### SonarQube", `- Status: not available — ${sonarFindings.reason || "host unreachable"}`, ""];
+  }
+  const lines = ["### SonarQube"];
+  if (sonarFindings.qualityGate?.status) lines.push(`- Quality gate: ${sonarFindings.qualityGate.status}`);
+  lines.push(`- Open issues: ${sonarFindings.total ?? 0}`);
+  if ((sonarFindings.total ?? 0) > 0) {
+    const groups = groupIssuesBySeverity(sonarFindings.issues || []);
+    for (const [severity, issues] of Object.entries(groups)) {
+      if (issues.length === 0) continue;
+      lines.push(`  - ${severity} (${issues.length}):`);
+      for (const issue of issues.slice(0, MAX_SAMPLE_SONAR_PER_SEVERITY)) {
+        const loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+        const rule = issue.rule ? ` [${issue.rule}]` : "";
+        lines.push(`    - ${loc}${rule} ${issue.message || ""}`.trim());
+      }
+      if (issues.length > MAX_SAMPLE_SONAR_PER_SEVERITY) {
+        lines.push(`    - ... and ${issues.length - MAX_SAMPLE_SONAR_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatWebperfBlock(webperf) {
+  if (!webperf.available) {
+    return ["### WebPerf", `- Status: not collected — ${webperf.reason || "no frontend signal"}`, ""];
+  }
+  const lines = ["### WebPerf"];
+  if (webperf.mode === "cwv-result" && webperf.cwv) {
+    lines.push(`- Mode: live CWV measurement`);
+    if (webperf.url) lines.push(`- URL: ${webperf.url}`);
+    lines.push(`- Verdict: ${webperf.cwv.pass ? "PASS" : "FAIL"}`);
+    for (const [metric, score] of Object.entries(webperf.cwv.scores || {})) {
+      lines.push(`  - ${metric.toUpperCase()}: ${score.value} (${score.rating})`);
+    }
+  } else {
+    lines.push(`- Mode: static hints only (no live CWV measurement available)`);
+    lines.push(`- LLM phase will scan source for bundle/lazy/img-opt patterns when activated`);
+  }
+  lines.push("");
+  return lines;
+}
+
+/**
+ * Detect whether the deterministic context found any signal worth showing.
+ * If everything came back empty/unavailable, the CLI can skip the
+ * "Continue with LLM?" prompt — there's nothing to compare against.
+ */
+export function deterministicContextHasFindings(ctx) {
+  if (!ctx) return false;
+  if (ctx.basalCost?.deadExports?.length > 0) return true;
+  if (ctx.basalCost?.unusedDependencies?.unused?.length > 0) return true;
+  if (ctx.sonarFindings?.available && (ctx.sonarFindings.total ?? 0) > 0) return true;
+  if (ctx.sonarFindings?.qualityGate?.status === "ERROR") return true;
+  if (ctx.osvFindings?.available && (ctx.osvFindings.total ?? 0) > 0) return true;
+  if (ctx.semgrepFindings?.available && (ctx.semgrepFindings.total ?? 0) > 0) return true;
+  if (ctx.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
+  return false;
+}

package/src/audit/osv-findings.js

@@ -0,0 +1,162 @@
+/**
+ * OSV-Scanner findings collector for `kj audit` (KJC-TSK-0365).
+ *
+ * Wraps Google's `osv-scanner` CLI and feeds its results into the audit
+ * prompt as a deterministic vulnerability section. OSV.dev's database
+ * pulls from GitHub Advisory Database, GLSA, PyPI advisories, Go vuln
+ * DB and others — broader coverage than `npm audit` alone, with no
+ * account, token, or upload (the scanner runs locally and only the
+ * advisory data is fetched on demand).
+ *
+ * This module follows the same pattern as src/audit/sonar-findings.js:
+ *   - Best-effort: missing binary or scan errors return
+ *     {available: false, reason} and the audit continues without the
+ *     section.
+ *   - Severity-grouped: helps the LLM (and the deterministic summary)
+ *     prioritise the worst issues without scrolling.
+ *   - Capped: only the first MAX_OSV_VULNS_IN_PROMPT entries land in
+ *     the prompt, with overflow markers per severity, so an
+ *     out-of-control result list cannot blow the token budget.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 60_000;
+const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "MODERATE"];
+
+/**
+ * Run osv-scanner on the project and return a structured result.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, vulnerabilities?: object[]}>}
+ */
+export async function collectOsvFindings(projectDir, logger = null) {
+  let stdout;
+  try {
+    const { stdout: out } = await execFileAsync(
+      "osv-scanner",
+      ["--format=json", "--recursive", projectDir || "."],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    // osv-scanner exits with non-zero when vulnerabilities are found, so
+    // err.code 1 is NORMAL — we still want the stdout. Real failures are
+    // ENOENT (binary missing) or stdout empty.
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("osv-scanner not found in PATH — install via 'go install github.com/google/osv-scanner@latest'");
+      return { available: false, reason: "osv-scanner not installed" };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`osv-scanner timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `osv-scanner timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`osv-scanner failed: ${err.message}`);
+      return { available: false, reason: `osv-scanner failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`osv-scanner output not parseable: ${err.message}`);
+    return { available: false, reason: "osv-scanner output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseOsvOutput(parsed) };
+}
+
+/**
+ * Flatten the osv-scanner JSON shape into a flat list of vulnerabilities.
+ * The scanner emits results[].packages[].vulnerabilities[].
+ *
+ * @param {object} raw - parsed osv-scanner JSON
+ * @returns {{total: number, vulnerabilities: object[]}}
+ */
+export function parseOsvOutput(raw) {
+  const flat = [];
+  const results = Array.isArray(raw?.results) ? raw.results : [];
+  for (const result of results) {
+    const source = result.source?.path || result.source || "";
+    const packages = Array.isArray(result.packages) ? result.packages : [];
+    for (const pkg of packages) {
+      const name = pkg.package?.name || "";
+      const version = pkg.package?.version || "";
+      const ecosystem = pkg.package?.ecosystem || "";
+      const vulns = Array.isArray(pkg.vulnerabilities) ? pkg.vulnerabilities : [];
+      const groups = Array.isArray(pkg.groups) ? pkg.groups : [];
+      for (const vuln of vulns) {
+        flat.push({
+          id: vuln.id || vuln.aliases?.[0] || "UNKNOWN",
+          aliases: vuln.aliases || [],
+          severity: extractSeverity(vuln, groups),
+          summary: vuln.summary || vuln.details?.split("\n")[0] || "",
+          package: name,
+          version,
+          ecosystem,
+          source,
+          fixed: extractFixedVersion(vuln),
+        });
+      }
+    }
+  }
+  return { total: flat.length, vulnerabilities: flat };
+}
+
+/**
+ * Resolve a vulnerability's effective severity. osv-scanner reports
+ * CVSS (per-vuln) and a separate `groups[].severity` (per scanner run).
+ * Group severity wins when present because it reflects scanner policy.
+ */
+function extractSeverity(vuln, groups) {
+  // Group-level severity (scanner-resolved, includes ecosystem context)
+  for (const group of groups) {
+    if (group.ids?.includes(vuln.id) && group.severity) {
+      return String(group.severity).toUpperCase();
+    }
+  }
+  // Per-vuln CVSS — pick the highest score
+  const severities = Array.isArray(vuln.severity) ? vuln.severity : [];
+  for (const sev of severities) {
+    if (sev?.severity) return String(sev.severity).toUpperCase();
+  }
+  // database_specific severity (GHSA-style)
+  if (vuln.database_specific?.severity) {
+    return String(vuln.database_specific.severity).toUpperCase();
+  }
+  return "UNKNOWN";
+}
+
+function extractFixedVersion(vuln) {
+  const ranges = vuln.affected?.[0]?.ranges || [];
+  for (const range of ranges) {
+    const events = range.events || [];
+    for (const event of events) {
+      if (event.fixed) return event.fixed;
+    }
+  }
+  return null;
+}
+
+/**
+ * Group vulnerabilities by severity, preserving canonical ordering
+ * (CRITICAL → HIGH → MEDIUM/MODERATE → LOW → UNKNOWN).
+ */
+export function groupVulnerabilitiesBySeverity(vulnerabilities) {
+  const groups = Object.fromEntries(SEVERITY_ORDER.map(s => [s, []]));
+  groups.UNKNOWN = [];
+  for (const vuln of vulnerabilities || []) {
+    const sev = (vuln.severity || "UNKNOWN").toUpperCase();
+    if (groups[sev]) groups[sev].push(vuln);
+    else groups.UNKNOWN.push(vuln);
+  }
+  return groups;
+}

package/src/audit/semgrep-findings.js

@@ -0,0 +1,117 @@
+/**
+ * Semgrep SAST collector for `kj audit` (KJC-TSK-0366).
+ *
+ * Wraps `semgrep --config auto --json` and feeds structured static-
+ * analysis findings into the audit prompt. Equivalent to the SAST half
+ * of `snyk code` but free for OSS, no account, runs locally. Semgrep
+ * has 2000+ built-in rules across JS/TS/Python/Go/etc. covering OWASP
+ * Top 10, taint analysis, hardcoded secrets, regex misuse and language-
+ * specific anti-patterns.
+ *
+ * Same best-effort pattern as sonar-findings.js and osv-findings.js:
+ *   - Missing binary or timeout returns {available: false, reason}.
+ *   - 120s timeout (semgrep can be slow on large repos with --config auto).
+ *   - Severity-grouped (ERROR / WARNING / INFO) and capped at
+ *     MAX_SEMGREP_FINDINGS_IN_PROMPT (50) total entries with overflow
+ *     markers.
+ *   - The LLM is told these are deterministic and asked to fold them
+ *     into the `security` dimension using the rule ID as the rule field.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 120_000;
+const SEVERITY_ORDER = ["ERROR", "WARNING", "INFO"];
+
+/**
+ * Run semgrep on the project and return a structured result.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, findings?: object[]}>}
+ */
+export async function collectSemgrepFindings(projectDir, logger = null) {
+  let stdout;
+  try {
+    const { stdout: out } = await execFileAsync(
+      "semgrep",
+      ["--config", "auto", "--json", "--quiet", `--timeout=${Math.floor(SCAN_TIMEOUT_MS / 1000)}`, projectDir || "."],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS + 5000, maxBuffer: 32 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("semgrep not found in PATH — install via 'pipx install semgrep' or 'brew install semgrep'");
+      return { available: false, reason: "semgrep not installed" };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`semgrep timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `semgrep timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    // semgrep exits 1 when it finds blocking rules (ERROR severity), but
+    // still emits a valid JSON report on stdout. Rescue that case.
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`semgrep failed: ${err.message}`);
+      return { available: false, reason: `semgrep failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`semgrep output not parseable: ${err.message}`);
+    return { available: false, reason: "semgrep output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseSemgrepOutput(parsed, projectDir) };
+}
+
+/**
+ * Convert semgrep's JSON shape into the flat findings list the prompt
+ * builder consumes. Semgrep emits results[] with rule id, severity,
+ * path, start/end line, message, fix hints.
+ *
+ * @param {object} raw - parsed semgrep --json output
+ * @param {string} [projectDir] - used to make paths repo-relative
+ * @returns {{total: number, findings: object[]}}
+ */
+export function parseSemgrepOutput(raw, projectDir = "") {
+  const results = Array.isArray(raw?.results) ? raw.results : [];
+  const findings = [];
+  for (const r of results) {
+    const file = r.path && projectDir
+      ? r.path.startsWith(projectDir + "/") ? r.path.slice(projectDir.length + 1) : r.path
+      : r.path || "";
+    findings.push({
+      rule: r.check_id || "(unknown)",
+      severity: String(r.extra?.severity || "INFO").toUpperCase(),
+      file,
+      line: r.start?.line ?? 0,
+      endLine: r.end?.line ?? 0,
+      message: r.extra?.message || "",
+      fix: r.extra?.fix || r.extra?.fix_regex || null,
+      cwe: r.extra?.metadata?.cwe || null,
+      owasp: r.extra?.metadata?.owasp || null,
+    });
+  }
+  return { total: findings.length, findings };
+}
+
+/**
+ * Group findings by severity in canonical order (ERROR → WARNING → INFO).
+ */
+export function groupFindingsBySeverity(findings) {
+  const groups = Object.fromEntries(SEVERITY_ORDER.map(s => [s, []]));
+  for (const f of findings || []) {
+    const sev = (f.severity || "INFO").toUpperCase();
+    if (groups[sev]) groups[sev].push(f);
+    else groups.INFO.push(f);
+  }
+  return groups;
+}