karajan-code 2.16.0 → 2.17.1

package/README.md

@@ -23,7 +23,11 @@
 
 ---
 
-> **v2.16.0 released** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
+> **v2.17.1 released** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
+>
+> **v2.17.0** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
+>
+> **v2.16.0** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
 >
 > **v2.15.0** — Minor. Three epics, 30+ commits, ~4 000 LOC. (1) **Brain Recovery** (KJC-PCS-0044): universal error classifier with 7 rich classes (rate_limit_short, quota_daily, quota_monthly, api_down, auth_failed, network_timeout, silenced, unknown_fatal), `withBrainRecovery` wrapper wired into ALL agent invocations (no silent failures), persistent hibernation in `~/.kj/standby/<id>.json` with event-driven scheduler (no polling), `kj standby list` + `kj standby resume`, board reconcile at startup, **fallback chain** when quota exhausted with `retryAfter > 12h` (Claude → Codex → OpenCode → Aider, configurable per role via `kj init`). (2) **Model Routing + Undo** (KJC-PCS-0043): each HU gets `coder_model` + `reviewer_model` with cross-provider review by default (claude↔codex), per-HU override from board modal, OpenCode + Aider as first-class providers, ⏪ Undo button restores files via git snapshots. (3) **Self-Healing Plan** (KJC-PCS-0042): structural integrity pass breaks cycles + cleans orphan refs, smart convergence guard for self-fix loop, `kj plan fix [planId] [--prompt]` for iterating without regenerating, skip Sonar for SPIKE/DOC/RESEARCH HUs, eliminate Failed kanban column. 4 835/4 835 tests passing across 400 files. Safe upgrade from 2.14.3.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.16.0",
+  "version": "2.17.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "engines": {
-    "node": ">=20.10.0"
+    "node": ">=20.19.0"
   },
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -70,6 +70,8 @@
     "commander": "^14.0.0",
     "execa": "^9.6.0",
     "js-yaml": "^4.1.0",
+    "knip": "^6.14.1",
+    "madge": "^8.0.0",
     "valibot": "^1.3.1"
   },
   "devDependencies": {

package/scripts/esbuild-sea.config.mjs

@@ -153,7 +153,22 @@ export const seaBuildOptions = {
   // this `external` entry is belt-and-braces — if any other dependency
   // pulls better-sqlite3 in we want a clear "not bundled" error, not a
   // silent half-bundle.
-  external: ["better-sqlite3"],
+  //
+  // madge (KJC-TSK v2.17): pulled in by src/audit/circular-deps.js via a
+  // dynamic import. Madge transitively depends on @vue/compiler-sfc which
+  // optionally requires ~20 template engines (velocityjs, dustjs-linkedin,
+  // twig, …) that are not installed — esbuild fails the bundle if it
+  // tries to walk those. Marking madge external keeps `kj audit` working
+  // in npm-installed Karajan (madge is in node_modules) and degrades
+  // gracefully in the SEA binary (the dynamic import fails → audit
+  // continues without circular-dep findings).
+  // knip (KJC-TSK v2.17): invoked as a subprocess by src/audit/dead-exports.js
+  // via `process.execPath knip-bin --reporter json`. Its native parser
+  // (oxc-parser, oxc-resolver) and CLI machinery must not be bundled. In SEA
+  // builds the createRequire(import.meta.url).resolve("knip/bin/knip.js")
+  // throws → collector returns available:false. npm installs get knip
+  // resolved normally from node_modules.
+  external: ["better-sqlite3", "madge", "knip", "oxc-parser", "oxc-resolver"],
   plugins: [seaTransformPlugin, huBoardStubPlugin],
   logLevel: "info",
 };

package/src/audit/circular-deps.js

@@ -0,0 +1,144 @@
+// Circular import-deps collector for `kj audit` (KJC-TSK — v2.17).
+//
+// Deterministic, stack-aware. Uses madge programmatically; activates only
+// when the project's stack has JS/TS sources. Anything else returns
+// { available: false, reason }.
+//
+// Same best-effort shape as sonar-findings / osv-findings / semgrep-findings:
+//   - missing dep or timeout returns { available: false, reason }
+//   - findings are passed through audit/issue-filter.js so the user can
+//     suppress known cycles via config.audit.false_positives or inline
+//     `// karajan-audit-ignore: madge:circular-import` markers.
+
+import path from "node:path";
+import fs from "node:fs/promises";
+import { filterFalsePositives } from "./issue-filter.js";
+
+// madge is loaded dynamically: in the SEA standalone binary it is excluded
+// from the bundle (see scripts/esbuild-sea.config.mjs) and a require()
+// failure here cleanly degrades to available:false, while npm installs work
+// normally. Keeping the import inside collectCircularDeps() also avoids
+// paying the load cost for non-JS projects.
+
+const SCAN_TIMEOUT_MS = 60_000;
+const MAX_CYCLES_REPORTED = 50;
+
+// Extensions madge will follow. Python/Go/etc. are not supported and we
+// short-circuit on stack detection — listing only JS/TS variants here is a
+// safety net so we never accidentally scan unrelated files.
+const JS_TS_EXTENSIONS = ["js", "mjs", "cjs", "jsx", "ts", "tsx"];
+
+function hasJsTsStack(stack) {
+  if (!stack) return false;
+  const lang = (stack.language || "").toLowerCase();
+  if (lang === "javascript" || lang === "typescript") return true;
+  const langs = Array.isArray(stack.languages) ? stack.languages : [];
+  return langs.some((l) => /^(javascript|typescript|jsx?|tsx?)$/i.test(String(l)));
+}
+
+async function findTsConfig(projectDir) {
+  for (const name of ["tsconfig.json", "jsconfig.json"]) {
+    const p = path.join(projectDir, name);
+    try { await fs.access(p); return p; } catch { /* not present */ }
+  }
+  return undefined;
+}
+
+function pickEntrypoint(projectDir) {
+  // madge needs an entrypoint. We prefer common conventions; if none
+  // exists we fall back to scanning `src/` which covers ~95% of JS/TS
+  // projects we've seen.
+  return path.join(projectDir, "src");
+}
+
+/**
+ * Collect circular-import findings for a project.
+ *
+ * @param {string} projectDir
+ * @param {object} stack - shape returned by detectProjectStack()
+ * @param {object} [config] - kj config (for config.audit.false_positives)
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, cycles?: object[], suppressed?: object[]}>}
+ */
+export async function collectCircularDeps(projectDir, stack, config = {}, logger = null) {
+  if (!hasJsTsStack(stack)) {
+    return { available: false, reason: "no JS/TS sources detected — circular-dep scan skipped" };
+  }
+
+  const entry = pickEntrypoint(projectDir);
+  try { await fs.access(entry); } catch {
+    return { available: false, reason: `entrypoint ${path.relative(projectDir, entry)} not found` };
+  }
+
+  let madge;
+  try {
+    ({ default: madge } = await import("madge"));
+  } catch (err) {
+    return { available: false, reason: `madge not loadable (${err?.message || err}). In the SEA binary install karajan-code via npm to enable.` };
+  }
+
+  const tsConfig = await findTsConfig(projectDir);
+  const opts = {
+    fileExtensions: JS_TS_EXTENSIONS,
+    excludeRegExp: [/node_modules/, /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /dist\//, /build\//, /coverage\//],
+    detectiveOptions: { es6: { mixedImports: true } },
+  };
+  if (tsConfig) opts.tsConfig = tsConfig;
+
+  let cycles;
+  try {
+    const scan = await Promise.race([
+      madge(entry, opts),
+      new Promise((_, rej) => setTimeout(() => rej(new Error("madge timeout")), SCAN_TIMEOUT_MS)),
+    ]);
+    cycles = scan.circular() || [];
+  } catch (err) {
+    logger?.warn?.(`audit/circular-deps: madge failed (${err?.message || err})`);
+    return { available: false, reason: `madge run failed: ${err?.message || err}` };
+  }
+
+  // madge returns paths relative to the entry dir; normalize to paths
+  // relative to projectDir so they match how the rest of the audit (Sonar,
+  // Semgrep) reports locations and so config.audit.false_positives can
+  // target them with familiar globs like "src/".
+  const relPrefix = path.relative(projectDir, entry);
+  const normalizedCycles = cycles.map((cycle) =>
+    cycle.map((p) => (relPrefix ? path.join(relPrefix, p) : p)),
+  );
+
+  const issues = normalizedCycles.slice(0, MAX_CYCLES_REPORTED).map((cycle, idx) => ({
+    tool: "madge",
+    rule: "circular-import",
+    component: cycle[0],
+    path: cycle[0],
+    line: 1,
+    severity: cycle.length >= 4 ? "MAJOR" : "MINOR",
+    message: `Circular import chain (${cycle.length} files): ${cycle.join(" → ")} → ${cycle[0]}`,
+    cycle,
+    index: idx,
+  }));
+
+  const extraRules = (config?.audit?.false_positives || []).filter((r) => r.tool === "madge");
+  const { kept, suppressed } = filterFalsePositives(issues, { extraRules, projectRoot: projectDir });
+
+  return {
+    available: true,
+    total: kept.length,
+    suppressedCount: suppressed.length,
+    cycles: kept,
+    suppressed,
+    truncated: normalizedCycles.length > MAX_CYCLES_REPORTED ? normalizedCycles.length - MAX_CYCLES_REPORTED : 0,
+  };
+}
+
+/**
+ * Group cycles by severity for the deterministic summary renderer.
+ */
+export function groupCyclesBySeverity(cycles) {
+  const groups = { MAJOR: [], MINOR: [] };
+  for (const c of cycles || []) {
+    const sev = c.severity || "MINOR";
+    if (groups[sev]) groups[sev].push(c);
+  }
+  return groups;
+}

package/src/audit/dead-exports.js

@@ -0,0 +1,186 @@
+// Dead exports collector for `kj audit` (KJC-TSK v2.17, code-quality dim).
+//
+// Wraps knip via subprocess. Reports unused exports + unused files —
+// findings consumed deterministically by the LLM phase so the coder
+// stops shipping new code without noticing dead code piling up.
+//
+// Same best-effort pattern as madge / semgrep / osv / sonar:
+//   - missing project signal (no package.json, no JS/TS) → available:false
+//   - missing knip binary → available:false (degrades cleanly in SEA)
+//   - timeout / parse error → available:false with reason
+//
+// Findings pass through audit/issue-filter.js so users can suppress
+// false positives via config.audit.false_positives (tool="knip") or
+// inline `// karajan-audit-ignore: knip:<ruleId>`.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createRequire } from "node:module";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { filterFalsePositives } from "./issue-filter.js";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 120_000;
+const MAX_DEAD_EXPORTS_REPORTED = 100;
+const MAX_UNUSED_FILES_REPORTED = 50;
+
+function hasJsTsStack(stack) {
+  if (!stack) return false;
+  const lang = (stack.language || "").toLowerCase();
+  if (lang === "javascript" || lang === "typescript") return true;
+  const langs = Array.isArray(stack.languages) ? stack.languages : [];
+  return langs.some((l) => /^(javascript|typescript|jsx?|tsx?)$/i.test(String(l)));
+}
+
+async function hasPackageJson(projectDir) {
+  try { await fs.access(path.join(projectDir, "package.json")); return true; } catch { return false; }
+}
+
+/**
+ * Resolve the knip binary path relative to this package's node_modules.
+ * In SEA builds knip is `external` and require.resolve throws — we let
+ * the caller catch it and return available:false.
+ *
+ * knip restricts its subpath exports to "." and "./session", so we can't
+ * directly resolve "knip/bin/knip.js" or even "knip/package.json".
+ * Instead we resolve "knip" (the main entry, dist/index.js), walk up to
+ * its package root, and locate bin/knip.js from there.
+ */
+function resolveKnipBin() {
+  const require = createRequire(import.meta.url);
+  const entry = require.resolve("knip"); // e.g. .../node_modules/knip/dist/index.js
+  // entry is .../node_modules/knip/dist/index.js — the package root is two levels up
+  const knipRoot = path.dirname(path.dirname(entry));
+  return path.join(knipRoot, "bin", "knip.js");
+}
+
+/**
+ * Collect dead-exports findings for a project.
+ *
+ * @param {string} projectDir
+ * @param {object} stack
+ * @param {object} [config]
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, exports?: object[], files?: object[], suppressed?: object[]}>}
+ */
+export async function collectDeadExports(projectDir, stack, config = {}, logger = null) {
+  if (!hasJsTsStack(stack)) {
+    return { available: false, reason: "no JS/TS sources detected — dead-export scan skipped" };
+  }
+  if (!(await hasPackageJson(projectDir))) {
+    return { available: false, reason: "no package.json found — knip needs one to detect entry points" };
+  }
+
+  let knipBin;
+  try { knipBin = resolveKnipBin(); } catch (err) {
+    return { available: false, reason: `knip binary not resolvable (${err?.message || err}). In the SEA binary install karajan-code via npm to enable.` };
+  }
+
+  let raw;
+  try {
+    const { stdout } = await execFileAsync(
+      process.execPath,
+      [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 },
+    );
+    raw = stdout;
+  } catch (err) {
+    // knip exits non-zero when issues are found; with --no-exit-code that
+    // should not happen, but old configs might still trigger it. If the
+    // process produced JSON on stdout we still try to parse it.
+    raw = err?.stdout || "";
+    if (!raw) {
+      logger?.warn?.(`audit/dead-exports: knip failed (${err?.message || err})`);
+      return { available: false, reason: `knip run failed: ${err?.shortMessage || err?.message || err}` };
+    }
+  }
+
+  let report;
+  try {
+    report = JSON.parse(raw);
+  } catch (err) {
+    return { available: false, reason: `knip output not parseable as JSON (${err?.message || err})` };
+  }
+
+  // knip --reporter json shape: { files: [paths], issues: [{ file, exports?, types?, ... }], ... }
+  const unusedFiles = Array.isArray(report.files) ? report.files : [];
+  const fileIssues = Array.isArray(report.issues) ? report.issues : [];
+
+  const deadExportIssues = [];
+  for (const fi of fileIssues) {
+    const file = fi.file || fi.filePath || "";
+    if (!file) continue;
+    for (const ex of fi.exports || []) {
+      deadExportIssues.push({
+        tool: "knip",
+        rule: "unused-exports",
+        component: file,
+        path: file,
+        line: ex.line || 1,
+        col: ex.col,
+        name: ex.name,
+        severity: "MINOR",
+        message: `Unused export \`${ex.name}\` in ${file}`,
+      });
+    }
+    for (const t of fi.types || []) {
+      deadExportIssues.push({
+        tool: "knip",
+        rule: "unused-types",
+        component: file,
+        path: file,
+        line: t.line || 1,
+        name: t.name,
+        severity: "MINOR",
+        message: `Unused type \`${t.name}\` in ${file}`,
+      });
+    }
+  }
+
+  const unusedFileIssues = unusedFiles.map((f) => ({
+    tool: "knip",
+    rule: "unused-files",
+    component: f,
+    path: f,
+    line: 1,
+    severity: "MAJOR",
+    message: `Unused file: ${f}`,
+  }));
+
+  const allIssues = [
+    ...deadExportIssues.slice(0, MAX_DEAD_EXPORTS_REPORTED),
+    ...unusedFileIssues.slice(0, MAX_UNUSED_FILES_REPORTED),
+  ];
+  const extraRules = (config?.audit?.false_positives || []).filter((r) => r.tool === "knip");
+  const { kept, suppressed } = filterFalsePositives(allIssues, { extraRules, projectRoot: projectDir });
+
+  const keptExports = kept.filter((i) => i.rule === "unused-exports" || i.rule === "unused-types");
+  const keptFiles = kept.filter((i) => i.rule === "unused-files");
+
+  return {
+    available: true,
+    total: kept.length,
+    suppressedCount: suppressed.length,
+    exports: keptExports,
+    files: keptFiles,
+    suppressed,
+    truncated: {
+      exports: deadExportIssues.length > MAX_DEAD_EXPORTS_REPORTED ? deadExportIssues.length - MAX_DEAD_EXPORTS_REPORTED : 0,
+      files: unusedFiles.length > MAX_UNUSED_FILES_REPORTED ? unusedFiles.length - MAX_UNUSED_FILES_REPORTED : 0,
+    },
+  };
+}
+
+/**
+ * Group dead-export issues by severity for the deterministic summary.
+ */
+export function groupDeadExportsBySeverity(items) {
+  const groups = { MAJOR: [], MINOR: [] };
+  for (const i of items || []) {
+    const sev = i.severity || "MINOR";
+    if (groups[sev]) groups[sev].push(i);
+  }
+  return groups;
+}

package/src/audit/deterministic-summary.js

@@ -12,11 +12,15 @@
 import { groupIssuesBySeverity } from "./sonar-findings.js";
 import { groupVulnerabilitiesBySeverity } from "./osv-findings.js";
 import { groupFindingsBySeverity as groupSemgrepBySeverity } from "./semgrep-findings.js";
+import { groupCyclesBySeverity } from "./circular-deps.js";
+import { groupDeadExportsBySeverity } from "./dead-exports.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;
+const MAX_SAMPLE_CYCLES_PER_SEVERITY = 5;
+const MAX_SAMPLE_KNIP_PER_SEVERITY = 5;
 
 /**
  * @param {{basalCost?: object, growthDelta?: object, stack?: object, sonarFindings?: object, webperf?: object, osvFindings?: object}} ctx
@@ -32,11 +36,39 @@ export function formatDeterministicSummary(ctx) {
   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.circularDeps) lines.push(...formatCircularDepsBlock(ctx.circularDeps));
+  if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
   if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
 
   return lines.join("\n");
 }
 
+function formatCircularDepsBlock(circularDeps) {
+  if (!circularDeps.available) {
+    return ["### Circular Dependencies (architecture)", `- Status: not available — ${circularDeps.reason || "madge not available"}`, ""];
+  }
+  const lines = ["### Circular Dependencies (architecture)"];
+  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : ""}`);
+  if ((circularDeps.total ?? 0) > 0) {
+    const groups = groupCyclesBySeverity(circularDeps.cycles || []);
+    for (const [severity, cycles] of Object.entries(groups)) {
+      if (cycles.length === 0) continue;
+      lines.push(`  - ${severity} (${cycles.length}):`);
+      for (const c of cycles.slice(0, MAX_SAMPLE_CYCLES_PER_SEVERITY)) {
+        const head = (c.cycle || [c.path]).slice(0, 3).join(" → ");
+        const more = (c.cycle?.length || 0) > 3 ? ` → … (${c.cycle.length} files)` : "";
+        lines.push(`    - ${head}${more}`);
+      }
+      if (cycles.length > MAX_SAMPLE_CYCLES_PER_SEVERITY) {
+        lines.push(`    - ... and ${cycles.length - MAX_SAMPLE_CYCLES_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+    if (circularDeps.truncated > 0) lines.push(`  - ... ${circularDeps.truncated} more cycles not shown`);
+  }
+  lines.push("");
+  return lines;
+}
+
 function formatSemgrepBlock(semgrepFindings) {
   if (!semgrepFindings.available) {
     return ["### Semgrep SAST", `- Status: not available — ${semgrepFindings.reason || "semgrep not installed"}`, ""];
@@ -86,6 +118,34 @@ function formatOsvBlock(osvFindings) {
   return lines;
 }
 
+function formatDeadExportsBlock(deadExports) {
+  if (!deadExports.available) {
+    return ["### Dead Code (knip)", `- Status: not available — ${deadExports.reason || "knip not available"}`, ""];
+  }
+  const lines = ["### Dead Code (knip)"];
+  const exportsTotal = (deadExports.exports || []).length;
+  const filesTotal = (deadExports.files || []).length;
+  lines.push(`- Unused exports/types: ${exportsTotal}`);
+  lines.push(`- Unused files: ${filesTotal}`);
+  if (deadExports.suppressedCount) lines.push(`- Suppressed (FP filter): ${deadExports.suppressedCount}`);
+  const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])];
+  if (allItems.length > 0) {
+    const groups = groupDeadExportsBySeverity(allItems);
+    for (const [severity, items] of Object.entries(groups)) {
+      if (items.length === 0) continue;
+      lines.push(`  - ${severity} (${items.length}):`);
+      for (const item of items.slice(0, MAX_SAMPLE_KNIP_PER_SEVERITY)) {
+        lines.push(`    - ${item.path}${item.line ? `:${item.line}` : ""} [${item.rule}]${item.name ? ` \`${item.name}\`` : ""}`);
+      }
+      if (items.length > MAX_SAMPLE_KNIP_PER_SEVERITY) {
+        lines.push(`    - ... and ${items.length - MAX_SAMPLE_KNIP_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"];
@@ -195,6 +255,8 @@ export function deterministicContextHasFindings(ctx) {
   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.circularDeps?.available && (ctx.circularDeps.total ?? 0) > 0) return true;
+  if (ctx.deadExports?.available && (ctx.deadExports.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/issue-filter.js

@@ -0,0 +1,136 @@
+// Generalised deterministic false-positive filter for kj audit collectors.
+//
+// Originally introduced as `src/sonar/issue-filter.js` in v2.16.0 (KJC-TSK-0416)
+// for Sonar findings. Generalised here so every collector (sonar, knip, madge,
+// osv, semgrep, …) can reuse the same two mechanisms:
+//
+//   1. Static rules: { tool, rule, filePattern, reason }. Match by tool name
+//      + rule id + path pattern. Catalogue below + extensible per project via
+//      config.audit.false_positives. Legacy `config.sonar.false_positives` is
+//      honoured for backwards compatibility.
+//   2. Inline ignore: `// karajan-audit-ignore: <tool>:<ruleId>` on the issue
+//      line or the previous one. Legacy `// karajan-sonar-ignore: <ruleId>`
+//      keeps working when the issue's tool is "sonar".
+//
+// Issues filtered out are kept in the `suppressed` list with `_suppressedBy`
+// metadata for auditability — no silent dropping.
+
+import fs from "node:fs";
+
+export const DEFAULT_FALSE_POSITIVES = [
+  {
+    tool: "sonar",
+    rule: "javascript:S2699",
+    filePattern: /tests\/architecture\//,
+    reason: "Structural tests assert via expect(offenders, msg).toEqual([]) — Sonar misses the custom-message form",
+  },
+  // Knip — v2.17 audit/dead-exports collector.
+  {
+    tool: "knip",
+    rule: "unused-files",
+    filePattern: /(?:^|\/)tests\/fixtures\//,
+    reason: "Test fixtures are loaded by file path at runtime, not statically imported — knip can't see them",
+  },
+  {
+    tool: "knip",
+    rule: "unused-files",
+    filePattern: /(?:^|\/)examples\//,
+    reason: "Example projects are user-facing entry points, not consumed by the parent project's source",
+  },
+  {
+    tool: "knip",
+    rule: "unused-exports",
+    filePattern: /(?:^|\/)(?:index|main)\.(?:js|ts|mjs|cjs|jsx|tsx)$/,
+    reason: "Barrel re-exports in index.{js,ts} are legitimate public API surface even when no in-tree caller uses them",
+  },
+  // Madge — v2.17 audit/circular-deps collector.
+  {
+    tool: "madge",
+    rule: "circular-import",
+    filePattern: /node_modules\//,
+    reason: "Cycles inside node_modules are upstream's problem, not ours — defensive default since madge excludes node_modules by config",
+  },
+];
+
+export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
+  if (!filePath || !line || !ruleId) return false;
+  if (!fs.existsSync(filePath)) return false;
+  try {
+    const lines = fs.readFileSync(filePath, "utf8").split("\n");
+    const idx = line - 1;
+    const candidates = [lines[idx], lines[idx - 1]].filter(Boolean);
+    const escapedRule = escapeRegex(ruleId);
+    const escapedTool = escapeRegex(tool);
+    // New generalised marker + legacy sonar-only marker.
+    const reAudit = new RegExp(`karajan-audit-ignore\\s*:\\s*${escapedTool}:${escapedRule}\\b`);
+    const reLegacy = tool === "sonar"
+      ? new RegExp(`karajan-sonar-ignore\\s*:\\s*${escapedRule}\\b`)
+      : null;
+    return candidates.some((l) => reAudit.test(l) || (reLegacy && reLegacy.test(l)));
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegex(s) {
+  return String(s).replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Filter a list of normalised audit findings into kept + suppressed.
+ *
+ * @param {object[]} issues  Each issue must carry { tool, rule, component|path, line? }.
+ *                           `tool` defaults to "sonar" for backwards compat.
+ * @param {object} [opts]
+ * @param {object[]} [opts.extraRules]   Rules from config.audit.false_positives
+ *                                       (or legacy config.sonar.false_positives).
+ * @param {string} [opts.projectRoot]    Used to resolve component → absolute path.
+ * @returns {{ kept: object[], suppressed: object[] }}
+ */
+export function filterFalsePositives(issues, opts = {}) {
+  if (!Array.isArray(issues)) return { kept: [], suppressed: [] };
+  const rules = [...DEFAULT_FALSE_POSITIVES, ...(opts.extraRules || [])].map((r) => ({
+    tool: r.tool || "sonar",
+    rule: r.rule,
+    filePattern: r.filePattern instanceof RegExp ? r.filePattern : new RegExp(String(r.filePattern || ".*")),
+    reason: r.reason,
+  }));
+  const projectRoot = opts.projectRoot || process.cwd();
+  const kept = [];
+  const suppressed = [];
+
+  for (const issue of issues) {
+    const tool = issue.tool || "sonar";
+    const path = componentToPath(issue.component) || issue.path || "";
+    let matched = null;
+
+    // 1. Static rules.
+    for (const rule of rules) {
+      if (rule.tool === tool && issue.rule === rule.rule && rule.filePattern.test(path)) {
+        matched = { tool, rule: rule.rule, path, reason: rule.reason };
+        break;
+      }
+    }
+
+    // 2. Inline ignore (only checked if no static rule matched).
+    if (!matched && issue.rule && issue.line && path) {
+      const absPath = path.startsWith("/") ? path : `${projectRoot}/${path}`;
+      if (hasInlineIgnore(absPath, issue.line, issue.rule, tool)) {
+        matched = { tool, rule: issue.rule, path, reason: "inline `// karajan-audit-ignore`" };
+      }
+    }
+
+    if (matched) {
+      suppressed.push({ ...issue, _suppressedBy: matched });
+    } else {
+      kept.push(issue);
+    }
+  }
+  return { kept, suppressed };
+}
+
+function componentToPath(component) {
+  if (typeof component !== "string") return "";
+  const colonIdx = component.indexOf(":");
+  return colonIdx >= 0 ? component.slice(colonIdx + 1) : component;
+}