@maxgfr/codeindex 2.7.0

package/src/rules.ts

@@ -0,0 +1,249 @@
+// Architecture rules (issue #4): dependency-cruiser-style assertions validated
+// against the built Graph — a deterministic CI gate with zero dependencies.
+// Two rule shapes:
+//   forbidden edge  {name, from, to, kind?, severity?, comment?} — no resolved
+//     file edge may go from a path matching `from` to one matching `to`
+//     (globs use src/glob.ts compileGlobs semantics; `kind` narrows to specific
+//     edge kinds, default all);
+//   builtin         {name, builtin: "cycles" | "orphans", severity?, comment?}
+//     cycles  — module-level import cycles (each strongly-connected component
+//               is reported once, as a canonical shortest cycle from its
+//               lexicographically smallest module);
+//     orphans — code files with no resolved in/out edges, excluding
+//               entrypoint-looking basenames (index/main/cli/…).
+// Violations are sorted deterministically (rule, from, to, kind) so two runs on
+// the same graph are byte-identical.
+import type { EdgeKind, Graph } from "./types.js";
+import { compileGlobs } from "./glob.js";
+import { byStr } from "./sort.js";
+
+export type RuleSeverity = "error" | "warn";
+
+export interface ForbiddenEdgeRule {
+  name: string;
+  from: string | string[]; // glob(s) over the source file's repo-relative path
+  to: string | string[]; // glob(s) over the target file's repo-relative path
+  kind?: EdgeKind[]; // restrict to these edge kinds (default: all)
+  severity?: RuleSeverity; // default "error"
+  comment?: string; // rationale, echoed on each violation
+}
+
+export interface BuiltinRule {
+  name: string;
+  builtin: "cycles" | "orphans";
+  severity?: RuleSeverity;
+  comment?: string;
+}
+
+export type ArchRule = ForbiddenEdgeRule | BuiltinRule;
+
+export interface RuleViolation {
+  rule: string;
+  from: string;
+  to: string; // for a cycle: the full path, "a -> b -> a"
+  kind: EdgeKind | "cycle" | "orphan";
+  severity: RuleSeverity;
+  comment?: string;
+}
+
+const EDGE_KINDS = new Set<string>(["contains", "doc-link", "import", "call", "use", "mention"]);
+const SEVERITIES = new Set<string>(["error", "warn"]);
+const BUILTINS = new Set<string>(["cycles", "orphans"]);
+
+// A basename that looks like an entrypoint — excluded from the orphans check,
+// because nothing is EXPECTED to import a main/cli/server entry.
+const ENTRYPOINT_STEMS = new Set([
+  "index",
+  "main",
+  "app",
+  "application",
+  "cli",
+  "server",
+  "entry",
+  "entrypoint",
+  "setup",
+  "conftest",
+  "__init__",
+  "__main__",
+  "mod",
+  "lib",
+]);
+
+function isEntrypointLike(rel: string): boolean {
+  const base = rel.split("/").pop()!;
+  const stem = base.split(".")[0]!.toLowerCase();
+  return ENTRYPOINT_STEMS.has(stem);
+}
+
+function toList(v: string | string[]): string[] {
+  return Array.isArray(v) ? v : [v];
+}
+
+// Validate an untrusted rules payload (CLI --config file, MCP inline JSON) into
+// a typed rules array. Accepts either a bare array or a `{ rules: [...] }`
+// wrapper. Throws a descriptive error on the first malformed entry.
+export function parseRules(input: unknown): ArchRule[] {
+  const raw = Array.isArray(input) ? input : (input as { rules?: unknown } | null)?.rules;
+  if (!Array.isArray(raw)) throw new Error("rules config must be an array (or an object with a `rules` array)");
+  return raw.map((entry, i) => {
+    const at = `rules[${i}]`;
+    if (typeof entry !== "object" || entry === null) throw new Error(`${at}: must be an object`);
+    const r = entry as Record<string, unknown>;
+    if (typeof r.name !== "string" || !r.name) throw new Error(`${at}: \`name\` (non-empty string) is required`);
+    if (r.severity !== undefined && !SEVERITIES.has(r.severity as string))
+      throw new Error(`${at} (${r.name}): \`severity\` must be "error" or "warn"`);
+    if (r.comment !== undefined && typeof r.comment !== "string")
+      throw new Error(`${at} (${r.name}): \`comment\` must be a string`);
+    if (r.builtin !== undefined) {
+      if (!BUILTINS.has(r.builtin as string))
+        throw new Error(`${at} (${r.name}): \`builtin\` must be "cycles" or "orphans"`);
+      return { name: r.name, builtin: r.builtin, severity: r.severity, comment: r.comment } as BuiltinRule;
+    }
+    const glob = (field: "from" | "to"): string | string[] => {
+      const v = r[field];
+      const ok = typeof v === "string" ? v.length > 0 : Array.isArray(v) && v.length > 0 && v.every((g) => typeof g === "string" && g);
+      if (!ok) throw new Error(`${at} (${r.name}): \`${field}\` must be a glob or a non-empty array of globs`);
+      return v as string | string[];
+    };
+    const from = glob("from");
+    const to = glob("to");
+    if (r.kind !== undefined) {
+      const ok = Array.isArray(r.kind) && r.kind.every((k) => EDGE_KINDS.has(k as string));
+      if (!ok) throw new Error(`${at} (${r.name}): \`kind\` must be an array of edge kinds (${[...EDGE_KINDS].join(", ")})`);
+    }
+    return { name: r.name, from, to, kind: r.kind, severity: r.severity, comment: r.comment } as ForbiddenEdgeRule;
+  });
+}
+
+// Module-level import cycles. One violation per strongly-connected component
+// (iterative Tarjan over the import-kind module edges), rendered as a canonical
+// cycle: BFS from the SCC's smallest module along sorted adjacency, closing
+// through the (nearest, then smallest) member with an edge back to the start.
+function findImportCycles(graph: Graph): { start: string; path: string[] }[] {
+  const adj = new Map<string, string[]>();
+  for (const e of graph.moduleEdges) {
+    if (e.kind !== "import") continue;
+    let list = adj.get(e.from);
+    if (!list) adj.set(e.from, (list = []));
+    list.push(e.to);
+  }
+  for (const list of adj.values()) list.sort(byStr);
+  const nodes = [...adj.keys()].sort(byStr);
+
+  // Iterative Tarjan SCC.
+  const indexOf = new Map<string, number>();
+  const low = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const sccs: string[][] = [];
+  let counter = 0;
+  for (const root of nodes) {
+    if (indexOf.has(root)) continue;
+    const work: { node: string; next: number }[] = [{ node: root, next: 0 }];
+    while (work.length) {
+      const frame = work[work.length - 1]!;
+      const v = frame.node;
+      if (frame.next === 0) {
+        indexOf.set(v, counter);
+        low.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.add(v);
+      }
+      const targets = adj.get(v) ?? [];
+      if (frame.next < targets.length) {
+        const w = targets[frame.next]!;
+        frame.next++;
+        if (!indexOf.has(w)) work.push({ node: w, next: 0 });
+        else if (onStack.has(w)) low.set(v, Math.min(low.get(v)!, indexOf.get(w)!));
+      } else {
+        if (low.get(v) === indexOf.get(v)) {
+          const scc: string[] = [];
+          for (;;) {
+            const w = stack.pop()!;
+            onStack.delete(w);
+            scc.push(w);
+            if (w === v) break;
+          }
+          if (scc.length > 1) sccs.push(scc);
+        }
+        work.pop();
+        const parent = work[work.length - 1];
+        if (parent) low.set(parent.node, Math.min(low.get(parent.node)!, low.get(v)!));
+      }
+    }
+  }
+
+  const cycles: { start: string; path: string[] }[] = [];
+  for (const scc of sccs) {
+    const members = new Set(scc);
+    const start = [...scc].sort(byStr)[0]!;
+    // BFS within the SCC from `start`; parent links reconstruct the path.
+    const parent = new Map<string, string | null>([[start, null]]);
+    const order: string[] = [start];
+    for (let i = 0; i < order.length; i++) {
+      const v = order[i]!;
+      for (const w of adj.get(v) ?? []) {
+        if (!members.has(w) || parent.has(w)) continue;
+        parent.set(w, v);
+        order.push(w);
+      }
+    }
+    // The closing hop: the BFS-nearest (then smallest) member with an edge back
+    // to start. BFS `order` is deterministic, so `closer` is too.
+    const closer = order.find((v) => (adj.get(v) ?? []).includes(start) && v !== start) ??
+      // Degenerate (shouldn't happen in an SCC): fall back to start itself.
+      start;
+    const path: string[] = [];
+    for (let v: string | null = closer; v !== null; v = parent.get(v) ?? null) path.unshift(v);
+    path.push(start);
+    cycles.push({ start, path });
+  }
+  return cycles;
+}
+
+// Validate `rules` against the built graph. Pure and deterministic: violations
+// are fully sorted; severity defaults to "error"; a rule's `comment` (when set)
+// is echoed onto each of its violations.
+export function checkRules(graph: Graph, rules: ArchRule[]): RuleViolation[] {
+  const out: RuleViolation[] = [];
+  const emit = (rule: ArchRule, v: Omit<RuleViolation, "rule" | "severity" | "comment">): void => {
+    out.push({
+      rule: rule.name,
+      ...v,
+      severity: rule.severity ?? "error",
+      ...(rule.comment !== undefined ? { comment: rule.comment } : {}),
+    });
+  };
+  const fileSet = new Set(graph.files.map((f) => f.rel));
+
+  for (const rule of rules) {
+    if ("builtin" in rule) {
+      if (rule.builtin === "cycles") {
+        for (const c of findImportCycles(graph)) {
+          emit(rule, { from: c.start, to: c.path.join(" -> "), kind: "cycle" });
+        }
+      } else {
+        for (const f of graph.files) {
+          if (f.fileKind !== "code" || f.degIn !== 0 || f.degOut !== 0) continue;
+          if (isEntrypointLike(f.rel)) continue;
+          emit(rule, { from: f.rel, to: f.rel, kind: "orphan" });
+        }
+      }
+      continue;
+    }
+    const fromMatch = compileGlobs(toList(rule.from));
+    const toMatch = compileGlobs(toList(rule.to));
+    if (!fromMatch || !toMatch) continue; // empty glob list — matches nothing
+    const kinds = rule.kind?.length ? new Set<string>(rule.kind) : null;
+    for (const e of graph.fileEdges) {
+      if (e.dangling || !fileSet.has(e.to)) continue;
+      if (kinds && !kinds.has(e.kind)) continue;
+      if (!fromMatch(e.from) || !toMatch(e.to)) continue;
+      emit(rule, { from: e.from, to: e.to, kind: e.kind });
+    }
+  }
+
+  out.sort((a, b) => byStr(a.rule, b.rule) || byStr(a.from, b.from) || byStr(a.to, b.to) || byStr(a.kind, b.kind));
+  return out;
+}

package/src/scan.ts

@@ -0,0 +1,172 @@
+import { basename } from "node:path";
+import type { FileRecord } from "./types.js";
+import { walk, readText } from "./walk.js";
+import { headCommit } from "./git.js";
+import { sha1 } from "./hash.js";
+import { classify, MARKDOWN_EXT } from "./classify.js";
+import { extToLang } from "./lang/registry.js";
+import { compileGlobs } from "./glob.js";
+import { byKey } from "./sort.js";
+import { extractMarkdown } from "./extract/markdown.js";
+import { extractCode } from "./extract/code.js";
+
+export interface RepoScan {
+  root: string;
+  commit?: string;
+  files: FileRecord[];
+  languages: Record<string, number>;
+  // Raw content of doc files, kept so the graph's mention pass does not re-read
+  // them from disk (they were already read here). Docs only — bounding memory to
+  // prose, never the whole source tree.
+  docText: Map<string, string>;
+  // rel → last-modified ms for every kept file, so build.ts can persist the
+  // (size,mtime) fastpath key into cache.json for the next build.
+  mtimes: Map<string, number>;
+  capped: boolean; // the walk hit --max-files and the index is partial
+  // Files the walk saw and rejected (size/lockfile/binary/minified/gitignore
+  // rules — see WalkResult.excluded). Surfaced so a consumer can report how
+  // much of the tree was filtered out of the index.
+  excluded: number;
+}
+
+export interface ScanOptions {
+  include?: string[];
+  exclude?: string[];
+  // Sugar for include: ["<scope>/**"] — restrict the scan to one directory.
+  scope?: string;
+  // Honor .gitignore files (default true — see WalkOptions.gitignore).
+  gitignore?: boolean;
+  maxBytes?: number;
+  maxFiles?: number;
+  out?: string; // absolute output dir to exclude from the scan (self-index guard)
+  // Previous build's extraction cache (rel → {hash, record, size?, mtimeMs?}). A
+  // file whose (size,mtime) key matches skips read+hash entirely (the stat
+  // fastpath); one whose content hash is unchanged reuses its record and skips
+  // re-extraction.
+  cache?: Map<string, { hash: string; record: FileRecord; size?: number; mtimeMs?: number }>;
+  // Disable the stat fastpath: read and re-hash every file (see BuildOptions).
+  fullHash?: boolean;
+}
+
+function countLines(s: string): number {
+  if (!s) return 0;
+  let n = 1;
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+// Walk the repo once and turn every in-scope file into a FileRecord. Pure file
+// I/O + deterministic extraction — never reads the repo into the model.
+export function scanRepo(root: string, opts: ScanOptions = {}): RepoScan {
+  const scoped = opts.scope ? [...(opts.include ?? []), `${opts.scope.replace(/\/+$/, "")}/**`] : opts.include;
+  const include = compileGlobs(scoped);
+  const exclude = compileGlobs(opts.exclude);
+  const { files: walked, capped, excluded } = walk(root, {
+    maxFileBytes: opts.maxBytes,
+    maxFiles: opts.maxFiles,
+    gitignore: opts.gitignore,
+  });
+  // Never index our own output (e.g. a committed `docs/ultraindex/`), or builds
+  // would describe the encyclopedia instead of the code.
+  const outPrefix = opts.out ? opts.out.replace(/\/+$/, "") + "/" : null;
+
+  const files: FileRecord[] = [];
+  const languages: Record<string, number> = {};
+  const docText = new Map<string, string>();
+  const mtimes = new Map<string, number>();
+
+  for (const f of walked) {
+    if (outPrefix && (f.abs === opts.out || f.abs.startsWith(outPrefix))) continue;
+    if (include && !include(f.rel)) continue;
+    if (exclude && exclude(f.rel)) continue;
+
+    const kind = classify(f.rel, f.ext);
+    const lang = extToLang(f.ext);
+    languages[lang] = (languages[lang] ?? 0) + 1;
+    mtimes.set(f.rel, f.mtimeMs); // persist the fastpath key for the next build
+
+    const cached = opts.cache?.get(f.rel);
+
+    // Stat fastpath: a NON-DOC file whose size AND mtime both match its cache
+    // entry is treated as unchanged and reuses its record WITHOUT a read or hash.
+    // Docs are EXEMPT — the graph's mention pass needs their raw content (docText)
+    // every build, so a doc is always read regardless. --full-hash disables the
+    // fastpath. The (size,mtime) pair is the heuristic here (not the exact content
+    // hash below): a real editor bumps mtime on every save, and --full-hash /
+    // --no-cache are the escape hatches for the astronomically-unlikely edit that
+    // preserves both.
+    if (
+      kind !== "doc" &&
+      !opts.fullHash &&
+      cached &&
+      cached.size !== undefined &&
+      cached.mtimeMs !== undefined &&
+      cached.size === f.size &&
+      cached.mtimeMs === f.mtimeMs
+    ) {
+      files.push(cached.record);
+      continue;
+    }
+
+    // Read + hash (the staleness oracle stays exact); only EXTRACTION is cached. A
+    // hash hit reuses the previous record — content is byte-identical, so every
+    // derived field is too. classify()/extToLang() depend only on the path, so
+    // kind/lang are stable across the hit.
+    const content = readText(f.abs);
+    const hash = sha1(content);
+    if (cached && cached.hash === hash) {
+      files.push(cached.record);
+      if (kind === "doc" && content) docText.set(f.rel, content);
+      continue;
+    }
+
+    const record: FileRecord = {
+      rel: f.rel,
+      ext: f.ext,
+      size: f.size,
+      lines: countLines(content),
+      hash,
+      kind,
+      lang,
+      headings: [],
+      symbols: [],
+      refs: [],
+    };
+
+    if (content) {
+      if (kind === "doc" && MARKDOWN_EXT.has(f.ext)) {
+        const md = extractMarkdown(content);
+        record.title = md.title ?? basename(f.rel);
+        record.summary = md.summary;
+        record.headings = md.headings;
+        record.refs = md.refs;
+      } else if (kind === "doc") {
+        // Non-markdown prose (.rst/.txt): title from basename, no link graph.
+        record.title = basename(f.rel);
+      } else if (kind === "code") {
+        const code = extractCode(f.rel, f.ext, content);
+        record.title = basename(f.rel);
+        record.summary = code.summary;
+        record.symbols = code.symbols;
+        record.refs = code.refs;
+        record.pkg = code.pkg;
+        record.idents = code.idents;
+        record.calls = code.calls;
+        record.importedNames = code.importedNames;
+      } else {
+        record.title = basename(f.rel);
+      }
+    } else {
+      record.title = basename(f.rel);
+    }
+
+    // Retain doc content for the graph's mention pass (docs only) so it is read
+    // once here, not a second time from disk.
+    if (kind === "doc" && content) docText.set(f.rel, content);
+
+    files.push(record);
+  }
+
+  files.sort(byKey((f) => f.rel));
+  return { root, commit: headCommit(root), files, languages, docText, mtimes, capped, excluded };
+}

package/src/sort.ts

@@ -0,0 +1,12 @@
+// Locale-INDEPENDENT string comparator (UTF-16 code-unit order). Used for every
+// sort that feeds the on-disk artifact, so two builds on different machines /
+// locales produce byte-identical output. `localeCompare` must NOT be used for
+// artifact ordering — its result varies with the host's ICU locale.
+export function byStr(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// Sort by a string key, stably and locale-independently.
+export function byKey<T>(keyOf: (x: T) => string): (a: T, b: T) => number {
+  return (a, b) => byStr(keyOf(a), keyOf(b));
+}

package/src/surprise.ts

@@ -0,0 +1,58 @@
+import type { Graph, SurpriseEdge } from "./types.js";
+import { byStr } from "./sort.js";
+
+// Surprising cross-community coupling: a dependency edge that is one of at most
+// two links between two otherwise-separate subsystems. These are the places
+// where the architecture leaks — an agent reviewing a change touching one
+// deserves a nudge. Deliberately conservative: doc-links/mentions crossing
+// communities are normal, and everyone importing shared foundations (tier 0)
+// across communities is expected.
+export const SURPRISE_CAP = 24;
+const MAX_PAIR_EDGES = 2;
+
+const DEP_KINDS = new Set(["import", "call", "use"]);
+
+// One O(E) pass over the module edges. Deterministic: candidates keep the
+// stored edge order until the final (pairEdges asc, from, to) sort.
+export function computeSurprises(graph: Graph): SurpriseEdge[] {
+  const commOf = new Map<string, number>();
+  const tierOf = new Map<string, number>();
+  for (const m of graph.modules) {
+    if (m.community !== undefined) commOf.set(m.slug, m.community);
+    tierOf.set(m.slug, m.tier);
+  }
+
+  const pairCount = new Map<string, number>();
+  const pairKey = (a: number, b: number): string => (a < b ? `${a}:${b}` : `${b}:${a}`);
+  const candidates: { edge: Graph["moduleEdges"][number]; comms: [number, number] }[] = [];
+  for (const e of graph.moduleEdges) {
+    if (e.dangling) continue;
+    const ca = commOf.get(e.from);
+    const cb = commOf.get(e.to);
+    if (ca === undefined || cb === undefined || ca === cb) continue;
+    pairCount.set(pairKey(ca, cb), (pairCount.get(pairKey(ca, cb)) ?? 0) + 1);
+    if (!DEP_KINDS.has(e.kind)) continue;
+    if (tierOf.get(e.to) === 0) continue;
+    candidates.push({ edge: e, comms: [ca, cb] });
+  }
+
+  return candidates
+    .filter((c) => pairCount.get(pairKey(c.comms[0], c.comms[1]))! <= MAX_PAIR_EDGES)
+    .map((c) => ({
+      from: c.edge.from,
+      to: c.edge.to,
+      kind: c.edge.kind,
+      weight: c.edge.weight,
+      communities: c.comms,
+      pairEdges: pairCount.get(pairKey(c.comms[0], c.comms[1]))!,
+    }))
+    .sort((a, b) => a.pairEdges - b.pairEdges || byStr(a.from, b.from) || byStr(a.to, b.to))
+    .slice(0, SURPRISE_CAP);
+}
+
+// Is the directed module edge from→to flagged surprising? Reads the stored
+// build-time list when present, recomputes otherwise.
+export function isSurprising(graph: Graph, from: string, to: string): boolean {
+  const list = graph.surprises ?? computeSurprises(graph);
+  return list.some((s) => s.from === from && s.to === to);
+}

package/src/tests-map.ts

@@ -0,0 +1,105 @@
+import type { Graph, ModuleNode } from "./types.js";
+import { isTestFile } from "./modules.js";
+import { byStr } from "./sort.js";
+
+// tests→code mapping, derived from the existing graph — NO new edge kind. The
+// evidence is already there: a test file with a resolved import/call/use edge
+// into a source file covers it (the same "depends on" kind set `impact` walks).
+// Classifying test FILES and projecting the dependency edges through that
+// classification keeps degree, Louvain, and the kind ranking untouched.
+
+// Test-file detection by basename, per language convention. JS/TS reuses the
+// tier logic's TEST_FILE regex via isTestFile; the rest are the conventional
+// names: test_*.py / *_test.py, *_test.go, *Test(s).java|kt / *IT.java,
+// *_spec.rb / *_test.rb, *Test.php, *Test(s).cs, *_test.exs.
+const BASENAME_PATTERNS = [
+  /^test_.*\.py$/i,
+  /_test\.py$/i,
+  /_test\.go$/,
+  /(Test|Tests|IT)\.java$/,
+  /(Test|Tests)\.kt$/,
+  /_spec\.rb$/,
+  /_test\.rb$/,
+  /Test\.php$/,
+  /(Test|Tests)\.cs$/,
+  /_test\.exs$/,
+];
+
+// Directory rule: anything under a dedicated test dir is test material. This is
+// deliberately NARROWER than the tier logic's TIER2_ANY — examples, docs,
+// fixtures and benchmarks are tail, but they are not tests.
+const TEST_DIR = /(^|\/)(tests?|__tests?__|spec|specs|e2e)(\/|$)/i;
+
+// Is this repo-relative path a test file? Callers filter to code files; this
+// only judges the path.
+export function isTestPath(rel: string): boolean {
+  if (TEST_DIR.test(rel)) return true;
+  if (isTestFile(rel)) return true;
+  const base = rel.split("/").pop()!;
+  return BASENAME_PATTERNS.some((p) => p.test(base));
+}
+
+export interface TestMap {
+  testFiles: Set<string>; // rels of code files classified as tests
+  testedByFile: Map<string, string[]>; // source rel → sorted covering test rels
+  testedByModule: Map<string, string[]>; // module slug → sorted covering test rels
+}
+
+// Project the graph's dependency edges through the test classification. A
+// test→test edge (helpers, shared setup) is not coverage; neither is a doc-link
+// or mention, nor anything dangling. O(F + E), fully deterministic.
+export function computeTestMap(graph: Graph): TestMap {
+  const testFiles = new Set<string>();
+  const moduleOf = new Map<string, string>();
+  for (const f of graph.files) {
+    moduleOf.set(f.rel, f.module);
+    if (f.fileKind === "code" && isTestPath(f.rel)) testFiles.add(f.rel);
+  }
+
+  const byFile = new Map<string, Set<string>>();
+  const byModule = new Map<string, Set<string>>();
+  for (const e of graph.fileEdges) {
+    if (e.dangling) continue;
+    if (e.kind !== "import" && e.kind !== "use" && e.kind !== "call") continue;
+    if (!testFiles.has(e.from) || testFiles.has(e.to)) continue;
+    let set = byFile.get(e.to);
+    if (!set) byFile.set(e.to, (set = new Set()));
+    set.add(e.from);
+    const slug = moduleOf.get(e.to);
+    if (slug !== undefined) {
+      let mset = byModule.get(slug);
+      if (!mset) byModule.set(slug, (mset = new Set()));
+      mset.add(e.from);
+    }
+  }
+
+  const sortSets = (m: Map<string, Set<string>>): Map<string, string[]> => {
+    const out = new Map<string, string[]>();
+    for (const key of [...m.keys()].sort(byStr)) out.set(key, [...m.get(key)!].sort(byStr));
+    return out;
+  };
+  return { testFiles, testedByFile: sortSets(byFile), testedByModule: sortSets(byModule) };
+}
+
+// Covering tests for one module: the stored build-time field when present,
+// recomputed from the graph otherwise (older graphs, hand-built test literals).
+export function testsForModule(graph: Graph, slug: string): string[] {
+  const m = graph.modules.find((x) => x.slug === slug);
+  if (m?.testedBy) return m.testedBy;
+  return computeTestMap(graph).testedByModule.get(slug) ?? [];
+}
+
+// Modules that SHOULD have tests but don't: tier ≤ 1, at least one non-test
+// code member, declared symbols, and no covering test. Doc-only and tail
+// modules are out of scope by construction.
+export function untestedModules(graph: Graph): ModuleNode[] {
+  const tm = computeTestMap(graph);
+  const codeMembers = new Map<string, number>();
+  for (const f of graph.files) {
+    if (f.fileKind !== "code" || tm.testFiles.has(f.rel)) continue;
+    codeMembers.set(f.module, (codeMembers.get(f.module) ?? 0) + 1);
+  }
+  return graph.modules.filter(
+    (m) => m.tier <= 1 && m.symbols > 0 && (codeMembers.get(m.slug) ?? 0) > 0 && !tm.testedByModule.has(m.slug),
+  );
+}