karajan-code 2.7.4 → 2.9.0

package/src/audit/agent-readiness.js

@@ -0,0 +1,240 @@
+/**
+ * kj audit --agent-readiness — score a repo for AI-agent readability.
+ *
+ * Static, deterministic, NO LLM call. Inspired by addyosmani/agentic-seo.
+ * Catches the failure modes that make repos invisible to Cursor /
+ * Cline / Aider / Claude Code:
+ *   - no llms.txt → agents have to crawl the README
+ *   - oversized doc pages → agents truncate or drop them
+ *   - JS-only docs → agents can't render
+ *   - broken heading hierarchy → agents misinfer structure
+ *   - no robots allowlist → some agents skip silently
+ *
+ * Returns a 0-100 score + per-check detail + top remediation hints.
+ * Pure data transformation: filesystem reads in, analysis out.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const PAGE_BYTE_LIMIT = 32 * 1024; // ≈ 8K tokens, the typical agent budget per fetch
+
+/**
+ * Catalogue of checks. Each check has:
+ *   - id          — stable identifier
+ *   - weight      — points contributed when ok
+ *   - run         — (rootDir) => { ok, hint, details }
+ */
+const CHECKS = [
+  {
+    id: "llms-txt-present",
+    weight: 25,
+    description: "llms.txt at repo root",
+    run(rootDir) {
+      const p = path.join(rootDir, "llms.txt");
+      const ok = fs.existsSync(p) && fs.statSync(p).isFile();
+      return ok
+        ? { ok: true, hint: null, details: { path: p } }
+        : { ok: false, hint: "Add llms.txt at repo root with a single-fetch index of docs + commands.", details: {} };
+    },
+  },
+  {
+    id: "llms-txt-valid",
+    weight: 10,
+    description: "llms.txt has at least one section heading and one link",
+    run(rootDir) {
+      const p = path.join(rootDir, "llms.txt");
+      if (!fs.existsSync(p)) return { ok: false, hint: "llms.txt missing — see llms-txt-present.", details: {} };
+      const text = safeRead(p);
+      const hasSection = /^##\s+/m.test(text);
+      const hasLink = /\[[^\]]+\]\([^)]+\)/.test(text);
+      const ok = hasSection && hasLink;
+      return ok
+        ? { ok: true, hint: null, details: { hasSection, hasLink } }
+        : { ok: false, hint: "Add `## Section` headings and `[label](path)` links to llms.txt.", details: { hasSection, hasLink } };
+    },
+  },
+  {
+    id: "robots-allowlist",
+    weight: 10,
+    description: "robots.txt explicitly Allows AI crawlers",
+    run(rootDir) {
+      // Check root or public/.
+      const candidates = ["robots.txt", "public/robots.txt", "static/robots.txt"];
+      const found = candidates.find((c) => fs.existsSync(path.join(rootDir, c)));
+      if (!found) return { ok: false, hint: "Add robots.txt with `User-agent: GPTBot|ClaudeBot|PerplexityBot\\nAllow: /` blocks.", details: {} };
+      const text = safeRead(path.join(rootDir, found));
+      const aiBots = ["GPTBot", "ClaudeBot", "PerplexityBot", "anthropic-ai", "Google-Extended"];
+      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${bot}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
+      const ok = allowed.length > 0;
+      return ok
+        ? { ok: true, hint: null, details: { found, allowed } }
+        : { ok: false, hint: `robots.txt found at ${found} but no AI crawler explicitly Allowed. Add explicit User-agent: ClaudeBot blocks.`, details: { found, allowed } };
+    },
+  },
+  {
+    id: "page-token-budget",
+    weight: 15,
+    description: "every .md doc fits within ≈ 8K tokens (32 KB raw)",
+    run(rootDir) {
+      const docsDir = path.join(rootDir, "docs");
+      if (!fs.existsSync(docsDir)) {
+        // No docs/ at all is its own kind of agent-unfriendly, but
+        // not strictly a budget violation. Pass with a hint.
+        return { ok: true, hint: "No docs/ directory found. Consider adding one.", details: { docsDirPresent: false } };
+      }
+      const oversized = listMarkdownFiles(docsDir).filter((f) => fs.statSync(f).size > PAGE_BYTE_LIMIT);
+      if (oversized.length === 0) {
+        return { ok: true, hint: null, details: { oversizedCount: 0 } };
+      }
+      const sample = oversized.slice(0, 3).map((f) => `${path.relative(rootDir, f)} (${(fs.statSync(f).size / 1024).toFixed(1)} KB)`);
+      return {
+        ok: false,
+        hint: `Split or trim ${oversized.length} oversized doc(s): ${sample.join(", ")}.`,
+        details: { oversizedCount: oversized.length, sample },
+      };
+    },
+  },
+  {
+    id: "heading-hierarchy",
+    weight: 10,
+    description: "each .md has exactly one H1 and no skipped levels",
+    run(rootDir) {
+      const docsDir = path.join(rootDir, "docs");
+      if (!fs.existsSync(docsDir)) return { ok: true, hint: null, details: { docsDirPresent: false } };
+      const violations = [];
+      for (const f of listMarkdownFiles(docsDir)) {
+        const text = safeRead(f);
+        const h1Count = (text.match(/^#\s+/gm) || []).length;
+        if (h1Count !== 1) {
+          violations.push({ file: path.relative(rootDir, f), h1Count });
+          continue;
+        }
+        // Check for skipped levels (#### without preceding ###, etc.)
+        const headings = [...text.matchAll(/^(#{1,6})\s/gm)].map((m) => m[1].length);
+        let prev = 0;
+        for (const lvl of headings) {
+          if (prev > 0 && lvl > prev + 1) {
+            violations.push({ file: path.relative(rootDir, f), reason: `H${prev}→H${lvl} skip` });
+            break;
+          }
+          prev = lvl;
+        }
+      }
+      if (violations.length === 0) {
+        return { ok: true, hint: null, details: { violationsCount: 0 } };
+      }
+      const sample = violations.slice(0, 3);
+      return {
+        ok: false,
+        hint: `Fix heading hierarchy in ${violations.length} doc(s): ${sample.map((v) => v.file).join(", ")}.`,
+        details: { violationsCount: violations.length, sample },
+      };
+    },
+  },
+  {
+    id: "agents-readme",
+    weight: 10,
+    description: "docs/agents/README.md as agent entry point",
+    run(rootDir) {
+      const p = path.join(rootDir, "docs/agents/README.md");
+      const ok = fs.existsSync(p);
+      return ok
+        ? { ok: true, hint: null, details: { path: p } }
+        : { ok: false, hint: "Create docs/agents/README.md as the agent-facing index (links from llms.txt).", details: {} };
+    },
+  },
+  {
+    id: "skill-md-coverage",
+    weight: 20,
+    description: "at least one SKILL.md per declared CLI capability",
+    run(rootDir) {
+      const skillDir = path.join(rootDir, "docs/agents");
+      if (!fs.existsSync(skillDir)) return { ok: false, hint: "Create docs/agents/ with one SKILL.<command>.md per CLI capability.", details: {} };
+      const skillFiles = fs.readdirSync(skillDir).filter((f) => /^SKILL\..+\.md$/.test(f));
+      if (skillFiles.length === 0) {
+        return { ok: false, hint: "Add SKILL.<command>.md files documenting each CLI capability.", details: { skillFilesCount: 0 } };
+      }
+      // We don't enumerate the user's own CLI here (out of scope for a
+      // generic auditor). At least 1 SKILL.md is the minimum signal.
+      return { ok: true, hint: null, details: { skillFilesCount: skillFiles.length } };
+    },
+  },
+];
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return ""; }
+}
+
+function listMarkdownFiles(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith(".") || e.name === "node_modules") continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) listMarkdownFiles(p, out);
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Run every agent-readiness check against `rootDir`. Returns a
+ * report with score, per-check results, and ranked remediation hints.
+ *
+ * @param {string} rootDir — absolute path to the repo root to audit
+ * @returns {{ score: number, checks: object[], topFixes: object[] }}
+ */
+export function runAgentReadiness(rootDir) {
+  const checks = [];
+  let earned = 0;
+  let possible = 0;
+  for (const c of CHECKS) {
+    possible += c.weight;
+    let result;
+    try {
+      result = c.run(rootDir);
+    } catch (err) {
+      result = { ok: false, hint: `Check threw: ${err.message}`, details: { error: err.message } };
+    }
+    if (result.ok) earned += c.weight;
+    checks.push({
+      id: c.id,
+      description: c.description,
+      weight: c.weight,
+      score: result.ok ? c.weight : 0,
+      ok: result.ok,
+      hint: result.hint,
+      details: result.details || {},
+    });
+  }
+  const score = possible === 0 ? 0 : Math.round((earned / possible) * 100);
+  const topFixes = checks
+    .filter((c) => !c.ok && c.hint)
+    .sort((a, b) => b.weight - a.weight)
+    .slice(0, 5)
+    .map((c, i) => ({
+      priority: i + 1,
+      checkId: c.id,
+      weightLost: c.weight,
+      action: c.hint,
+    }));
+  return { score, possible, earned, checks, topFixes };
+}
+
+/**
+ * Render the report in plain text for the human terminal.
+ */
+export function formatAgentReadinessReport({ score, checks, topFixes }, rootDir) {
+  const lines = [`Agent Readiness — ${rootDir}: ${score}/100`, ""];
+  for (const c of checks) {
+    const tick = c.ok ? "✓" : "✗";
+    const pts = `(+${c.score})`.padStart(6);
+    lines.push(`  ${tick} ${c.description.padEnd(50)} ${pts}${c.hint ? "  " + c.hint : ""}`);
+  }
+  if (topFixes.length > 0) {
+    lines.push("", "Top fixes:");
+    for (const f of topFixes) {
+      lines.push(`  ${f.priority}. [${f.checkId}] ${f.action}`);
+    }
+  }
+  return lines.join("\n");
+}

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