@dev-tren/mapd 0.21.0

package/src/core/solutions.js

@@ -0,0 +1,254 @@
+/**
+ * solutions.js — `mapd solutions`: the "bigger picture" layer above raw
+ * findings. Two layers, deliberately separated:
+ *
+ * Layer 1 (buildSolutions, this file's core) is 100% deterministic and
+ * always complete on its own, with zero LLM/network involvement:
+ *   - clusters related findings by real file overlap (Union-Find) — so
+ *     e.g. 5 separate duplicate-function findings that all touch the same
+ *     files surface as ONE problem, not 5 unrelated line items
+ *   - scores each cluster's blast radius from the actual import graph and
+ *     workflow membership already computed by graph.js — how many
+ *     workflows does this touch, how depended-upon are its files
+ *   - ranks clusters by (finding severity/priority) × blast radius
+ * Every fact in the output — file, workflow ID, suggestion — traces back to
+ * a real finding already in the review queue. Nothing here is invented.
+ *
+ * Layer 2 (narrateSolutions) is optional and additive: if a provider is
+ * configured, it asks the LLM to write a short "why this matters" paragraph
+ * per cluster — but it may ONLY rephrase/argue from the facts layer 1
+ * already produced. The response is mechanically verified afterward (every
+ * file path and workflow ID the narrative mentions must already appear in
+ * that cluster's own data); a narrative that fails verification is thrown
+ * away, never surfaced. Layer 1's output is always complete without layer 2.
+ */
+
+import path from "node:path";
+import { buildScoredGraph } from "./intelligence.js";
+import { pending, loadQueue } from "./review.js";
+import { loadFinding } from "./fix.js";
+import { priorityOf, filesOf } from "./findingScoring.js";
+import { checkReportFreshness } from "./staleness.js";
+import { verifyGrounding } from "./grounding.js";
+
+/** Iterative Union-Find (path compression, union by nothing fancy — inputs are small). */
+function makeUnionFind(n) {
+  const parent = Array.from({ length: n }, (_, i) => i);
+  const find = (x) => {
+    let root = x;
+    while (parent[root] !== root) root = parent[root];
+    while (parent[x] !== root) { const next = parent[x]; parent[x] = root; x = next; }
+    return root;
+  };
+  const union = (a, b) => { const ra = find(a); const rb = find(b); if (ra !== rb) parent[ra] = rb; };
+  return { find, union };
+}
+
+/**
+ * Groups findings that share at least one file. Dependency- and
+ * architecture-tier findings are excluded from this step and always kept
+ * standalone: they're already whole-repo-scope facts by construction
+ * (orphan-cluster, cjs-in-esm-project, monolithic-workflow, etc. — see
+ * modernize.js's own tiering), so letting them act as file-overlap bridges
+ * would merge unrelated local findings into one meaningless mega-cluster
+ * just because both happen to touch a widely-shared file.
+ */
+function clusterByFileOverlap(resolved) {
+  const { find, union } = makeUnionFind(resolved.length);
+  const fileToIndices = new Map();
+  resolved.forEach((r, i) => {
+    for (const f of r.files) {
+      if (!fileToIndices.has(f)) fileToIndices.set(f, []);
+      fileToIndices.get(f).push(i);
+    }
+  });
+  for (const indices of fileToIndices.values()) {
+    for (let k = 1; k < indices.length; k++) union(indices[0], indices[k]);
+  }
+  const groups = new Map();
+  resolved.forEach((r, i) => {
+    const root = find(i);
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(r);
+  });
+  return [...groups.values()];
+}
+
+/**
+ * Blast radius of a file set: how many of the project's own workflows
+ * include at least one of these files, and how depended-upon the
+ * most-imported file among them is (import in-degree) — both read directly
+ * off graph.js's already-computed workflow membership and import edges,
+ * never estimated.
+ */
+function computeBlastRadius(graph, files) {
+  const fileSet = new Set(files);
+  const workflowsTouched = graph.workflows.filter((w) => w.files.some((f) => fileSet.has(f))).map((w) => w.id);
+  const inDegree = new Map();
+  for (const e of graph.importEdges) if (e.to) inDegree.set(e.to, (inDegree.get(e.to) ?? 0) + 1);
+  const maxImportInDegree = files.reduce((max, f) => Math.max(max, inDegree.get(f) ?? 0), 0);
+  const totalWorkflows = Math.max(1, graph.workflows.length);
+  const totalFiles = Math.max(1, graph.files.length);
+  const workflowShare = workflowsTouched.length / totalWorkflows;
+  const score = Math.min(1, workflowShare + maxImportInDegree / totalFiles);
+  return {
+    workflowsTouched,
+    workflowShare: Number(workflowShare.toFixed(3)),
+    maxImportInDegree,
+    score: Number(score.toFixed(3)),
+    method: "blast-radius-v1 (share of all workflows touched + max import in-degree, both normalized by repo size)",
+  };
+}
+
+/** Layer 1: fully deterministic, no provider required. */
+export function buildSolutions(rootDir, { top = 5 } = {}) {
+  const abs = path.resolve(rootDir);
+  const graph = buildScoredGraph(abs);
+  const freshness = checkReportFreshness(abs);
+  const staleSet = new Set(freshness.staleReports);
+  const allItems = pending(loadQueue(abs)).filter((i) => i.source === "check" || i.source.startsWith("modernize-"));
+  // Same enforcement as handoff.js: findings from a stale report are excluded
+  // from clustering/ranking entirely (with the count disclosed), never mixed
+  // into an action plan with only a banner asking the reader to discount them.
+  const items = allItems.filter((i) => !staleSet.has(path.basename(i.file)));
+  const excludedStaleCount = allItems.length - items.length;
+
+  const resolved = items
+    .map((item) => {
+      const loaded = loadFinding(abs, item.id);
+      if (!loaded) return null;
+      const finding = loaded.finding;
+      return { item, finding, tier: finding.tier ?? "check", files: filesOf(finding), priority: priorityOf(finding, item) };
+    })
+    .filter(Boolean);
+
+  const standalone = resolved.filter((r) => r.tier === "dependency" || r.tier === "architecture");
+  const clusterable = resolved.filter((r) => r.tier !== "dependency" && r.tier !== "architecture");
+  const groups = [...standalone.map((r) => [r]), ...clusterByFileOverlap(clusterable)];
+
+  const solutions = groups
+    .map((group) => {
+      const files = [...new Set(group.flatMap((r) => r.files))];
+      const blastRadius = computeBlastRadius(graph, files);
+      const memberPriority = Math.max(...group.map((r) => r.priority));
+      const priority = Number((memberPriority * (0.5 + 0.5 * blastRadius.score)).toFixed(3));
+      return {
+        clusterId: group.map((r) => r.item.id).sort().join("+"),
+        kinds: [...new Set(group.map((r) => r.finding.kind ?? r.finding.rule))],
+        files,
+        priority,
+        blastRadius,
+        members: group.map((r) => ({
+          id: r.item.id, source: r.item.source, kind: r.finding.kind ?? r.finding.rule,
+          severity: r.finding.severity ?? null, detail: r.finding.detail,
+          files: r.files, suggestion: r.finding.suggestion ?? null,
+        })),
+        narrative: null,
+      };
+    })
+    .sort((a, b) => b.priority - a.priority)
+    .slice(0, top);
+
+  return {
+    root: abs, fileCount: graph.stats.fileCount, workflowCount: graph.workflows.length,
+    freshness, excludedStaleCount, solutions,
+  };
+}
+
+const NARRATE_SYSTEM_PROMPT =
+  "You will receive a JSON array of \"clusters\" — groups of related, already-verified static-analysis " +
+  "findings from a tool called Map'd, each with real file paths, workflow IDs, and numeric scores.\n\n" +
+  "Your ONLY job: for each cluster, write a short \"whyItMatters\" paragraph (2-4 sentences) explaining " +
+  "its priority, using ONLY the facts given.\n\n" +
+  "Strict rules:\n" +
+  "- Never mention a file path that is not in that cluster's \"files\" list.\n" +
+  "- Never mention a workflow ID that is not in that cluster's \"blastRadius.workflowsTouched\" list.\n" +
+  "- Never state a suggestion beyond what is already in that cluster's members' \"suggestion\" fields — " +
+  "you may combine or rephrase them, never invent a new one.\n" +
+  "- Never state a number that is not already present in the cluster's data.\n" +
+  "- If you are not confident you can do this without adding anything new, write \"\" for that cluster instead of guessing.\n\n" +
+  "Respond with ONLY a JSON array, same length and order as the input, each element: {\"whyItMatters\": \"...\"}";
+
+/**
+ * Layer 2: optional. `data` is buildSolutions' output. Every candidate
+ * narrative is mechanically checked against that same cluster's real data
+ * before being attached — a narrative that cites a file or workflow ID not
+ * already present in the cluster is discarded, never surfaced, regardless
+ * of how plausible the prose reads. Fails safe to the unmodified layer-1
+ * data on no provider, no response, malformed JSON, or a shape mismatch.
+ */
+export async function narrateSolutions(data, provider, { graph } = {}) {
+  if (!provider?.available?.() || !data.solutions.length) return data;
+
+  const payload = data.solutions.map((s) => ({
+    kinds: s.kinds, files: s.files, priority: s.priority, blastRadius: s.blastRadius,
+    members: s.members.map((m) => ({ kind: m.kind, severity: m.severity, detail: m.detail, suggestion: m.suggestion })),
+  }));
+
+  let raw;
+  try { raw = await provider.complete(NARRATE_SYSTEM_PROMPT, JSON.stringify(payload), 2000); }
+  catch { return data; }
+  if (!raw) return data;
+
+  let parsed;
+  try {
+    const jsonMatch = raw.match(/\[[\s\S]*\]/);
+    parsed = JSON.parse(jsonMatch ? jsonMatch[0] : raw);
+  } catch { return data; }
+  if (!Array.isArray(parsed) || parsed.length !== data.solutions.length) return data;
+
+  const solutions = data.solutions.map((s, i) => {
+    const text = parsed[i]?.whyItMatters;
+    if (typeof text !== "string" || !text.trim()) return s;
+
+    const check = verifyGrounding(text, { files: s.files, workflowIds: s.blastRadius.workflowsTouched, graph });
+    if (!check.grounded) {
+      const v = check.violations[0];
+      return { ...s, narrative: null, narrativeSkippedReason: `mentioned a ${v.type} ("${v.value}") not in this cluster's data` };
+    }
+
+    return { ...s, narrative: text.trim() };
+  });
+  return { ...data, solutions };
+}
+
+/** Renders buildSolutions' (optionally narrateSolutions'd) data as plain text. */
+export function renderSolutions(data) {
+  if (!data.solutions.length) {
+    // "no open findings" and "every finding was excluded as stale" are very
+    // different situations — say which one actually happened.
+    return data.excludedStaleCount > 0
+      ? `All ${data.excludedStaleCount} open finding(s) come from stale report(s) (${data.freshness.staleReports.join(", ")}) that ` +
+        "predate a more recent source change — nothing current to synthesize. Re-run `mapd check`/`mapd modernize` first."
+      : "No open findings — nothing to synthesize. Run `mapd check` / `mapd modernize` first.";
+  }
+
+  const lines = [];
+  if (data.freshness?.stale && data.excludedStaleCount > 0) {
+    lines.push(`⚠ STALE REPORTS EXCLUDED: ${data.freshness.staleReports.join(", ")} predate a more recent source change. ` +
+      `${data.excludedStaleCount} finding(s) sourced from them were EXCLUDED from the solutions below (not just flagged). ` +
+      "Re-run `mapd check`/`mapd modernize` to refresh and include them.");
+    lines.push("");
+  } else if (data.freshness?.stale) {
+    // stale report(s) exist but contributed no open findings — one quiet line,
+    // not a warning banner about zero exclusions
+    lines.push(`note: ${data.freshness.staleReports.join(", ")} predate a more recent source change but contributed no open findings; re-run \`mapd check\`/\`mapd modernize\` to refresh.`);
+    lines.push("");
+  }
+  lines.push(`Map'd solutions — ${data.fileCount} files, ${data.workflowCount} workflows`, "");
+  data.solutions.forEach((s, i) => {
+    const header = `${i + 1}. ${s.kinds.join(" + ").toUpperCase()}  (priority ${s.priority}, ${s.members.length} finding(s))`;
+    lines.push(header);
+    lines.push("-".repeat(header.length));
+    lines.push(`Blast radius: touches ${s.blastRadius.workflowsTouched.length} workflow(s) ` +
+      `(${(s.blastRadius.workflowShare * 100).toFixed(0)}% of all workflows), ` +
+      `most-depended-upon file has ${s.blastRadius.maxImportInDegree} importer(s).`);
+    if (s.blastRadius.workflowsTouched.length) lines.push(`Workflows: ${s.blastRadius.workflowsTouched.join(", ")}`);
+    lines.push(`Files: ${s.files.join(", ")}`);
+    if (s.narrative) lines.push(`Why it matters: ${s.narrative}`);
+    else if (s.narrativeSkippedReason) lines.push(`(narrative skipped — ${s.narrativeSkippedReason})`);
+    for (const m of s.members) lines.push(`  - [${m.id}] ${m.kind}${m.severity ? ` (${m.severity})` : ""}: ${m.detail}`);
+    lines.push("");
+  });
+  return lines.join("\n").trimEnd();
+}

package/src/core/staleness.js

@@ -0,0 +1,45 @@
+/**
+ * staleness.js — reports from `mapd check`/`mapd modernize` are written to
+ * disk once and re-read by review.js, handoff.js, solutions.js, and chat's
+ * /findings and /review every time after that. Nothing previously compared
+ * a report's age against the current tree, so a finding that was already
+ * fixed (in this project or by an external agent) kept getting presented as
+ * current. That's a real form of overclaiming — stale data shown as current
+ * fact without disclosure — so this is checked and surfaced explicitly
+ * wherever those reports get read, never silently trusted.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { latestSourceMtime } from "./parser.js";
+
+const REPORT_FILES = ["findings.json", "modernize-light.json", "modernize-medium.json", "modernize-heavy.json"];
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/**
+ * Compares each present report's `generatedAt` against the most recent
+ * source-file mtime in the project. Returns `{checked:false}` when no
+ * reports exist yet (nothing to be stale). Never mutates or deletes
+ * anything — purely informational, for callers to disclose.
+ */
+export function checkReportFreshness(rootDir) {
+  const abs = path.resolve(rootDir);
+  const dir = path.join(abs, ".mapd");
+  const reports = REPORT_FILES
+    .map((name) => ({ name, path: path.join(dir, name) }))
+    .filter((r) => fs.existsSync(r.path))
+    .map((r) => ({ ...r, data: readJson(r.path) }))
+    .filter((r) => r.data?.generatedAt);
+
+  if (!reports.length) return { checked: false, stale: false, staleReports: [] };
+
+  const latestSource = latestSourceMtime(abs);
+  const staleReports = reports
+    .filter((r) => new Date(r.data.generatedAt).getTime() < latestSource)
+    .map((r) => r.name);
+
+  return { checked: true, stale: staleReports.length > 0, staleReports, latestSourceMtime: latestSource };
+}

package/src/core/testGuidance.js

@@ -0,0 +1,226 @@
+/**
+ * testGuidance.js — Test Guidance: make the testPresence signal honest.
+ *
+ * confidence.js credits a source file as "tested" if ANY file on a test path
+ * merely contains its basename as a substring (see hasTestFor). That is cheap
+ * to satisfy and easy to fool: an empty `foo.test.js`, or a `foobar.test.js`
+ * that never touches foo, both earn full credit.
+ *
+ * This module re-derives that relationship from real structure — the parsed
+ * imports and exports already on every graph node — and separates:
+ *   tested-real     a matching test imports THIS module AND references ≥1 export
+ *   tested-shallow  a matching test imports the module XOR references an export
+ *   tested-nameonly the basename rule credits it, but no import/symbol link
+ *                   exists → padding: it inflates the score without evidence
+ *   untested        no test matches by the basename rule at all
+ *
+ * It never rewrites the score here (that would move every baseline). It reports
+ * how much of testPresence is real vs padding, so the inflation is visible —
+ * and `mapd score` can be hardened as an explicit, separate decision.
+ */
+
+import path from "node:path";
+
+/** The LITERAL rules confidence.js uses — imported nowhere else, mirrored here so the report can quote them exactly. */
+export const TEST_PATH_RE = /(\.test\.|\.spec\.|__tests__\/|tests?\/)/;
+export const SRC_EXT_RE = /\.(js|ts|jsx|tsx|mjs|cjs|py|go|rs|rb|java|php)$/;
+
+const basenameKey = (file) => path.posix.basename(file).replace(SRC_EXT_RE, "");
+const stripExt = (file) => file.replace(SRC_EXT_RE, "");
+
+/** Resolve a relative import from `importer` to a repo-relative path without extension; null for bare/external. */
+function resolveImport(importer, source) {
+  if (!source || !source.startsWith(".")) return null;
+  return stripExt(path.posix.normalize(path.posix.join(path.posix.dirname(importer), source)));
+}
+
+const normName = (s) => s.toLowerCase().replace(/[-_]/g, "");
+const GENERIC_TEST_TOKENS = new Set(["test", "tests", "spec", "specs", "__tests__", "e2e", "unit", "integration"]);
+
+/** Name tokens a test file answers to: its path segments/words plus its whole stem (logger-redaction → logger, redaction, loggerredaction). */
+function testNameTokens(testFile) {
+  const stem = stripExt(testFile);
+  const tokens = new Set();
+  for (const seg of stem.split("/")) {
+    const words = seg.split(".").filter((w) => !GENERIC_TEST_TOKENS.has(w.toLowerCase()));
+    if (!words.length) continue;
+    tokens.add(normName(words.join("")));
+    for (const w of words.join("-").split(/[-_]/)) if (w && !GENERIC_TEST_TOKENS.has(w.toLowerCase())) tokens.add(normName(w));
+  }
+  return tokens;
+}
+
+const QUALITY_RANK = { real: 3, shallow: 2, nameonly: 1 };
+
+function suggestTestName(file, hasTopTestsDir) {
+  const ext = (file.match(SRC_EXT_RE)?.[0] ?? ".js").slice(1);
+  const testExt = ext === "mjs" || ext === "cjs" ? "js" : ext;
+  const base = basenameKey(file);
+  return hasTopTestsDir ? `tests/${base}.test.${testExt}` : `${path.posix.dirname(file)}/${base}.test.${testExt}`;
+}
+
+/**
+ * The canonical per-source test-credit classification, derived from real parsed
+ * imports/exports. Returns one record per non-test source file. This is the
+ * SINGLE definition of "is this file really tested" — confidence.js consumes it
+ * so the score and this report can never disagree.
+ */
+export function classifyTestCredit(graph) {
+  const files = graph.files ?? [];
+  const testFiles = files.filter((f) => TEST_PATH_RE.test(f.file));
+  const srcFiles = files.filter((f) => !TEST_PATH_RE.test(f.file));
+  const wfFiles = new Set(graph.workflows.flatMap((w) => w.files)); // only these move testPresence
+  const hasTopTestsDir = files.some((f) => /^tests?\//.test(f.file));
+
+  // Precompute each test file's resolved import targets + imported symbol names.
+  const testMeta = testFiles.map((t) => {
+    const targets = new Set();
+    const names = new Set();
+    for (const imp of t.imports ?? []) {
+      // A type-only import exercises nothing at runtime, so it must not earn
+      // test credit — otherwise `import type { Finding }` reads as coverage.
+      if (imp.typeOnly) continue;
+      const r = resolveImport(t.file, imp.source);
+      if (r) targets.add(r);
+      for (const n of imp.names ?? []) names.add(n);
+    }
+    return { file: t.file, targets, names, nameTokens: testNameTokens(t.file) };
+  });
+
+  return srcFiles.map((s) => {
+    const key = basenameKey(s.file);
+    const sNoExt = stripExt(s.file);
+    const exportSet = new Set(s.exports ?? []);
+
+    // Credit a test that NAMES this file (tests/logger.test.ts) OR one that
+    // simply IMPORTS it. Gating on the filename alone missed real coverage:
+    // tests/setup.test.ts imports redactSecrets from src/logger.ts, exercises
+    // it properly, and was reported as untested purely because the test is not
+    // called "logger". An import is stronger evidence than a filename.
+    // Name matching is whole-token, not substring: a raw `includes` let src/a.js
+    // "match" tests/format.test.js and src/test.js match every test file.
+    const nameKey = normName(key);
+    const nameMatched = testMeta.filter((t) => t.nameTokens.has(nameKey) || t.targets.has(sNoExt));
+
+    const credits = nameMatched.map((t) => {
+      const pathLinked = t.targets.has(sNoExt);
+      const symbolLinked = exportSet.size > 0 && [...exportSet].some((e) => t.names.has(e));
+      const quality = pathLinked && symbolLinked ? "real"
+        : pathLinked || symbolLinked ? "shallow"
+        : "nameonly";
+      return { test: t.file, quality, pathLinked, symbolLinked };
+    }).sort((a, b) => QUALITY_RANK[b.quality] - QUALITY_RANK[a.quality]);
+
+    const best = credits[0];
+    const status = !nameMatched.length ? "untested"
+      : best.quality === "real" ? "tested-real"
+      : best.quality === "shallow" ? "tested-shallow"
+      : "tested-nameonly";
+
+    return {
+      file: s.file,
+      inWorkflow: wfFiles.has(s.file),
+      exportCount: exportSet.size,
+      status,
+      credits,
+      suggestedTest: suggestTestName(s.file, hasTopTestsDir),
+    };
+  });
+}
+
+/** Files that count toward the HONEST testPresence signal (real or shallow credit). */
+export function honestlyTestedFiles(graph) {
+  return new Set(classifyTestCredit(graph)
+    .filter((s) => s.status === "tested-real" || s.status === "tested-shallow")
+    .map((s) => s.file));
+}
+
+/**
+ * Analyze every workflow source file's test relationship. Returns per-file
+ * classification + credit map + an honest-vs-current testPresence summary.
+ */
+export function analyzeTestCoverage(rootDir, graph) {
+  const perSource = classifyTestCredit(graph);
+
+  const wf = perSource.filter((s) => s.inWorkflow);
+  const count = (st) => wf.filter((s) => s.status === st).length;
+  const real = count("tested-real"), shallow = count("tested-shallow");
+  const nameOnly = count("tested-nameonly"), untested = count("untested");
+  const total = wf.length || 1;
+
+  return {
+    rule: {
+      honest: 'a source file counts toward testPresence only if a matching test IMPORTS the module (path-linked) and/or REFERENCES one of its exports (symbol-linked) — real or shallow credit',
+      looseLegacy: 'the retired substring rule credited any test whose path merely contained the basename; name-only matches now earn nothing',
+    },
+    summary: {
+      workflowFiles: wf.length,
+      real, shallow, nameOnlyPadding: nameOnly, untested,
+      // testPresence is now the HONEST value and matches what confidence.js scores.
+      testPresence: Number(((real + shallow) / total).toFixed(3)),
+      // what the retired substring rule would have counted — kept only to show the gap.
+      looseRuleWouldCredit: Number(((real + shallow + nameOnly) / total).toFixed(3)),
+      paddingRejected: Number((nameOnly / total).toFixed(3)),
+    },
+    files: perSource,
+  };
+}
+
+// ── views ──────────────────────────────────────────────────────────────────
+
+/** Files that lower testPresence: untested, plus name-only padding (credited but unbacked). */
+export function testGaps(analysis, { includeShallow = false } = {}) {
+  const wanted = new Set(["untested", "tested-nameonly", ...(includeShallow ? ["tested-shallow"] : [])]);
+  return analysis.files
+    .filter((s) => s.inWorkflow && wanted.has(s.status))
+    .sort((a, b) => a.status.localeCompare(b.status) || a.file.localeCompare(b.file));
+}
+
+/** The source→test crediting map. `paddingOnly` narrows to the anti-padding view. */
+export function testCredit(analysis, { paddingOnly = false } = {}) {
+  return analysis.files.filter((s) => {
+    if (!s.credits.length && !paddingOnly) return s.inWorkflow; // untested workflow files still shown
+    if (paddingOnly) return s.status === "tested-nameonly";
+    return s.credits.length > 0;
+  });
+}
+
+// ── renderers ────────────────────────────────────────────────────────────────
+
+export function renderTestGaps(analysis, gaps, theme) {
+  const { bold, dim, red, green, yellow, cyan } = theme;
+  const s = analysis.summary;
+  const lines = [`\n${bold("Test gaps")} — ${s.workflowFiles} workflow file(s)`];
+  lines.push(`  testPresence (honest, scored): ${s.testPresence < 0.5 ? red(s.testPresence) : green(s.testPresence)}${s.paddingRejected > 0 ? dim(`  (the retired substring rule would have inflated this to ${s.looseRuleWouldCredit})`) : ""}`);
+  lines.push(`  ${green(`${s.real} real`)} · ${cyan(`${s.shallow} shallow`)} · ${yellow(`${s.nameOnlyPadding} name-only padding (earns nothing)`)} · ${red(`${s.untested} untested`)}`);
+  lines.push(dim(`  rule: ${analysis.rule.honest}`));
+  if (!gaps.length) { lines.push(green("\n  No gaps — every workflow file has a real or shallow test.")); return lines.join("\n"); }
+  const label = { "untested": red("untested"), "tested-nameonly": yellow("name-only padding"), "tested-shallow": cyan("shallow") };
+  for (const g of gaps) {
+    lines.push(`\n  ${label[g.status] ?? g.status}  ${bold(g.file)}${g.exportCount === 0 ? dim(" (no exports)") : ""}`);
+    if (g.status === "tested-nameonly") {
+      lines.push(dim(`      credited by ${g.credits.map((c) => c.test).join(", ")} — but no import or export reference; the credit is a filename coincidence`));
+    } else if (g.status === "untested") {
+      lines.push(dim(`      suggested: ${g.suggestedTest}  (import ${g.file}, exercise ${g.exportCount ? "its exports" : "its behavior"})`));
+    } else {
+      lines.push(dim(`      credited by ${g.credits[0].test} — ${g.credits[0].pathLinked ? "imports the module but references no export" : "references an export but doesn't import the module"}`));
+    }
+  }
+  return lines.join("\n");
+}
+
+export function renderTestCredit(rows, theme, { paddingOnly = false } = {}) {
+  const { bold, dim, red, green, yellow, cyan } = theme;
+  const qColor = { real: green, shallow: cyan, nameonly: yellow };
+  const lines = [`\n${bold(paddingOnly ? "Test credit — padding suspects" : "Test credit")}`];
+  if (!rows.length) { lines.push(green(paddingOnly ? "\n  No padding suspects — all credits are real or shallow." : "\n  No credited files.")); return lines.join("\n"); }
+  for (const r of rows) {
+    if (!r.credits.length) { lines.push(`\n  ${red("untested")}  ${bold(r.file)}  ${dim(`→ suggest ${r.suggestedTest}`)}`); continue; }
+    lines.push(`\n  ${bold(r.file)}  ${dim(`(${r.exportCount} export(s))`)}`);
+    for (const c of r.credits) {
+      const links = [c.pathLinked ? "imports module" : null, c.symbolLinked ? "uses export" : null].filter(Boolean).join(" + ") || "name match only";
+      lines.push(`      ${qColor[c.quality](c.quality.padEnd(8))} ${c.test}  ${dim(`(${links})`)}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/core/theme.js

@@ -0,0 +1,50 @@
+/**
+ * theme.js — minimal ANSI terminal styling for human-readable CLI output.
+ * No new dependency (plain escape codes). Respects NO_COLOR and non-TTY
+ * output (piped/redirected) by degrading to plain text automatically — never
+ * pollutes --json output or a file redirect with escape codes.
+ */
+
+function colorEnabled() {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return !!process.stdout.isTTY;
+}
+
+function wrap(code) {
+  return (text) => (colorEnabled() ? `\x1b[${code}m${text}\x1b[0m` : String(text));
+}
+
+export const bold = wrap(1);
+export const dim = wrap(2);
+export const red = wrap(31);
+export const green = wrap(32);
+export const yellow = wrap(33);
+export const blue = wrap(34);
+export const magenta = wrap(35);
+export const cyan = wrap(36);
+
+/** Green when healthy, yellow when marginal, red when fragile — a quick visual cue, not a new signal. */
+export function confidenceColor(score) {
+  if (score >= 0.8) return green;
+  if (score >= 0.5) return yellow;
+  return red;
+}
+
+/** Wraps `items` (strings) into lines no wider than `width`, joined by `sep`, each subsequent line indented. */
+export function wrapList(items, { width = 100, indent = "    ", sep = ", " } = {}) {
+  if (!items.length) return "";
+  const lines = [];
+  let current = "";
+  for (const item of items) {
+    const candidate = current ? `${current}${sep}${item}` : item;
+    if (candidate.length > width && current) {
+      lines.push(current);
+      current = item;
+    } else {
+      current = candidate;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.map((l, i) => (i === 0 ? l : `${indent}${l}`)).join("\n");
+}