@karajan-family/code 4.21.0

package/src/audit/basal-cost.js

@@ -0,0 +1,281 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getKarajanHome } from "../utils/paths.js";
+import { sniffManifests, summariseStack } from "../utils/manifest-sniff.js";
+
+const execFileAsync = promisify(execFile);
+
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".tsx", ".jsx",
+  ".py", ".rb", ".go", ".rs", ".java", ".kt", ".swift", ".c", ".cpp", ".h",
+  ".vue", ".svelte", ".astro", ".php", ".cs", ".sh"
+]);
+
+const EXCLUDE_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "coverage", ".next",
+  ".nuxt", ".output", "__pycache__", ".cache", ".parcel-cache"
+]);
+
+function slugify(projectDir) {
+  return path.basename(projectDir).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+async function walkSourceFiles(dir) {
+  // Use git ls-files for speed (instant vs recursive walk)
+  try {
+    const { stdout } = await execFileAsync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], { cwd: dir, encoding: "utf8", timeout: 5000 });
+    return stdout.trim().split("\n")
+      .filter(f => f && SOURCE_EXTENSIONS.has(path.extname(f)) && !EXCLUDE_DIRS.has(f.split("/")[0]))
+      .map(f => path.join(dir, f));
+  } catch {
+    // Fallback to recursive walk if not a git repo
+    const files = [];
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch { /* directory not readable */
+      return files;
+    }
+    for (const entry of entries) {
+      if (EXCLUDE_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...await walkSourceFiles(full));
+      } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+        files.push(full);
+      }
+    }
+    return files;
+  }
+}
+
+async function countLines(filePath) {
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    return content.split("\n").length;
+  } catch {
+    return 0;
+  }
+}
+
+function countDependenciesFromStack(stack) {
+  // Suma deps + devDeps de TODOS los manifests detectados (multi-stack).
+  // Si no hay manifests, devuelve ceros — coherente con repos sin paquete.
+  let deps = 0;
+  let devDeps = 0;
+  for (const m of stack.manifests) {
+    deps += m.deps;
+    devDeps += m.devDeps;
+  }
+  return { dependencies: deps, devDependencies: devDeps, total: deps + devDeps };
+}
+
+function runDepcheck(projectDir) {
+  return new Promise((resolve) => {
+    execFile("npx", ["depcheck", "--json"], { cwd: projectDir, timeout: 30000 }, (err, stdout) => {
+      if (err && !stdout) {
+        resolve({ unused: [], note: "depcheck not available or failed" });
+        return;
+      }
+      try {
+        const result = JSON.parse(stdout);
+        const unused = [
+          ...(result.dependencies || []),
+          ...(result.devDependencies || [])
+        ];
+        resolve({ unused });
+      } catch {
+        resolve({ unused: [], note: "depcheck output not parseable" });
+      }
+    });
+  });
+}
+
+// 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
+    .replaceAll(/`[^`]*`/g, "``")
+    .replaceAll(/"(?:\\.|[^"\\])*"/g, '""')
+    .replaceAll(/'(?:\\.|[^'\\])*'/g, "''");
+}
+
+async function findDeadExports(sourceFiles) {
+  const exportMap = new Map(); // file -> [exportName]
+  const internalExportsByFile = new Map(); // file -> Set<exportName>
+  const importedNames = new Set();
+  const fullyConsumedFiles = new Set(); // resolved file paths reached via `import *` or bound dynamic import
+
+  for (const file of sourceFiles) {
+    let content;
+    try {
+      content = await fs.readFile(file, "utf8");
+    } catch {
+      continue;
+    }
+    const exportContent = stripStringLiterals(content);
+
+    const exports = [];
+    for (const match of exportContent.matchAll(EXPORT_RE)) {
+      exports.push(match[1]);
+    }
+    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);
+    }
+    if (exports.length > 0) {
+      exportMap.set(file, exports);
+    }
+
+    // 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(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 });
+      }
+    }
+  }
+  return dead;
+}
+
+export async function measureBasalCost(projectDir) {
+  const sourceFiles = await walkSourceFiles(projectDir);
+  let totalLines = 0;
+  for (const f of sourceFiles) {
+    totalLines += await countLines(f);
+  }
+
+  const stack = summariseStack(await sniffManifests(projectDir));
+  const depInfo = countDependenciesFromStack(stack);
+  // depcheck solo aplica a Node; en stacks puros no-Node lo saltamos.
+  const hasNode = stack.manifests.some((m) => m.stack === "node");
+  const depcheck = hasNode ? await runDepcheck(projectDir) : { unused: [], note: "depcheck skipped (no package.json)" };
+  const deadExports = await findDeadExports(sourceFiles);
+
+  return {
+    totalLines,
+    totalFiles: sourceFiles.length,
+    dependencies: depInfo,
+    unusedDependencies: depcheck,
+    deadExports,
+    stack
+  };
+}
+
+function auditDir() {
+  return path.join(getKarajanHome(), "audits");
+}
+
+export async function loadPreviousAudit(projectDir) {
+  const file = path.join(auditDir(), slugify(projectDir), "latest.json");
+  try {
+    return JSON.parse(await fs.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function saveAuditSnapshot(projectDir, metrics) {
+  const dir = path.join(auditDir(), slugify(projectDir));
+  await fs.mkdir(dir, { recursive: true });
+  const snapshot = { ...metrics, timestamp: new Date().toISOString() };
+  await fs.writeFile(path.join(dir, "latest.json"), JSON.stringify(snapshot, null, 2));
+  return snapshot;
+}
+
+export function computeGrowthDelta(current, previous) {
+  if (!previous) return null;
+  return {
+    lines: current.totalLines - previous.totalLines,
+    files: current.totalFiles - previous.totalFiles,
+    deps: current.dependencies.total - (previous.dependencies?.total ?? 0),
+    since: previous.timestamp || null
+  };
+}

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;
+}