weavatrix 0.1.1 → 0.1.3

package/README.md

@@ -5,8 +5,8 @@
 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.**
+coverage mapping. **23 tools available; 21 offline tools enabled by default, including one-call
+repository switching. Local-first: with the defaults, no repository data leaves your machine.**
 
 - Website: [weavatrix.com](https://weavatrix.com)
 - Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
@@ -32,7 +32,7 @@ answers grep can't produce:
 Requires Node ≥ 18. One command:
 
 ```sh
-# Claude Code — one user-level registration serves every repo on the machine:
+# Claude Code — offline default; open_repo can switch local repositories:
 claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>
 ```
 
@@ -51,6 +51,20 @@ startup_timeout_sec = 20
 tool_timeout_sec = 60
 ```
 
+The default includes offline repository switching but excludes every network tool. Pass a final
+comma-separated capability list only to restrict or extend it:
+
+```sh
+# Pin the registration to one repository (hide open_repo/list_known_repos):
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build
+
+# Add network tools while pinning one repository:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build,online
+
+# Add network tools and keep the default repository switching:
+claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> graph,search,source,health,build,retarget,online
+```
+
 Or clone it:
 
 ```sh
@@ -63,9 +77,12 @@ claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.m
   (`<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.
+No graph yet? Ask the agent to call `rebuild_graph`; it builds the missing graph locally.
+`open_repo` can change the active repository and builds a missing graph automatically. A normal
+`open_repo` call also upgrades graphs created before `0.1.3` to typed import edges; `build:false`
+probes without building and refuses a legacy graph. Retargeting is offline but intentionally changes
+the filesystem boundary for subsequent tools; omit `retarget` from an explicit capability list when
+a registration must stay pinned to one repository.
 
 An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install as
 `~/.claude/skills/weavatrix/SKILL.md`.
@@ -74,20 +91,24 @@ An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — instal
 
 **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`
+`change_impact`, `graph_diff`. Runtime dependencies and TypeScript type-only coupling are reported
+separately where that distinction changes the result.
 
 **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)
+**health** — `run_audit` (dead code, unused exports, missing/unused npm/Go/Python deps, runtime
+cycles, type-only coupling, 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`
+`graph.prev.json`)
+
+**retarget** *(enabled by default, offline, explicit tool call)* — `open_repo`, `list_known_repos`;
+changes the active repository boundary
 
 **online** *(explicit opt-in — see Privacy)* — `refresh_advisories`, `sync_graph`
 
@@ -95,20 +116,95 @@ Quality of life: graph tools self-report staleness vs the repo HEAD; ambiguous n
 disclosed instead of silently guessed; and the server **hot-reloads its own tool code** when the
 files under `src/mcp/` change — no reconnect needed.
 
+## Signal quality and repository configuration
+
+Weavatrix `0.1.3` reduces the most common sources of static-analysis noise:
+
+- In Git repositories, graph and clone scans use tracked plus non-ignored untracked files, so
+  `.gitignore`-excluded build outputs such as packaged applications do not dominate findings.
+- TypeScript `import type` and type-only re-exports remain visible as compile-time coupling but do
+  not inflate runtime-cycle severity. `module_map`, `change_impact` and structural diffs preserve
+  that distinction. `god_nodes` ranks unique neighbors with runtime connectivity first and reports
+  repeated occurrences separately.
+- Dependency checks resolve the nearest workspace manifest and `tsconfig`/`jsconfig` aliases,
+  account for framework-owned runtime peers such as Next.js + `react-dom`, and recognize Next.js
+  App Router route exports as endpoints.
+- `coverage_map` reports coverage as **unavailable** when no supported report exists. That means
+  “no data”, not zero coverage.
+- Duplicate output is a review queue, not a verdict: near-identical bodies are clone candidates;
+  same-name/different-body pairs are divergence candidates. Read both sources and confirm the
+  shared contract before consolidating code.
+
+`run_audit` makes incomplete security coverage explicit. OSV state is `OK` only after every
+supported pinned package/version for this repository was queried successfully. `PARTIAL` means
+some queries failed, the response was incomplete, the dependency fingerprint changed, or the cache
+uses a legacy stamp; `NOT_CHECKED` means there is no per-repository refresh; `ERROR` means the local
+check itself failed. None of the latter three states is a clean vulnerability result. The cache
+stores a fingerprint of the supported dependency set so a lockfile change cannot silently reuse a
+stale `OK`.
+
+For conventions that cannot be inferred safely, add an optional `.weavatrix-deps.json` at the
+repository root:
+
+```json
+{
+  "entrypoints": ["scripts/publish-release.mjs"],
+  "python": {
+    "managedDependencies": ["numpy", "openvino-genai"],
+    "ignoreDependencies": ["vendor-sdk"]
+  }
+}
+```
+
+`entrypoints` protects framework/script entry files from dead-code classification.
+`managedDependencies` declares Python modules supplied by an external runtime;
+`ignoreDependencies` suppresses intentionally unresolved Python packages. Keep the lists narrow:
+they change audit interpretation, not the repository or its dependency installation.
+
 ## 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:
+Graph queries, audits, clone scans and repository switching run locally. The default capability set
+is `graph,search,source,health,build,retarget`: no Weavatrix HTTP requests. `open_repo` changes the
+active local boundary only when called. Weavatrix itself initiates outbound HTTP only from two
+tools; both require the explicit `online` group and a tool call:
 
 - `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.
+- `sync_graph` — constructs a versioned, allowlisted payload from `graph.json`: relative paths,
+  symbol names and line ranges, import/dependency identifiers, edges and numeric metrics. Unknown
+  fields are discarded; source file bodies are never read for sync or included in the payload. The
+  endpoint is **yours**, configured via `WEAVATRIX_SYNC_URL` / `WEAVATRIX_SYNC_TOKEN`. Off by default.
+  Sync payload v2 preserves type-only edge metadata. Graphs built before `0.1.3` must be rebuilt
+  once before syncing; a normal `open_repo` call performs that upgrade automatically.
+
+If `refresh_advisories` is not listed by the MCP client, that is the expected default: the
+registration does not include `online`. Only with the user's approval, add `online` to the final
+capability list (for example `graph,search,source,health,build,retarget,online`), restart/reconnect
+the MCP server, and then invoke `refresh_advisories`. Enabling the group does not trigger a request
+by itself.
+
+Capability groups (`graph`, `search`, `source`, `health`, `build`, `retarget`, `online`) are
+selectable through the final positional argument. Omitted caps use the safe default above; an
+explicit list exposes exactly the named groups.
+
+## Security model
+
+Socket capability alerts describe expected powers of a local code-analysis tool; they are not
+vulnerability findings. This is where each capability comes from and how it is controlled:
+
+| Capability alert | Why it exists | Activation and boundary |
+|---|---|---|
+| Network access | `refresh_advisories` sends pinned package names and versions to OSV; `sync_graph` sends a versioned allowlist of graph metadata (relative paths, symbols and line ranges, import/dependency identifiers, edges and numeric metrics). It discards unknown graph fields and does not read source file bodies | `online` is disabled by default; each request requires a tool call, and sync additionally requires `WEAVATRIX_SYNC_URL` |
+| Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; timed-out Windows child processes may be terminated | Used only by the corresponding local operation; it does not imply network access |
+| Debug / dynamic loading | Cache-busted `import()` hot-reloads local MCP tool modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` |
+| Environment access | Reads `WEAVATRIX_*` configuration; local child processes inherit the normal host environment | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment and read only by `sync_graph` |
+| Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory cache | Realpath containment blocks traversal and symlink/junction escapes. `open_repo` is an explicit offline call that changes the active boundary; omit `retarget` in a custom capability list to pin one repository. The optional malware dependency scan may inspect installed dependency caches such as GOPATH |
+| URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the two `online` tools perform requests |
+
+`read_source` accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or
+realpath escapes. Graph-derived paths pass through the same boundary before analysis tools read
+them. Report suspected vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
 
 ## Languages
 

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published version of Weavatrix. Upgrade to the newest
+release before reporting an issue that may already be resolved.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Use GitHub's private vulnerability
+reporting flow:
+
+https://github.com/sergii-ziborov/weavatrix/security/advisories/new
+
+Include the affected Weavatrix version, operating system, MCP client, enabled capability groups,
+reproduction steps, expected boundary, observed behavior, and potential impact. Avoid including real
+credentials, private source code, or other sensitive data in the report.
+
+Reports will be investigated privately. Public disclosure should be coordinated after a fix or
+mitigation is available so users have a reasonable opportunity to update.
+
+## Security boundaries
+
+The default MCP registration is offline. Every standard source, manifest, configuration and coverage
+read is canonical-path-contained within the active repository and rejects traversal plus symlink or
+junction escapes. The optional malware dependency scan may inspect installed dependency caches such
+as GOPATH. The default `retarget` capability exposes `open_repo`, an explicit offline tool call that
+intentionally changes the active repository; omit that group in a custom capability list to pin one
+boundary. The optional `online` capability contains Weavatrix's HTTP tools; `sync_graph`
+additionally requires a user-configured endpoint and sends only a versioned metadata allowlist,
+discarding unknown fields from the local graph cache.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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>",
@@ -25,10 +25,16 @@
     "src",
     "skill",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "verify:release": "node scripts/verify-release.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "keywords": [
     "mcp",
@@ -44,7 +50,13 @@
     "ai-agents"
   ],
   "dependencies": {
-    "tree-sitter-wasms": "^0.1.13",
-    "web-tree-sitter": "^0.25.3"
+    "tree-sitter-wasms": "0.1.13",
+    "web-tree-sitter": "0.25.10"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2"
+  },
+  "overrides": {
+    "tmp": "0.2.7"
   }
 }

package/skill/SKILL.md

@@ -5,9 +5,9 @@ description: Drive the weavatrix MCP — code graph, blast-radius (get_dependent
 
 # 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.
+Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. The default
+is offline and includes `open_repo` for one-call switching between local Git repositories. A custom
+capability list that omits `retarget` pins the registration to its initial repository.
 
 ## Step 0 — if the tools are missing
 
@@ -15,22 +15,49 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
 (`claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>`; Codex:
 `codex mcp add weavatrix -- npx -y weavatrix <repoRoot>`), then retry.
 
+If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broken installation:
+`online` is intentionally absent from the default capability list.
+
 ## Ground rules
 
+- **Evidence, not verdicts**: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a
+  finding in source and check framework/runtime conventions before deleting, merging or redesigning
+  code. A same-name/different-body pair is a divergence candidate, not proof of duplication.
 - **Freshness**: every graph tool appends a staleness warning when the repo has commits newer than
-  the graph. Act on it: `rebuild_graph`.
+  the graph. Act on it: `rebuild_graph`. A normal `open_repo` builds missing graphs and upgrades
+  pre-`0.1.3` graphs to typed import edges; `build:false` deliberately refuses that upgrade.
 - **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.
+- **Runtime versus compile time**: keep runtime cycles and TypeScript type-only coupling separate.
+  `module_map` and `change_impact` label the distinction; `god_nodes` ranks unique connectivity and
+  reports repeated references separately. Do not schedule a runtime-cycle refactor from type-only
+  edges alone.
+- **Repository universe**: in Git repositories, graph and duplicate scans include tracked plus
+  non-ignored untracked files. If an old graph still contains packaged/generated output, rebuild it
+  before interpreting the result.
+- **Coverage**: `coverage_map` reads an existing report. `unavailable` means no supported report was
+  found, not 0% coverage; do not rank testing risk from that state.
+- **Audit completeness**: read `checks.osv.status` and `checks.malware.status`. For OSV, `OK` is
+  complete for the recorded dependency fingerprint; `PARTIAL` is incomplete or stale,
+  `NOT_CHECKED` has no repository-specific result, and `ERROR` means the local check failed. Treat
+  the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
+  authorized adding the optional `online` capability group to the MCP registration and then
+  invoking `refresh_advisories`; enabling the group alone sends nothing.
 - **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.
+  package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (pushes a
+  versioned allowlist of graph metadata, discarding unknown fields and never reading source file
+  bodies for sync, to a user-configured endpoint; disabled until
+  `WEAVATRIX_SYNC_URL` is set). `online` is
+  absent from the default capability set and must be enabled explicitly.
+- **Repository boundary**: source reads and graph-derived paths are realpath-contained. `open_repo`
+  intentionally changes the active boundary through an explicit offline tool call. It is available
+  by default; omit `retarget` from a custom capability list to hide it.
 
 ## Recipes
 
-- **Orient in an unfamiliar repo**: `open_repo` → `module_map` → `list_communities` → `god_nodes`.
+- **Orient in the configured 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
@@ -41,15 +68,45 @@ Tools are named `mcp__weavatrix__…`. If none are available, ask the user to re
   (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`.
+  `coverage_map`. Inspect the source behind shortlisted findings before proposing edits.
 - **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).
+- **Another repo**: `list_known_repos` → `open_repo <path>`
+  (builds or upgrades the graph when needed; `build:false` probes without building).
+
+## Repository-specific conventions
+
+Weavatrix understands nearest workspace manifests, nested `tsconfig`/`jsconfig` aliases,
+framework-owned runtime peers such as Next.js + `react-dom`, and Next.js App Router route exports.
+For project-specific entry points or Python dependencies supplied by an external runtime, add
+`.weavatrix-deps.json` at the repository root:
+
+```json
+{
+  "entrypoints": ["scripts/publish-release.mjs"],
+  "python": {
+    "managedDependencies": ["numpy", "openvino-genai"],
+    "ignoreDependencies": ["vendor-sdk"]
+  }
+}
+```
+
+Keep exceptions narrow. `managedDependencies` documents modules provided outside the repo's Python
+manifest; `ignoreDependencies` suppresses intentionally unresolved imports.
+
+## Sync
+
+`sync_graph` uses allowlisted payload v2, including typed-edge metadata but no source bodies. A graph
+built before `0.1.3` must be rebuilt first; normal `open_repo` does this automatically. Sync remains
+unavailable until the user opts into `online` and configures `WEAVATRIX_SYNC_URL`.
 
 ## Troubleshooting
 
-- `Graph unavailable` → `open_repo` with a valid repo path.
+- `Graph unavailable` → `rebuild_graph`; `open_repo` can select another valid repository path unless
+  the registration deliberately omitted `retarget`.
+- `refresh_advisories` is unavailable → with the user's approval, re-register/reconfigure the MCP
+  capability list to include `online`, reconnect it, and then invoke the tool. Do not enable network
+  access merely to turn `NOT_CHECKED` into a cosmetic green state.
 - `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.

package/src/analysis/coverage-reports.js

@@ -3,6 +3,7 @@
 // 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";
+import { createRepoBoundary } from "../repo-path.js";
 
 export function normRepoPath(value) {
   return String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
@@ -210,20 +211,22 @@ function parseGoCoverage(map, filePath, knownFiles, repoRoot) {
 export function readCoverageForRepo(repoRoot, knownFiles) {
   const out = new Map();
   if (!repoRoot) return out;
+  const boundary = createRepoBoundary(repoRoot);
   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]
+    ["coverage/coverage-summary.json", parseIstanbulSummary],
+    ["coverage/coverage-final.json", parseIstanbulFinal],
+    ["coverage/lcov.info", parseLcov],
+    ["lcov.info", parseLcov],
+    ["coverage/coverage.json", parseCoveragePyJson],
+    ["coverage.json", parseCoveragePyJson],
+    ["coverage.out", parseGoCoverage],
+    ["cover.out", parseGoCoverage]
   ];
-  for (const [path, parser] of candidates) {
-    if (!existsSync(path)) continue;
+  for (const [candidate, parser] of candidates) {
+    const resolved = boundary.resolve(candidate);
+    if (!resolved.ok || !existsSync(resolved.path)) continue;
     try {
-      parser(out, path, knownFiles, repoRoot);
+      parser(out, resolved.path, knownFiles, repoRoot);
     } catch {
       /* malformed/foreign coverage report: ignore */
     }

package/src/analysis/dead-check.js

@@ -6,7 +6,8 @@
 // `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";
+import { posix } from "node:path";
+import { createRepoBoundary } from "../repo-path.js";
 
 const IDENT_RE = /[A-Za-z_$][\w$]*/g;
 const bareName = (label) => String(label || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
@@ -15,7 +16,80 @@ const bareName = (label) => String(label || "").replace(/\s*\(.*$/, "").replace(
 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) {
+// Framework-owned entry modules are invoked by convention rather than a source import. Keep this narrow:
+// these are Next.js App/Pages Router surfaces and framework metadata files, not every file under `app/`.
+export const NEXT_ENTRY_FILE = /(^|\/)(?:src\/)?app\/(?:.*\/)?(?:page|layout|template|loading|error|global-error|not-found|default|route|robots|sitemap|manifest|opengraph-image|twitter-image|icon|apple-icon)\.[cm]?[jt]sx?$|(^|\/)(?:src\/)?pages\/(?!.*\/(?:components?|lib|utils?)\/).+\.[cm]?[jt]sx?$|(^|\/)(?:middleware|instrumentation)\.[cm]?[jt]s$/i;
+export const isFrameworkEntryFile = (file) => NEXT_ENTRY_FILE.test(String(file || "").replace(/\\/g, "/"));
+
+const lineOfNode = (n) => {
+  const m = /@(\d+)$/.exec(String(n.id || "")) || /L(\d+)/.exec(String(n.source_location || ""));
+  return m ? Number(m[1]) : 0;
+};
+
+// Older graphs marked every method of an exported class as exported. Verify that an `exported` node is
+// actually a module-surface declaration before reporting it. New graphs expose symbol_kind/member_of and
+// already keep members unexported, but the source check preserves correctness for cached v0.1.2 graphs.
+function hasModuleExport(source, node, name) {
+  if (node.member_of || node.symbol_kind === "method") return false;
+  const lines = String(source || "").split(/\r?\n/);
+  const line = lines[Math.max(0, lineOfNode(node) - 1)] || "";
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const direct = new RegExp(`\\bexport\\s+(?:default\\s+)?(?:(?:declare|abstract|async)\\s+)*(?:function|class|const|let|var|enum|interface|type|namespace)\\s+${escaped}\\b`);
+  if (direct.test(line) || direct.test(String(source || ""))) return true;
+  const exportDefault = new RegExp(`\\bexport\\s+default\\s+${escaped}\\b`);
+  if (exportDefault.test(String(source || ""))) return true;
+  // `export { local }`, `export { local as publicName }` and CommonJS explicit exports.
+  const exportList = new RegExp(`\\bexport\\s*\\{[^}]*\\b${escaped}\\b[^}]*\\}`, "s");
+  const commonJs = new RegExp(`(?:module\\.exports\\s*=\\s*\\{[^}]*\\b${escaped}\\b|(?:module\\.exports|exports)\\.${escaped}\\s*=)`, "s");
+  return exportList.test(String(source || "")) || commonJs.test(String(source || ""));
+}
+
+function namespaceConsumedFiles(sources, graph) {
+  const files = new Set(sources.keys());
+  const consumed = new Set();
+  const extensions = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
+  const resolve = (from, spec) => {
+    if (!spec.startsWith(".")) return "";
+    const base = posix.normalize(posix.join(posix.dirname(from.replace(/\\/g, "/")), spec));
+    for (const ext of extensions) {
+      const p = `${base}${ext}`;
+      if (files.has(p)) return p;
+    }
+    for (const ext of extensions.slice(1)) {
+      const p = `${base}/index${ext}`;
+      if (files.has(p)) return p;
+    }
+    return "";
+  };
+  for (const [file, textValue] of sources) {
+    const text = String(textValue || "");
+    const patterns = [
+      /\bimport\s+\*\s+as\s+[A-Za-z_$][\w$]*\s+from\s*(["'])([^"']+)\1/g,
+      /\bexport\s+\*\s+from\s*(["'])([^"']+)\1/g,
+      /\b(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*require\(\s*(["'])([^"']+)\1\s*\)/g,
+    ];
+    for (const re of patterns) {
+      let m;
+      while ((m = re.exec(text))) {
+        const target = resolve(file, m[2]);
+        if (target) consumed.add(target);
+      }
+    }
+  }
+  // New graphs retain the exact specifier on file import edges, which also resolves namespace imports
+  // expressed through tsconfig aliases (the relative-path fallback above intentionally cannot guess those).
+  for (const link of graph.links || []) {
+    if (link.relation !== "imports" && link.relation !== "re_exports") continue;
+    const from = String(link.source?.id || link.source || ""), target = String(link.target?.id || link.target || "");
+    if (!link.specifier || from.includes("#") || target.includes("#") || !sources.has(from)) continue;
+    const spec = String(link.specifier).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const text = String(sources.get(from) || "");
+    if (new RegExp(`(?:import\\s+\\*\\s+as\\s+[A-Za-z_$][\\w$]*\\s+from|export\\s+\\*\\s+from)\\s*["']${spec}["']`).test(text)) consumed.add(target);
+  }
+  return consumed;
+}
+
+export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
   const nodes = graph.nodes || [], links = graph.links || [];
   const ep = (v) => (v && typeof v === "object" ? v.id : v);
   const inbound = new Set();
@@ -73,7 +147,7 @@ export function computeDead(graph, sources) {
   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;
+    if (inbound.has(n.id) || ENTRY_FILE.test(n.source_file) || isFrameworkEntryFile(n.source_file) || entrySet.has(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" });
   }
@@ -90,19 +164,21 @@ export function computeDead(graph, sources) {
 // 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() } = {}) {
+export function computeUnusedExports(graph, sources, { dynamicTargets = new Set(), entrySet = 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 namespaceConsumed = namespaceConsumedFiles(sources, graph);
   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;
+    if (ENTRY_FILE.test(n.source_file) || isFrameworkEntryFile(n.source_file) || entrySet.has(n.source_file) || dynamicTargets.has(n.source_file) || namespaceConsumed.has(n.source_file)) continue;
     const nm = bareName(n.label);
     if (!nm || !/^[A-Za-z_$]/.test(nm)) continue;
+    if (!hasModuleExport(sources.get(n.source_file), n, nm)) continue;
     candidates.push({ n, nm });
     wanted.add(nm);
   }
@@ -130,7 +206,12 @@ export function computeUnusedExports(graph, sources, { dynamicTargets = new Set(
 export function analyzeDeadCode(graph, repoRoot) {
   const sources = new Map();
   const files = new Set();
+  const boundary = createRepoBoundary(repoRoot);
   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 */ } }
+  for (const f of files) {
+    const resolved = boundary.resolve(f);
+    if (!resolved.ok) continue;
+    try { sources.set(f, readFileSync(resolved.path, "utf8")); } catch { /* file gone */ }
+  }
   return computeDead(graph, sources);
 }