fapony 0.4.0 → 0.6.0

package/src/adapters/mcp/primitives.ts

@@ -7,7 +7,7 @@
 // §0 rule: add-only — never remove or rename exported symbols.
 
 import { execSync } from "node:child_process";
-import type { BlastEntry } from "../../analyze.js";
+import type { BlastEntry } from "../../analyze/index.js";
 import { ROOT } from "../../update.js";
 
 // ─── Server build identity ─────────────────────────────────────────────

package/src/adapters/mcp/tools/check.ts

@@ -1,6 +1,6 @@
 // src/mcp/tools/check.ts — handoff_check tool
 
-import { blastRadiusForWorktree } from "../../../analyze.js";
+import { blastRadiusForWorktree } from "../../../analyze/index.js";
 import type { CheckResult } from "../primitives.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 

package/src/adapters/mcp/tools/collect.ts

@@ -1,7 +1,7 @@
 // src/mcp/tools/collect.ts — handoff_collect tool
 
 import { execSync } from "node:child_process";
-import { isTestFile } from "../../../analyze.js";
+import { isTestFile } from "../../../analyze/index.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 
 // --- Git helper ---

package/src/adapters/mcp/tools/index.ts

@@ -23,7 +23,8 @@ export const TOOLS = [
       "memDir shows which log dir was resolved (walked up from the given " +
       "worktree — in a monorepo pass the app directory to read its log). " +
       "Returns {rows, total, filesFound, " +
-      "skipped, memDir}: memDir:null = no mem at all, not 'nothing matched'.",
+      "skipped, memDir}: memDir:null = no mem at all, not 'nothing matched'. " +
+      "A key query that misses adds knownKeys (every key in the log).",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -64,6 +65,11 @@ export const TOOLS = [
           description:
             "true = unresolved work only: drops close/claim/release/synced rows and work rows already closed. Omit = every row. With kind:[bug] answers 'what bugs remain?'",
         },
+        key: {
+          type: "string",
+          description:
+            "Exact problem-identity match — miss returns knownKeys (every key in the log). No pattern: a wrong-pattern query must reach the server",
+        },
       },
       required: ["worktree"],
     },
@@ -104,6 +110,12 @@ export const TOOLS = [
           type: "string",
           description: "Optional spec/plan .md path",
         },
+        key: {
+          type: "string",
+          pattern: "^[a-z0-9-]{3,40}$",
+          description:
+            "Problem identity (not kind, not files) — same problem, same key",
+        },
       },
       required: ["worktree", "kind", "text", "files"],
     },

package/src/adapters/mcp/tools/mem.ts

@@ -23,6 +23,8 @@ export interface MemFindResult {
   filesFound: number;
   skipped: number;
   memDir: string | null;
+  /** Present only when a key query missed — every distinct key in the log. */
+  knownKeys?: string[];
 }
 
 export function memFind(args: {
@@ -33,6 +35,7 @@ export function memFind(args: {
   since?: string;
   limit?: number;
   open?: boolean;
+  key?: string;
 }): MemFindResult {
   // Query logic lives in the shared engine (src/mem/engine.ts) — this wrapper
   // owns only the read (readMemLog sees live + rotated archives via its loose
@@ -40,22 +43,24 @@ export function memFind(args: {
   // omitting kind returns every kind (locked by test). CLI cmdFind calls the
   // same engine with its own bookkeeping exclude.
   const read = readMemLog(args.worktree);
-  const { rows: matched, total } = engineFind(read.rows, {
+  const found = engineFind(read.rows, {
     text: args.text,
     files: args.files,
     kind: args.kind,
     sinceIso: args.since,
+    key: args.key,
     limit: args.limit,
     open: args.open,
   });
   return {
-    rows: matched,
-    total,
+    rows: found.rows,
+    total: found.total,
     filesFound: read.filesFound,
     skipped: read.skipped,
     // memDir separates "no mem at all" from "nothing matched" (spec §3) and
     // makes the monorepo single-log limit visible (spec §5.1).
     memDir: resolveMemDir(args.worktree),
+    ...(found.knownKeys ? { knownKeys: found.knownKeys } : {}),
   };
 }
 
@@ -93,9 +98,18 @@ export function toolMemFind(args: Record<string, unknown>): ToolResult {
   }
   const limit = typeof args.limit === "number" ? args.limit : undefined;
   const open = typeof args.open === "boolean" ? args.open : undefined;
+  // Shape gate like mem_add — a non-string key must not coerce to undefined
+  // (silent drop = reject-without-saying). Pattern is NOT checked here: find
+  // answers a wrong-pattern key with knownKeys, not a reject (SPEC fail example).
+  if (args.key !== undefined && typeof args.key !== "string") {
+    return errorResult(
+      'key must be a string matching [a-z0-9-]{3,40} — e.g. "fix-stop-dedupe"',
+    );
+  }
+  const key = typeof args.key === "string" ? args.key : undefined;
 
   return jsonResult(
-    memFind({ worktree, files, text, kind, since, limit, open }),
+    memFind({ worktree, files, text, kind, since, limit, open, key }),
   );
 }
 
@@ -112,6 +126,7 @@ export function memAdd(args: {
   text: string;
   files: string[];
   spec?: string;
+  key?: string;
 }): MemAddResult {
   initStore(args.worktree);
   return engineAdd({
@@ -119,6 +134,7 @@ export function memAdd(args: {
     text: args.text,
     files: args.files,
     spec: args.spec,
+    key: args.key,
   });
 }
 
@@ -166,8 +182,17 @@ export function toolMemAdd(args: Record<string, unknown>): ToolResult {
       ? args.spec.trim()
       : undefined;
 
+  // Shape gate here, pattern check in engineAdd — a non-string key must not
+  // slip through as undefined (silent drop = reject-without-saying, SPEC §Validation).
+  if (args.key !== undefined && typeof args.key !== "string") {
+    return errorResult(
+      'key must be a string matching [a-z0-9-]{3,40} — e.g. "fix-stop-dedupe"',
+    );
+  }
+  const key = typeof args.key === "string" ? args.key : undefined;
+
   try {
-    const result = memAdd({ worktree, kind, text, files, spec });
+    const result = memAdd({ worktree, kind, text, files, spec, key });
     return jsonResult(result);
   } catch (e) {
     return errorResult(e instanceof Error ? e.message : String(e));

package/src/adapters/mcp/tools/report.ts

@@ -4,7 +4,7 @@
 // run metrics + verdict into a single VerificationReport.
 // Calls existing primitives — no duplicate parser/conformance logic.
 
-import { blastRadiusForWorktree } from "../../../analyze.js";
+import { blastRadiusForWorktree } from "../../../analyze/index.js";
 import { loadConfig } from "../../../core/config.js";
 import { getEvents, getRun, openDb } from "../../../db/store.js";
 import { parseGateEventData } from "../../../parse.js";

package/src/adapters/mcp/transport.ts

@@ -19,7 +19,7 @@ import { errorResult, type ToolResult } from "./types.js";
 
 const SERVER_INSTRUCTIONS = `fapony records decisions, bugs, and notes about this project so the next session (or the next agent) knows what happened and what to watch out for.
 
-When you finish a unit of work, record a mem row: fapony mem add <decision|bug|note> "what happened" --files <files> <path/to/PLAN.md>. files[] is required — a row without it is unfindable when you touch that file next session.
+When you finish a unit of work, record a mem row: fapony mem add <decision|bug|note> "what happened" --files <files> <path/to/PLAN.md>. files[] is required — a row without it is unfindable when you touch that file next session. Name a known problem with --key <a-z0-9-id> and recall every row for it via mem_find key.
 
 worktree must be the absolute path (git rev-parse --show-toplevel): every query scopes by it, so a bare name or none files the row where nothing reads it, and nothing errors to say so. Write the note standalone — it is read months later with no access to this conversation.
 

package/src/analyze/barrels.ts

@@ -0,0 +1,56 @@
+// src/analyze/barrels.ts — exports seen *through* barrels.
+//
+// `export * from "./x"` is reported by Bun.Transpiler.scan as an IMPORT edge and
+// never as an export, so a barrel file scans as having zero exports. Measured on
+// vela 2026-09-18: 211 barrels out of 1,996 source files, and `@innominix/ui`
+// alone is imported 462 times — the blind spot hides most of the cross-package
+// graph, which is why a wrapper reached through a barrel reads as unused. Named
+// re-exports (`export { x } from "./y"`) are already reported correctly; only the
+// star form needs this. Cost to close it: 1.9ms on a 17-export barrel. tsc answers
+// the same question type-accurately for 2,176ms — see SPEC-convention-debt.md §2.2
+// for why that 1,145x is not worth paying here.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { extractExports } from "../map.js";
+import { resolvePythonRelative } from "./python.js";
+import { resolveRelative } from "./resolve-ts.js";
+
+export const STAR_REEXPORT_RE =
+  /^[ \t]*export\s+\*\s+(?:as\s+[\w$]+\s+)?from\s*["'](\.[^"']+)["']/gm;
+
+// `from .x import *` — the Python shape of a star re-export. Absolute star
+// imports can't resolve (same bucket as TS bare specifiers), so only relative.
+export const PY_STAR_REEXPORT_RE =
+  /^[ \t]*from\s*(\.+)((?:[\w.]*))\s+import\s+\*/gm;
+
+export function exportsThroughBarrels(
+  absDir: string,
+  rel: string,
+  filesSet: Set<string>,
+  seen = new Set<string>(),
+): string[] {
+  if (seen.has(rel)) return []; // barrels re-export each other; stop the cycle
+  seen.add(rel);
+  let source: string;
+  try {
+    source = readFileSync(join(absDir, rel), "utf-8");
+  } catch {
+    return [];
+  }
+  const out = extractExports(source, undefined, rel)
+    .symbols.filter((s) => s.name !== "*")
+    .map((s) => s.name);
+  STAR_REEXPORT_RE.lastIndex = 0;
+  for (const m of source.matchAll(STAR_REEXPORT_RE)) {
+    const hit = resolveRelative(rel, m[1], filesSet);
+    if (hit) out.push(...exportsThroughBarrels(absDir, hit, filesSet, seen));
+  }
+  PY_STAR_REEXPORT_RE.lastIndex = 0;
+  for (const m of source.matchAll(PY_STAR_REEXPORT_RE)) {
+    const hit = resolvePythonRelative(rel, m[1], m[2], filesSet);
+    if (hit) out.push(...exportsThroughBarrels(absDir, hit, filesSet, seen));
+  }
+  return [...new Set(out)];
+}

package/src/analyze/blast.ts

@@ -0,0 +1,58 @@
+// src/analyze/blast.ts — `blastRadius()`: per-file { dependents, tested }
+// facts for handoff_check / verification_report.
+
+import { isTestedThroughBarrels } from "./criteria.js";
+import { buildGraph } from "./graph.js";
+import type { BlastEntry, ImportGraph } from "./types.js";
+
+// BFS over the reverse-edge map — one grep-and-recurse chain collapsed into
+// one walk. `seen` makes cycles a no-op instead of an infinite loop.
+function transitiveDependentsCount(graph: ImportGraph, file: string): number {
+  const seen = new Set<string>();
+  let frontier = graph.dependents.get(file) ?? new Set<string>();
+  while (frontier.size > 0) {
+    const next = new Set<string>();
+    for (const f of frontier) {
+      if (seen.has(f)) continue;
+      seen.add(f);
+      for (const dep of graph.dependents.get(f) ?? []) {
+        if (!seen.has(dep)) next.add(dep);
+      }
+    }
+    frontier = next;
+  }
+  // A cycle can walk back to `file` itself — it's not its own dependent.
+  seen.delete(file);
+  return seen.size;
+}
+
+export function blastRadius(
+  graph: ImportGraph,
+  files: string[],
+): Record<string, BlastEntry> {
+  const out: Record<string, BlastEntry> = {};
+  for (const f of files) {
+    const deps = graph.dependents.get(f) ?? new Set<string>();
+    out[f] = {
+      dependents: deps.size,
+      tested: isTestedThroughBarrels(graph, f),
+      transitive: transitiveDependentsCount(graph, f),
+    };
+  }
+  return out;
+}
+
+// Convenience for the MCP tools: graph the worktree live, map files[] to
+// blast radius. Null when there is nothing to map or the dir is unreadable —
+// callers render "no blast data", never throw.
+export function blastRadiusForWorktree(
+  worktree: string,
+  files: string[],
+): Record<string, BlastEntry> | null {
+  if (files.length === 0) return null;
+  try {
+    return blastRadius(buildGraph(worktree), files);
+  } catch {
+    return null;
+  }
+}

package/src/analyze/cache.ts

@@ -0,0 +1,162 @@
+// src/analyze/cache.ts — session-scoped graph cache.
+//
+// buildGraph is cheap on this repo (~50ms/150 files) but the Edit hint calls it
+// on every Edit — and a Claude Code PreToolUse hook is a *fresh process per
+// tool call*, so an in-process cache alone never survives to the next edit. The
+// graph is therefore mirrored to <faponyDir>/graph-cache/<key>.json:
+//   - auto-build: every build is written through, best-effort (never blocks)
+//   - auto-invalidate: a fingerprint over the source-file set (rel path + size
+//     + mtimeMs) is stored beside the graph; a mismatch means rebuild
+//   - cost: the cache file is only stat-ed when there is one to validate, so a
+//     first-ever call pays build + write; later calls pay a walk + stat + parse,
+//     well under a rebuild on any repo large enough for this to matter
+// Everything here is derived state — an unreadable, corrupt, stale or
+// unwritable cache falls back to a live build and no code path trusts it.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+import { faponyDir } from "../core/config.js";
+import { collectSourceFiles } from "./discover.js";
+import { buildGraph } from "./graph.js";
+import type { ImportGraph } from "./types.js";
+
+const GRAPH_CACHE_VERSION = 1;
+const GRAPH_CACHE_DIR = "graph-cache";
+
+interface SerializedGraph {
+  v: number;
+  fp: string;
+  files: string[];
+  deps: Record<string, string[]>;
+  dependents: Record<string, string[]>;
+  unresolved: number;
+  external: number;
+  barrels: string[];
+}
+
+let _graphCache: { dir: string; fp: string; graph: ImportGraph } | null = null;
+
+/** Drop the in-process graph cache (tests simulate a fresh hook process). */
+export function resetGraphCache(): void {
+  _graphCache = null;
+}
+
+/** Absolute path of a worktree's graph-cache file — may not exist. */
+export function graphCachePath(dir: string): string {
+  const abs = resolve(dir);
+  const slug = abs.replace(/[^A-Za-z0-9]+/g, "-").slice(0, 60);
+  return join(
+    faponyDir(),
+    GRAPH_CACHE_DIR,
+    `${slug}-${Bun.hash(abs).toString(36)}.json`,
+  );
+}
+
+// The graph changes only when the set of source files or their bytes change —
+// size/mtime/ctime catch that without reading any file. ctime rides the same
+// stat call for free and cannot be forged like mtime can (only the system
+// moves it), so an mtime-preserving rewrite still invalidates.
+function graphFingerprint(absDir: string): string {
+  const parts: string[] = [];
+  for (const rel of collectSourceFiles(absDir)) {
+    try {
+      const st = statSync(join(absDir, rel));
+      parts.push(
+        `${rel}\u0000${st.size}\u0000${st.mtimeMs}\u0000${st.ctimeMs}`,
+      );
+    } catch {
+      parts.push(`${rel}\u0000?\u0000?\u0000?`);
+    }
+  }
+  return Bun.hash(parts.join("\n")).toString(36);
+}
+
+function serializeGraph(graph: ImportGraph, fp: string): SerializedGraph {
+  const rec = (m: Map<string, Set<string>>): Record<string, string[]> => {
+    const out: Record<string, string[]> = {};
+    for (const [k, v] of m) out[k] = [...v];
+    return out;
+  };
+  return {
+    v: GRAPH_CACHE_VERSION,
+    fp,
+    files: graph.files,
+    deps: rec(graph.deps),
+    dependents: rec(graph.dependents),
+    unresolved: graph.unresolved,
+    external: graph.external,
+    barrels: [...graph.barrels],
+  };
+}
+
+function hydrateGraph(c: SerializedGraph): ImportGraph {
+  const toMap = (r: Record<string, string[]>): Map<string, Set<string>> => {
+    const m = new Map<string, Set<string>>();
+    for (const [k, v] of Object.entries(r)) m.set(k, new Set(v));
+    return m;
+  };
+  return {
+    files: c.files,
+    deps: toMap(c.deps),
+    dependents: toMap(c.dependents),
+    unresolved: c.unresolved,
+    external: c.external,
+    barrels: new Set(c.barrels),
+  };
+}
+
+function readCachedGraph(path: string, fp: string): ImportGraph | null {
+  try {
+    const cached = JSON.parse(readFileSync(path, "utf-8")) as SerializedGraph;
+    if (cached.v !== GRAPH_CACHE_VERSION || cached.fp !== fp) return null;
+    return hydrateGraph(cached);
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedGraph(path: string, graph: ImportGraph, fp: string): void {
+  try {
+    if (!existsSync(join(faponyDir(), GRAPH_CACHE_DIR))) {
+      mkdirSync(join(faponyDir(), GRAPH_CACHE_DIR), { recursive: true });
+    }
+    // pid-suffixed temp + rename: a reader never sees a half-written file even
+    // when two hook processes race.
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(serializeGraph(graph, fp)), "utf-8");
+    renameSync(tmp, path);
+  } catch {
+    // best-effort — a cache that cannot be written must not break the caller
+  }
+}
+
+export function buildGraphCached(dir: string): ImportGraph {
+  const abs = resolve(dir);
+  // One walk per call: the fingerprint doubles as the in-process validity
+  // check, so a same-process second call after an edit rebuilds instead of
+  // serving the stale graph. A drift between this fp and the built graph
+  // self-heals — the next call recomputes and rebuilds again.
+  const fp = graphFingerprint(abs);
+  if (_graphCache?.dir === abs && _graphCache.fp === fp)
+    return _graphCache.graph;
+  const path = graphCachePath(abs);
+  if (existsSync(path)) {
+    const cached = readCachedGraph(path, fp);
+    if (cached) {
+      _graphCache = { dir: abs, fp, graph: cached };
+      return cached;
+    }
+  }
+  const graph = buildGraph(abs);
+  _graphCache = { dir: abs, fp, graph };
+  writeCachedGraph(path, graph, fp);
+  return graph;
+}

package/src/analyze/cli.ts

@@ -0,0 +1,28 @@
+// src/analyze/cli.ts — `fapony analyze` CLI entry.
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { diagnose } from "./diagnose.js";
+import { formatAnalyze } from "./format.js";
+import { buildGraph } from "./graph.js";
+import type { ImportGraph } from "./types.js";
+
+export function cmdAnalyze(args: string[]): void {
+  const dir = args[0] ?? ".";
+  const absDir = resolve(dir);
+  if (!existsSync(absDir)) {
+    console.error(`fapony analyze: "${dir}" does not exist`);
+    process.exit(1);
+  }
+  let graph: ImportGraph;
+  try {
+    graph = buildGraph(absDir);
+  } catch (e) {
+    console.error(
+      `fapony analyze: cannot scan "${dir}": ${e instanceof Error ? e.message : String(e)}`,
+    );
+    process.exit(1);
+  }
+  console.log(formatAnalyze(graph, diagnose(graph)));
+}

package/src/analyze/criteria.ts

@@ -0,0 +1,81 @@
+// src/analyze/criteria.ts — "is this file tested?" criteria shared by
+// diagnose, blast radius, and review-seed.
+//
+// Same regex collect.ts has always used for test detection — single source of
+// truth now (collect.ts imports isTestFile from here). Do NOT diverge.
+
+import type { ImportGraph } from "./types.js";
+
+// Word-boundary aware: "test"/"spec" match only as whole path segments, not as
+// substrings of other words (e.g. testing.ts, contest.ts, vitest/ do NOT match).
+export const TEST_PATH_RE =
+  /(?:^|[/._-])(?:test|spec)(?:$|[/._-])|__tests__|\.test\.|\.spec\./i;
+
+export function isTestFile(p: string): boolean {
+  return TEST_PATH_RE.test(p);
+}
+
+// A file whose entire body is `export ... from "..."`. Detected because a test
+// importing a barrel is still a test importing everything behind it — without
+// this, every module under src/db/index.ts or src/stats.ts reads as untested.
+const EXPORT_FROM_RE =
+  /export\s+(?:\*|\{[^}]*\}|type\s+\*|type\s+\{[^}]*\})(?:\s+as\s+[\w$]+)?\s+from\s*["'][^"']+["']\s*;?/g;
+
+export function isBarrelSource(content: string, rel?: string): boolean {
+  if (rel?.endsWith("__init__.py") || rel?.endsWith("__init__.pyi")) {
+    // A Python barrel re-exports instead of defining: every logical line is
+    // an import, a from-import, or the `__all__` assignment. Docstrings are
+    // stripped first (nearly every `__init__.py` has one); `#` is cut per
+    // line, which is safe here because import/`__all__` lines carry no `#`
+    // inside strings — only identifiers, dots, commas, and parens.
+    const code = content.replace(/"""[\s\S]*?"""|'''[\s\S]*?'''/g, "");
+    const logical: string[] = [];
+    let buf = "";
+    let open = 0;
+    const push = () => {
+      const t = buf.trim();
+      if (t) logical.push(t);
+      buf = "";
+      open = 0;
+    };
+    for (const rawLine of code.split("\n")) {
+      const line = rawLine.split("#")[0].trim();
+      if (!line) continue;
+      buf += (buf ? " " : "") + line;
+      open +=
+        (line.match(/[[(]/g) ?? []).length -
+        (line.match(/[\])]/g) ?? []).length;
+      if (!line.endsWith("\\") && open <= 0 && !line.endsWith(",")) push();
+    }
+    push();
+    if (logical.length === 0) return false;
+    return logical.every((l) =>
+      /^(?:import\s+[\w.]+|from\s+\.*[\w.]*\s+import\s+\S|__all__\s*=)/.test(l),
+    );
+  }
+  const code = content
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^[ \t]*\/\/.*$/gm, "");
+  if (!/\bexport\b/.test(code)) return false;
+  EXPORT_FROM_RE.lastIndex = 0;
+  return code.replace(EXPORT_FROM_RE, "").trim() === "";
+}
+
+// Is any test file an importer of `file`, walking *through* barrels only?
+// Barrels can nest (db/*.ts → db/index.ts → db.ts), so recurse, but never
+// through a normal module — that would make every file in a tested repo
+// count as tested and kill the signal entirely.
+export function isTestedThroughBarrels(
+  graph: ImportGraph,
+  file: string,
+  seen = new Set<string>(),
+): boolean {
+  if (seen.has(file)) return false;
+  seen.add(file);
+  for (const dep of graph.dependents.get(file) ?? []) {
+    if (isTestFile(dep)) return true;
+    if (graph.barrels.has(dep) && isTestedThroughBarrels(graph, dep, seen))
+      return true;
+  }
+  return false;
+}

package/src/analyze/diagnose.ts

@@ -0,0 +1,113 @@
+// src/analyze/diagnose.ts — `diagnose()`: hub-untested / orphan / cycle /
+// changed-untested findings over a built graph.
+
+import { isTestedThroughBarrels, isTestFile } from "./criteria.js";
+import { isEntryPoint } from "./discover.js";
+import type { Finding, FindingKind, ImportGraph } from "./types.js";
+
+function findCycles(graph: ImportGraph): string[][] {
+  const cycles: string[][] = [];
+  const seen = new Set<string>();
+  const color = new Map<string, number>(); // 1 = on stack, 2 = done
+  const stack: string[] = [];
+
+  function visit(node: string): void {
+    if (cycles.length >= 20) return; // bound work, display caps at 5 anyway
+    color.set(node, 1);
+    stack.push(node);
+    for (const next of graph.deps.get(node) ?? []) {
+      if (cycles.length >= 20) break;
+      const c = color.get(next) ?? 0;
+      if (c === 1) {
+        const cycle = stack.slice(stack.indexOf(next));
+        const key = [...cycle].sort().join("|");
+        if (!seen.has(key)) {
+          seen.add(key);
+          cycles.push(cycle);
+        }
+      } else if (c === 0) {
+        visit(next);
+      }
+    }
+    stack.pop();
+    color.set(node, 2);
+  }
+
+  for (const f of graph.files) {
+    if ((color.get(f) ?? 0) === 0) visit(f);
+  }
+  return cycles;
+}
+
+const KIND_RANK: Record<FindingKind, number> = {
+  cycle: 0,
+  "hub-untested": 1,
+  "changed-untested": 2,
+  orphan: 3,
+};
+
+export function diagnose(
+  graph: ImportGraph,
+  changed: string[] = [],
+): Finding[] {
+  const findings: Finding[] = [];
+  const filesSet = new Set(graph.files);
+
+  for (const cycle of findCycles(graph)) {
+    findings.push({
+      kind: "cycle",
+      file: cycle.join(" ↔ "),
+      detail: "circular imports — refactoring either side breaks the other",
+      evidence: [...cycle, cycle[0]].join(" → "),
+    });
+  }
+
+  const hubUntested: { file: string; n: number }[] = [];
+  for (const f of graph.files) {
+    const deps = graph.dependents.get(f) ?? new Set<string>();
+    if (deps.size === 0) {
+      if (!isEntryPoint(f) && !isTestFile(f)) {
+        findings.push({
+          kind: "orphan",
+          file: f,
+          detail:
+            "no one imports it and it is not an entry point — dead code candidate",
+          evidence: "0 dependents",
+        });
+      }
+    } else if (deps.size >= 3 && !isTestedThroughBarrels(graph, f)) {
+      hubUntested.push({ file: f, n: deps.size });
+    }
+  }
+  hubUntested.sort((a, b) => b.n - a.n || (a.file < b.file ? -1 : 1));
+  for (const { file, n } of hubUntested) {
+    const deps = [...(graph.dependents.get(file) ?? [])].sort();
+    const shown = deps.slice(0, 3).join(", ");
+    const rest = n > 3 ? ` … (+${n - 3})` : "";
+    findings.push({
+      kind: "hub-untested",
+      file,
+      detail: `${n} files depend on it; no test imports it — edit here and nothing catches the break`,
+      evidence: `dependents: ${shown}${rest}`,
+    });
+  }
+
+  for (const c of changed) {
+    if (!filesSet.has(c)) continue;
+    const deps = graph.dependents.get(c) ?? new Set<string>();
+    if (!isTestedThroughBarrels(graph, c)) {
+      findings.push({
+        kind: "changed-untested",
+        file: c,
+        detail: `recently changed but no test depends on it (${deps.size} dependent) — nothing catches it if it breaks`,
+        evidence:
+          deps.size > 0
+            ? `dependents: ${[...deps].sort().join(", ")}`
+            : "0 dependents",
+      });
+    }
+  }
+
+  findings.sort((a, b) => KIND_RANK[a.kind] - KIND_RANK[b.kind]);
+  return findings;
+}