weavatrix 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergii Ziborov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# Weavatrix
+
+**Code graph & blast-radius MCP server for AI coding agents.**
+
+Grep sees text. Weavatrix sees structure. It builds a dependency graph of any local repository —
+files, symbols, and the imports/calls/inheritance connecting them — and serves it to Claude Code,
+Codex, or any MCP client: change impact, transitive dependents, health audit, clone detection,
+coverage mapping. **23 tools. One server for every repo on your machine. Local-first: your code
+never leaves it.**
+
+- Website: [weavatrix.com](https://weavatrix.com)
+- Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
+- Status: **pre-release** — npm publish imminent; API may still shift before v0.1.
+
+## Why
+
+An AI agent editing code without the dependency graph is refactoring blind. Weavatrix gives it
+answers grep can't produce:
+
+- *"What breaks if I change this?"* → `change_impact` diffs your branch (staged, unstaged and
+  untracked included), maps the changed files and symbols onto the graph, and lists everything that
+  depends on them — with test coverage attached, so the **untested part of the blast radius** stands
+  out before you ship.
+- *"Who calls this function?"* → `get_dependents` walks reverse edges transitively: every caller,
+  importer and subclass that can feel the refactor, ranked by proximity × connectivity.
+- *"Did my refactor actually decouple anything?"* → `rebuild_graph` + `graph_diff` report the
+  structural delta: new module dependencies, broken or introduced import cycles, symbols that lost
+  their last caller.
+
+## Quick start
+
+Requires Node ≥ 18. One command:
+
+```sh
+# Claude Code — one user-level registration serves every repo on the machine:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>
+```
+
+Codex CLI:
+
+```sh
+codex mcp add weavatrix -- npx -y weavatrix <repoRoot>
+```
+
+```toml
+# or in ~/.codex/config.toml
+[mcp_servers.weavatrix]
+command = "npx"
+args = ["-y", "weavatrix", "C:/path/to/repo"]
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+```
+
+Or clone it:
+
+```sh
+git clone https://github.com/sergii-ziborov/weavatrix
+cd weavatrix && npm install
+claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.mjs <repoRoot>
+```
+
+- `<repoRoot>` — the repository to start with; the graph location is derived automatically
+  (`<repoRoot-parent>/weavatrix-graphs/<repoName>/graph.json`). Pass an explicit
+  `<graph.json> <repoRoot>` pair instead if you keep graphs elsewhere.
+
+No graph yet? Just ask the agent to call `rebuild_graph` (or `open_repo`) — it builds missing
+graphs itself. From then on, `open_repo` retargets the same running server at **any** other local
+repository; never register a second copy.
+
+An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install as
+`~/.claude/skills/weavatrix/SKILL.md`.
+
+## Tools
+
+**graph** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`,
+`shortest_path`, `get_community`, `list_communities`, `module_map`, `get_dependents`,
+`change_impact`, `graph_diff`, `list_known_repos`
+
+**search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
+symbol's actual code in one hop), `list_endpoints` (HTTP route inventory:
+Express/Fastify/Nest/Flask/FastAPI/Go mux …)
+
+**health** — `run_audit` (dead code, unused exports, missing/unused npm/Go/Python deps, import
+cycles, orphans, boundary rules, offline OSV vulnerabilities + typosquat + lockfile drift),
+`find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even after renames),
+`coverage_map` (existing coverage reports mapped onto the graph; untested hotspots ranked by
+connectivity — tests are never executed)
+
+**build** — `rebuild_graph` (reports the structural delta, keeps the prior state as
+`graph.prev.json`), `open_repo`
+
+**online** *(explicit opt-in — see Privacy)* — `refresh_advisories`, `sync_graph`
+
+Quality of life: graph tools self-report staleness vs the repo HEAD; ambiguous name lookups are
+disclosed instead of silently guessed; and the server **hot-reloads its own tool code** when the
+files under `src/mcp/` change — no reconnect needed.
+
+## Privacy: local-first, offline by design
+
+Graph queries, audits and clone scans run in-process against local files. Exactly two tools can
+touch the network, both in the `online` capability group and both inert until explicitly invoked:
+
+- `refresh_advisories` — queries [OSV.dev](https://osv.dev) with your lockfile's package
+  **names + versions** (that is what an OSV query is; never source code) and caches the advisories
+  in `~/.weavatrix/advisories.json`. `run_audit` then matches against that store fully offline.
+- `sync_graph` — pushes `graph.json` (file paths, symbol names, edges — never file contents) to an
+  endpoint **you** configure via `WEAVATRIX_SYNC_URL` / `WEAVATRIX_SYNC_TOKEN`. Off by default.
+
+Capability groups (`graph`, `search`, `source`, `health`, `build`, `online`) are selectable per
+registration via a fifth argument — a comma-separated list. Omit `online` from it and those tools
+don't exist for that client.
+
+## Languages
+
+JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · HTML · CSS — parsed with
+[web-tree-sitter](https://github.com/tree-sitter/tree-sitter) WASM grammars; no Python install, no
+native compilation.
+
+## On-disk layout
+
+Graphs are derived data and never live inside your repo: they go to a `weavatrix-graphs/` folder
+**next to** it (one folder per repo, holding `graph.json` + `graph.prev.json`).
+
+## Development
+
+```sh
+npm install
+npm test          # node --test — 224 tests
+```
+
+Design rule: **no source file exceeds 300 lines.** Larger concerns split into dotted-suffix modules
+behind a slim facade (`foo.js` re-exports `foo.parse.js`, `foo.report.js`, …); the MCP layer lives
+in `src/mcp/` (graph context, four tool modules, catalog + hot-reload loader) behind the thin stdio
+entry `src/mcp-server.mjs`.
+
+## Roadmap
+
+- **Hosted graph view** on [weavatrix.com](https://weavatrix.com) — sync with one tool call, share
+  the interactive map with your team
+- **Graph-anchored memory** — agent notes pinned to nodes/modules, staleness-tracked as the code
+  under them changes
+- **CI blast radius** — `change_impact` as a PR comment
+
+## License
+
+[MIT](LICENSE) © 2026 Sergii Ziborov

package/bin/weavatrix-mcp.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Weavatrix MCP stdio entry — thin launcher so npm/npx get a shebang'd bin
+// while the server itself stays a plain module. Positional args pass through:
+//   weavatrix-mcp <repoRoot> [caps]               — graph path derived automatically
+//   weavatrix-mcp <graph.json> <repoRoot> [caps]  — explicit graph file
+import('../src/mcp-server.mjs')

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "weavatrix",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
+  "author": "Sergii Ziborov <sergii@edgehawk.io>",
+  "license": "MIT",
+  "homepage": "https://weavatrix.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sergii-ziborov/weavatrix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sergii-ziborov/weavatrix/issues"
+  },
+  "mcpName": "io.github.sergii-ziborov/weavatrix",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "weavatrix-mcp": "bin/weavatrix-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-graph",
+    "impact-analysis",
+    "blast-radius",
+    "static-analysis",
+    "dead-code",
+    "dependency-graph",
+    "tree-sitter",
+    "claude",
+    "ai-agents"
+  ],
+  "dependencies": {
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.25.3"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: weavatrix
+description: Drive the weavatrix MCP — code graph, blast-radius (get_dependents/change_impact), health audit, duplicates, coverage, endpoints — over any local repo. Use when analyzing code structure, refactor risk, dead code, dependency health, or before opening a PR.
+---
+
+# weavatrix MCP
+
+Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. One running
+server handles ANY local repository via `open_repo` — never register a second weavatrix server for a
+sibling repo.
+
+## Step 0 — if the tools are missing
+
+Tools are named `mcp__weavatrix__…`. If none are available, ask the user to register the server
+(`claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>`; Codex:
+`codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
+
+## Ground rules
+
+- **Freshness**: every graph tool appends a staleness warning when the repo has commits newer than
+  the graph. Act on it: `rebuild_graph`.
+- **Ambiguity**: `get_node`/`get_neighbors`/`get_dependents` disclose `matched N nodes; using the
+  best-connected` — read that note before trusting the answer; pass an exact node id to pin it.
+- **Offline by design**: scans and graph queries run in-process against local files; coverage tools
+  read existing reports and never run tests. The ONLY network-touching tools live in the `online`
+  capability group and run solely when explicitly called: `refresh_advisories` (queries OSV.dev with
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes
+  graph.json to a user-configured endpoint; disabled until `WEAVATRIX_SYNC_URL` is set). Registering
+  the server with a caps list that omits `online` removes both.
+
+## Recipes
+
+- **Orient in an unfamiliar repo**: `open_repo` → `module_map` → `list_communities` → `god_nodes`.
+- **Refactor safety for one symbol**: `get_dependents` → `coverage_map` (low coverage × many
+  dependents ⇒ write tests first) → `read_source`.
+- **Pre-PR review of your current changes**: `change_impact` (auto merge-base; includes uncommitted
+  and untracked work, coverage attached, untested hotspots called out) → drill with `get_dependents`.
+- **Impact of a PR that is NOT checked out**: pass its changed-file list explicitly —
+  `change_impact files=[…]` — same blast-radius + coverage view, no checkout.
+- **Validate a refactor structurally**: edit → `rebuild_graph` — it reports the structural delta
+  (cycle broken? new module dependency introduced? symbols orphaned?); re-query later with
+  `graph_diff` (optionally scoped by `path`). The semantic complement to the textual git diff.
+- **Health sweep**: `run_audit` (filter by `category`/`min_severity`) → `find_duplicates` →
+  `coverage_map`.
+- **API inventory**: `list_endpoints`.
+- **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
+- **Another repo**: `list_known_repos` → `open_repo <path>` (builds the graph when missing — minutes
+  on large repos; `build:false` probes without building).
+
+## Troubleshooting
+
+- `Graph unavailable` → `open_repo` with a valid repo path.
+- `No coverage report` → run the repo's own tests with coverage (`vitest run --coverage`,
+  `jest --coverage`, `pytest --cov --cov-report=json`, `go test -coverprofile=coverage.out`),
+  then re-call.
+- `change_impact` says files are "not in the graph" → they're new/renamed; `rebuild_graph` and retry.

package/src/analysis/coverage-reports.js

@@ -0,0 +1,232 @@
+// graph-builder-coverage.js — coverage-report readers for the graph analysis. Parses Istanbul (summary/final),
+// lcov, Python coverage.json, and Go coverage.out into per-file line-hit maps, resolving report paths onto the
+// graph's known files. Split out of graph-builder-analysis.js (pure except for reading the repo's coverage files).
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+export function normRepoPath(value) {
+  return String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+export function dirOfRepoPath(value) {
+  const p = normRepoPath(value);
+  const i = p.lastIndexOf("/");
+  return i >= 0 ? p.slice(0, i) : "";
+}
+
+export function normalizeRepoParts(value) {
+  const out = [];
+  for (const part of normRepoPath(value).split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") out.pop();
+    else out.push(part);
+  }
+  return out.join("/");
+}
+
+function pct01(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return Math.max(0, Math.min(1, n > 1 ? n / 100 : n));
+}
+
+export function pctFromCounts(covered, total) {
+  const c = Number(covered);
+  const t = Number(total);
+  if (!Number.isFinite(c) || !Number.isFinite(t) || t <= 0) return null;
+  return Math.max(0, Math.min(1, c / t));
+}
+
+function resolveCoverageFile(rawPath, knownFiles, repoRoot) {
+  const known = (knownFiles || []).map(normalizeRepoParts).filter(Boolean);
+  const knownSet = new Set(known);
+  const candidates = [];
+  const add = (value) => {
+    const p = normalizeRepoParts(value);
+    if (p && !candidates.includes(p)) candidates.push(p);
+  };
+  const raw = String(rawPath || "").replace(/^file:\/\//i, "").replace(/[?#].*$/, "");
+  const normalizedRaw = normRepoPath(raw);
+  add(normalizedRaw);
+  add(normalizedRaw.replace(/^\.\//, ""));
+  if (repoRoot) {
+    try {
+      const rel = normRepoPath(relative(repoRoot, raw));
+      if (rel && !rel.startsWith("..")) add(rel);
+    } catch {
+      /* best effort */
+    }
+    const rootPrefix = `${normRepoPath(resolve(repoRoot)).toLowerCase()}/`;
+    const lowerRaw = normalizedRaw.toLowerCase();
+    if (lowerRaw.startsWith(rootPrefix)) add(normalizedRaw.slice(rootPrefix.length));
+  }
+  for (const candidate of candidates) if (knownSet.has(candidate)) return candidate;
+  const lower = normalizedRaw.toLowerCase();
+  const suffixHit = known
+    .slice()
+    .sort((a, b) => b.length - a.length)
+    .find((file) => lower.endsWith(`/${file.toLowerCase()}`) || lower === file.toLowerCase());
+  return suffixHit || candidates[0] || "";
+}
+
+function mergeCoverageEntry(map, rawPath, entry, knownFiles, repoRoot) {
+  const file = resolveCoverageFile(rawPath, knownFiles, repoRoot);
+  if (!file) return;
+  const current = map.get(file) || {};
+  map.set(file, {
+    pct: entry.pct != null ? entry.pct : current.pct ?? null,
+    total: entry.total != null ? entry.total : current.total ?? null,
+    covered: entry.covered != null ? entry.covered : current.covered ?? null,
+    lines: entry.lines || current.lines || null,
+    source: current.source && entry.source ? `${current.source}, ${entry.source}` : entry.source || current.source || ""
+  });
+}
+
+function addLineHit(lines, line, hit) {
+  const n = Math.max(1, Math.round(Number(line) || 0));
+  if (!n) return;
+  const current = lines.get(n);
+  lines.set(n, Math.max(Number(current) || 0, Number(hit) || 0));
+}
+
+function parseIstanbulSummary(map, filePath, knownFiles, repoRoot) {
+  const json = JSON.parse(readFileSync(filePath, "utf8"));
+  for (const [raw, value] of Object.entries(json || {})) {
+    if (raw === "total" || !value || typeof value !== "object") continue;
+    const lines = value.lines || value.statements || {};
+    mergeCoverageEntry(map, raw, {
+      pct: pct01(lines.pct),
+      total: Number.isFinite(Number(lines.total)) ? Number(lines.total) : null,
+      covered: Number.isFinite(Number(lines.covered)) ? Number(lines.covered) : null,
+      source: "coverage-summary.json"
+    }, knownFiles, repoRoot);
+  }
+}
+
+function parseIstanbulFinal(map, filePath, knownFiles, repoRoot) {
+  const json = JSON.parse(readFileSync(filePath, "utf8"));
+  for (const [raw, record] of Object.entries(json || {})) {
+    if (!record || typeof record !== "object") continue;
+    const statementMap = record.statementMap || {};
+    const hits = record.s || {};
+    const lines = new Map();
+    for (const [id, loc] of Object.entries(statementMap)) {
+      const hit = Number(hits[id]) || 0;
+      const start = Math.max(1, Math.round(Number(loc?.start?.line) || 0));
+      const end = Math.max(start, Math.round(Number(loc?.end?.line) || start));
+      for (let line = start; line <= end; line++) addLineHit(lines, line, hit);
+    }
+    const total = lines.size;
+    const covered = [...lines.values()].filter((hit) => Number(hit) > 0).length;
+    mergeCoverageEntry(map, record.path || raw, {
+      pct: pctFromCounts(covered, total),
+      total,
+      covered,
+      lines,
+      source: "coverage-final.json"
+    }, knownFiles, repoRoot);
+  }
+}
+
+function parseLcov(map, filePath, knownFiles, repoRoot) {
+  const flush = (record) => {
+    if (!record || !record.file) return;
+    const total = record.total ?? record.lines.size;
+    const covered = record.covered ?? [...record.lines.values()].filter((hit) => Number(hit) > 0).length;
+    mergeCoverageEntry(map, record.file, {
+      pct: pctFromCounts(covered, total),
+      total,
+      covered,
+      lines: record.lines,
+      source: "lcov.info"
+    }, knownFiles, repoRoot);
+  };
+  let current = null;
+  for (const rawLine of readFileSync(filePath, "utf8").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith("SF:")) {
+      flush(current);
+      current = { file: line.slice(3), lines: new Map(), total: null, covered: null };
+    } else if (current && line.startsWith("DA:")) {
+      const [lineNo, count] = line.slice(3).split(",");
+      addLineHit(current.lines, lineNo, count);
+    } else if (current && line.startsWith("LF:")) {
+      current.total = Number(line.slice(3)) || current.total;
+    } else if (current && line.startsWith("LH:")) {
+      current.covered = Number(line.slice(3)) || current.covered;
+    } else if (line === "end_of_record") {
+      flush(current);
+      current = null;
+    }
+  }
+  flush(current);
+}
+
+function parseCoveragePyJson(map, filePath, knownFiles, repoRoot) {
+  const json = JSON.parse(readFileSync(filePath, "utf8"));
+  for (const [raw, file] of Object.entries(json?.files || {})) {
+    const lines = new Map();
+    for (const line of file.executed_lines || []) addLineHit(lines, line, 1);
+    for (const line of file.missing_lines || []) if (!lines.has(Number(line))) addLineHit(lines, line, 0);
+    const summary = file.summary || {};
+    const total = Number(summary.num_statements) || lines.size;
+    const covered = Number(summary.covered_lines) || [...lines.values()].filter((hit) => Number(hit) > 0).length;
+    mergeCoverageEntry(map, raw, {
+      pct: pct01(summary.percent_covered ?? summary.percent_covered_display) ?? pctFromCounts(covered, total),
+      total,
+      covered,
+      lines,
+      source: "coverage.json"
+    }, knownFiles, repoRoot);
+  }
+}
+
+function parseGoCoverage(map, filePath, knownFiles, repoRoot) {
+  const byFile = new Map();
+  for (const rawLine of readFileSync(filePath, "utf8").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("mode:")) continue;
+    const m = line.match(/^(.+):(\d+)\.\d+,(\d+)\.\d+\s+\d+\s+(\d+)$/);
+    if (!m) continue;
+    const record = byFile.get(m[1]) || { lines: new Map() };
+    const start = Math.max(1, Number(m[2]) || 1);
+    const end = Math.max(start, Number(m[3]) || start);
+    for (let n = start; n <= end; n++) addLineHit(record.lines, n, Number(m[4]) || 0);
+    byFile.set(m[1], record);
+  }
+  for (const [raw, record] of byFile) {
+    const total = record.lines.size;
+    const covered = [...record.lines.values()].filter((hit) => Number(hit) > 0).length;
+    mergeCoverageEntry(map, raw, {
+      pct: pctFromCounts(covered, total),
+      total,
+      covered,
+      lines: record.lines,
+      source: "coverage.out"
+    }, knownFiles, repoRoot);
+  }
+}
+
+export function readCoverageForRepo(repoRoot, knownFiles) {
+  const out = new Map();
+  if (!repoRoot) return out;
+  const candidates = [
+    [join(repoRoot, "coverage", "coverage-summary.json"), parseIstanbulSummary],
+    [join(repoRoot, "coverage", "coverage-final.json"), parseIstanbulFinal],
+    [join(repoRoot, "coverage", "lcov.info"), parseLcov],
+    [join(repoRoot, "lcov.info"), parseLcov],
+    [join(repoRoot, "coverage", "coverage.json"), parseCoveragePyJson],
+    [join(repoRoot, "coverage.json"), parseCoveragePyJson],
+    [join(repoRoot, "coverage.out"), parseGoCoverage],
+    [join(repoRoot, "cover.out"), parseGoCoverage]
+  ];
+  for (const [path, parser] of candidates) {
+    if (!existsSync(path)) continue;
+    try {
+      parser(out, path, knownFiles, repoRoot);
+    } catch {
+      /* malformed/foreign coverage report: ignore */
+    }
+  }
+  return out;
+}

package/src/analysis/dead-check.js

@@ -0,0 +1,136 @@
+// Portable, language-agnostic DEAD-code checker. A symbol is DEAD when it has NO inbound graph edge (nothing
+// calls/imports/references/inherits it) AND its bare name appears NOWHERE in the repo outside its own file.
+// A file is DEAD when nothing imports it, it isn't an entry point, and all its symbols are dead.
+//
+// Pure core `computeDead(graph, sources)` (sources = Map<fileRel, text>) is fully testable with no filesystem.
+// `analyzeDeadCode(graph, repoRoot)` is the thin fs wrapper. Works on ANY graph-builder-schema graph (built-in OR
+// graph-builder) — it only needs {nodes, links} + the source text. See [[graph-builder-internalization]].
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const IDENT_RE = /[A-Za-z_$][\w$]*/g;
+const bareName = (label) => String(label || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
+// entry surfaces are never dead even with no inbound edge (framework/CLI/HTTP enter them externally).
+// Exported for internal-audit.js (reachability entry set) — keep the two in lockstep.
+export const ENTRY_FILE = /(^|[\\/])(index|main|app|server|cli|cmd|bootstrap|entry|run|__main__|manage|wsgi|asgi|setup|conftest)\.[a-z0-9]+$|(^|[\\/])(bin|cmd)[\\/]|(^|[\\/])main\.go$/i;
+const TEST_FILE = /(^|[\\/])[^\\/]*[._-](test|spec)\.[a-z0-9]+$|(^|[\\/])(test|tests|__tests__|spec)[\\/]/i;
+
+export function computeDead(graph, sources) {
+  const nodes = graph.nodes || [], links = graph.links || [];
+  const ep = (v) => (v && typeof v === "object" ? v.id : v);
+  const inbound = new Set();
+  for (const l of links) if (l.relation !== "contains") inbound.add(ep(l.target));
+
+  // whole-repo identifier frequency: a symbol whose name appears MORE than once total (its definition + at least
+  // one use, same-file OR cross-file) is referenced. Errs toward "alive" (common-named symbols never flagged).
+  const globalFreq = new Map();
+  for (const [, text] of sources) for (const m of String(text || "").matchAll(IDENT_RE)) { const n = m[0]; globalFreq.set(n, (globalFreq.get(n) || 0) + 1); }
+
+  const symById = new Map();
+  const symsByFile = new Map();
+  for (const n of nodes) {
+    if (!String(n.id).includes("#")) continue;
+    symById.set(n.id, n);
+    (symsByFile.get(n.source_file) || symsByFile.set(n.source_file, []).get(n.source_file)).push(n);
+  }
+
+  // decorated defs (@app.route/@app.event/@pytest.fixture…) are entered by the framework: trust the
+  // builder's flag when present, else walk the source line(s) above the definition (graph-builder graphs).
+  const lineCache = new Map();
+  const linesOf = (f) => { let l = lineCache.get(f); if (!l) { l = String(sources.get(f) || "").split(/\r?\n/); lineCache.set(f, l); } return l; };
+  const symLine = (n) => { const m = /@(\d+)$/.exec(String(n.id)) || /L(\d+)/.exec(String(n.source_location || "")); return m ? Number(m[1]) : 0; };
+  const isDecorated = (n) => {
+    if (n.decorated) return true;
+    const ln = symLine(n);
+    if (!ln) return false;
+    const lines = linesOf(n.source_file);
+    for (let i = ln - 2; i >= 0 && i >= ln - 6; i--) {
+      const t = (lines[i] || "").trim();
+      if (t.startsWith("@")) return true;
+      if (t === "" || t.startsWith("#")) continue;
+      break;
+    }
+    return false;
+  };
+
+  const isReferenced = (n) => {
+    if (inbound.has(n.id)) return true;                          // a real graph edge targets it
+    const name = bareName(n.label);
+    if (!name || !/^[A-Za-z_$]/.test(name)) return true;         // selectors/odd labels → don't flag
+    if (/^__\w+__$/.test(name)) return true;                     // dunders are invoked implicitly (with/str/==/iter…), never spelled
+    if ((globalFreq.get(name) || 0) > 1) return true;            // name appears beyond its single definition
+    return isDecorated(n);                                       // framework-registered via decorator
+  };
+
+  const deadSymbols = [];
+  for (const n of symById.values()) {
+    if (isReferenced(n)) continue;
+    const test = TEST_FILE.test(n.source_file);
+    deadSymbols.push({ id: n.id, file: n.source_file, label: n.label, test, reason: "no inbound edge and name unreferenced outside its file" });
+  }
+  const deadSet = new Set(deadSymbols.map((s) => s.id));
+
+  const deadFiles = [];
+  for (const n of nodes) {
+    if (String(n.id).includes("#")) continue;                   // file nodes only
+    if (inbound.has(n.id) || ENTRY_FILE.test(n.source_file)) continue;
+    const syms = symsByFile.get(n.source_file) || [];
+    if (syms.length && syms.every((s) => deadSet.has(s.id))) deadFiles.push({ file: n.source_file, reason: "not imported; all symbols unreferenced" });
+  }
+
+  return {
+    deadSymbols,
+    deadFiles,
+    referencedIds: [...symById.values()].filter(isReferenced).map((n) => n.id),
+    stats: { symbols: symById.size, deadSymbols: deadSymbols.length, files: nodes.filter((n) => !String(n.id).includes("#")).length, deadFiles: deadFiles.length },
+  };
+}
+
+// Export-scoped unused check (knip's "unused exports"): an EXPORTED symbol (P0's exported:true flag)
+// with no inbound non-contains edge whose bare name occurs in NO file other than its own. Same-file-only
+// usage means the symbol is alive but the export is not — still worth surfacing. Pure like computeDead.
+// dynamicTargets = files reached via dynamic import() — their exports are consumed at runtime, skip them.
+export function computeUnusedExports(graph, sources, { dynamicTargets = new Set() } = {}) {
+  const nodes = graph.nodes || [], links = graph.links || [];
+  const ep = (v) => (v && typeof v === "object" ? v.id : v);
+  const inbound = new Set();
+  for (const l of links) if (l.relation !== "contains") inbound.add(ep(l.target));
+
+  const candidates = [];
+  const wanted = new Set();
+  for (const n of nodes) {
+    if (!n.exported || !String(n.id).includes("#") || inbound.has(n.id)) continue;
+    if (ENTRY_FILE.test(n.source_file) || dynamicTargets.has(n.source_file)) continue;
+    const nm = bareName(n.label);
+    if (!nm || !/^[A-Za-z_$]/.test(nm)) continue;
+    candidates.push({ n, nm });
+    wanted.add(nm);
+  }
+  if (!candidates.length) return [];
+
+  const occursIn = new Map(); // name -> Set(files whose text contains it)
+  for (const [file, text] of sources) {
+    for (const m of String(text || "").matchAll(IDENT_RE)) {
+      const w = m[0];
+      if (!wanted.has(w)) continue;
+      (occursIn.get(w) || occursIn.set(w, new Set()).get(w)).add(file);
+    }
+  }
+
+  const out = [];
+  for (const { n, nm } of candidates) {
+    const occ = occursIn.get(nm);
+    if (occ && [...occ].some((f) => f !== n.source_file)) continue; // referenced beyond its own file → alive
+    out.push({ id: n.id, file: n.source_file, label: n.label, test: TEST_FILE.test(n.source_file), reason: "exported but never imported or referenced outside its own file" });
+  }
+  return out;
+}
+
+// fs wrapper: reads each graph file's source once, then runs the pure checker.
+export function analyzeDeadCode(graph, repoRoot) {
+  const sources = new Map();
+  const files = new Set();
+  for (const n of graph.nodes || []) if (n.source_file) files.add(n.source_file);
+  for (const f of files) { try { sources.set(f, readFileSync(join(repoRoot, f), "utf8")); } catch { /* file gone */ } }
+  return computeDead(graph, sources);
+}