weavatrix 0.1.2 → 0.1.4

package/README.md

@@ -77,10 +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? Ask the agent to call `rebuild_graph`; it builds the missing graph locally. When the
-`open_repo` can change the active repository and build its 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.
+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.4` to edge metadata v2; `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`.
@@ -89,17 +91,19 @@ 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`
+`change_impact`, `graph_diff`. Runtime dependencies, TypeScript type-only coupling and language
+compile-only edges (Rust module/use, Java imports) 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 …)
+Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …)
 
-**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/compile-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`)
@@ -110,8 +114,72 @@ changes the active repository boundary
 **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.
+disclosed instead of silently guessed; and the server **hot-reloads its watched MCP tool entry
+modules and catalog** when those files change — other MCP helpers and analysis engines require a
+reconnect.
+
+## Signal quality and repository configuration
+
+Weavatrix `0.1.4` reduces the most common sources of static-analysis noise while deepening Rust and
+Java graphs:
+
+- 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.
+- Rust `mod`, `use` and `pub use` paths now resolve between files and modules. They are marked
+  compile-only, so they enrich `module_map` and compile-time coupling without inventing runtime
+  initialization cycles or promoting compile-time coupling to runtime impact. Axum and actix-web
+  routes are included in `list_endpoints`.
+- Java class/interface/enum/record/annotation declarations retain their symbol kind; methods and
+  constructors are linked to their declaring type with visibility metadata. Internal
+  `extends`/`implements` relationships and resolvable type references link to real declarations.
+  Imports are compile-only; call/reference/heritage edges contribute impact. Maven/Gradle Java
+  trees use package-aware communities instead of one giant `src` bucket. External or synthetic
+  placeholder types are not created merely to inflate graph counts.
+- 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.
+- Generated NAPI-RS platform loaders and declared template/example catalogs no longer create
+  phantom runtime dependency, orphan or unused-export findings. Conventional template roots are
+  inferred conservatively; custom roots can be declared explicitly.
+- `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"],
+  "nonRuntimeRoots": ["library", "catalogs/examples"],
+  "python": {
+    "managedDependencies": ["numpy", "openvino-genai"],
+    "ignoreDependencies": ["vendor-sdk"]
+  }
+}
+```
+
+`entrypoints` protects framework/script entry files from dead-code classification.
+`nonRuntimeRoots` (alias: `templateRoots`) marks reusable examples/templates that are not deployed
+as one application. It suppresses orphan/dead/unused-export noise and missing/unresolved dependency
+findings when every use is inside those roots. Import edges, cycles and boundary checks remain visible.
+`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
 
@@ -127,7 +195,14 @@ tools; both require the explicit `online` group and a tool call:
   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.
-  Graphs built before `0.1.2` must be rebuilt once before syncing.
+  Sync payload v2 preserves type-only and compile-only edge metadata. Graphs built before `0.1.4` 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
@@ -142,7 +217,7 @@ vulnerability findings. This is where each capability comes from and how it is c
 |---|---|---|
 | 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` |
+| Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool entry 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 |
@@ -171,8 +246,8 @@ npm test          # node --test
 
 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`.
+in `src/mcp/` (graph context, tool entry modules, focused helpers, and the catalog/hot-reload
+loader) behind the thin stdio entry `src/mcp-server.mjs`.
 
 ## Roadmap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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>",

package/skill/SKILL.md

@@ -15,12 +15,35 @@ 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.4` graphs to edge metadata v2; `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 separate from TypeScript type-only and
+  language compile-only coupling (Rust `mod`/`use`/`pub use`, Java imports). `module_map`,
+  `change_impact` and `graph_diff` label the distinction; `god_nodes` ranks unique connectivity and
+  reports repeated references separately. Do not schedule a runtime-cycle refactor from
+  compile-time-only edges.
+- **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
@@ -46,16 +69,51 @@ 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`.
-- **API inventory**: `list_endpoints`.
+  `coverage_map`. Inspect the source behind shortlisted findings before proposing edits.
+- **API inventory**: `list_endpoints` (including Next.js App Router, Rust axum and actix-web).
 - **Find code**: `search_code` (regex + glob) → `get_node` → `read_source`.
 - **Another repo**: `list_known_repos` → `open_repo <path>`
-  (builds the graph when missing; `build:false` probes without building).
+  (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`, generated NAPI-RS platform loaders,
+and Next.js App Router route exports. For project-specific entry points, reusable template catalogs,
+or Python dependencies supplied by an external runtime, add `.weavatrix-deps.json` at the repository
+root:
+
+```json
+{
+  "entrypoints": ["scripts/publish-release.mjs"],
+  "nonRuntimeRoots": ["library", "catalogs/examples"],
+  "python": {
+    "managedDependencies": ["numpy", "openvino-genai"],
+    "ignoreDependencies": ["vendor-sdk"]
+  }
+}
+```
+
+Keep exceptions narrow. `nonRuntimeRoots` (alias `templateRoots`) marks reusable examples that are
+not one deployed application. It suppresses orphan/dead/unused-export noise and missing/unresolved
+dependency findings when every use is inside those roots; graph edges, cycles and boundaries remain
+visible. `managedDependencies` documents modules provided outside the repo's Python manifest;
+`ignoreDependencies` suppresses intentionally unresolved imports.
+
+## Sync
+
+`sync_graph` uses allowlisted payload v2, including type-only/compile-only edge metadata but no
+source bodies. A graph built before `0.1.4` 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` → `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/dead-check.js

@@ -6,7 +6,9 @@
 // `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 { posix } from "node:path";
 import { createRepoBoundary } from "../repo-path.js";
+import { isStructuralRelation } from "../graph/relations.js";
 
 const IDENT_RE = /[A-Za-z_$][\w$]*/g;
 const bareName = (label) => String(label || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
@@ -15,11 +17,88 @@ 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 RUST_ENTRY_FILE = /(^|\/)(?:build\.rs|src\/(?:lib|main)\.rs)$/i;
+export const isFrameworkEntryFile = (file) => {
+  const normalized = String(file || "").replace(/\\/g, "/");
+  return NEXT_ENTRY_FILE.test(normalized) || RUST_ENTRY_FILE.test(normalized);
+};
+
+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();
-  for (const l of links) if (l.relation !== "contains") inbound.add(ep(l.target));
+  for (const l of links) if (!isStructuralRelation(l.relation)) 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).
@@ -73,7 +152,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 +169,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));
+  for (const l of links) if (!isStructuralRelation(l.relation)) 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);
   }

package/src/analysis/dep-check-ecosystems.js

@@ -0,0 +1,157 @@
+import { makeFinding } from "./findings.js";
+
+const TEST_PATH_RE = /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z0-9]+$|_test\.go$/i;
+const escRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const mentioned = (blob, name) => new RegExp(`(^|[^\\w@.-])${escRe(name)}($|[^\\w.-])`).test(blob);
+
+// ---- Go: set math over ecosystem:"Go" externalImports vs go.mod requires ----
+// goMod = parseGoMod() output. Only DIRECT requires can be "unused" (indirect ones belong to `go mod
+// tidy`); replace targets and the own module never count. Missing = imported module with no require
+// prefix — rare in Go (builds fail), so it usually flags vendored/replaced setups: keep it medium.
+export function computeGoDepFindings({ externalImports = [], goMod = null, nonRuntimeRoots = [] } = {}) {
+  const findings = [];
+  if (!goMod || !goMod.module) return { findings, declared: new Set() };
+  const requires = goMod.requires || [];
+  const declared = new Set(requires.map((r) => r.path));
+  const replaced = new Set((goMod.replaces || []).map((r) => r.from));
+  const moduleOf = (spec) => { let best = ""; for (const p of declared) if ((spec === p || spec.startsWith(p + "/")) && p.length > best.length) best = p; return best; };
+
+  const usedModules = new Set();
+  const missing = new Map(); // pkg → { files:Set, lines:Map }
+  const inNonRuntimeRoot = (file) => (nonRuntimeRoots || []).some((root) => {
+    const f = String(file || "").replace(/\\/g, "/"), r = String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+    return !!r && (f === r || f.startsWith(`${r}/`));
+  });
+  for (const e of externalImports) {
+    if (e.ecosystem !== "Go" || e.builtin || e.unresolved || !e.pkg) continue;
+    const mod = moduleOf(e.spec || e.pkg) || (declared.has(e.pkg) ? e.pkg : "");
+    if (mod) { usedModules.add(mod); continue; }
+    let m = missing.get(e.pkg);
+    if (!m) missing.set(e.pkg, (m = { files: new Set(), lines: new Map() }));
+    m.files.add(e.file);
+    if (!m.lines.has(e.file)) m.lines.set(e.file, e.line || 0);
+  }
+
+  for (const r of requires) {
+    if (r.indirect || usedModules.has(r.path)) continue;
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "unused-dep",
+      severity: "low",
+      confidence: "medium",
+      title: `Unused Go module: ${r.path}`,
+      detail: `"${r.path}" is required (direct) in go.mod but no .go file imports it or any of its packages. Build-tag-guarded files can hide usage — confirm with \`go mod tidy\` before removing.`,
+      package: r.path,
+      version: r.version,
+      source: "internal",
+      fixHint: "go mod tidy (drops requires nothing imports)",
+    }));
+  }
+  for (const [pkg, use] of missing) {
+    if (replaced.has(pkg)) continue;
+    const files = [...use.files];
+    if (files.every(inNonRuntimeRoot)) continue;
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "missing-dep",
+      severity: "medium",
+      confidence: "medium",
+      title: `Missing Go module: ${pkg}`,
+      detail: `"${pkg}" is imported by ${files.length} file(s) but go.mod has no matching require — a replace/workspace/vendor setup, or the module was never added.`,
+      package: pkg,
+      file: files[0],
+      line: use.lines.get(files[0]) || 0,
+      evidence: files.slice(0, 5).map((f) => ({ file: f, line: use.lines.get(f) || 0, snippet: "" })),
+      source: "internal",
+      fixHint: `go get ${pkg}`,
+    }));
+  }
+  return { findings, declared };
+}
+
+// ---- Python: ecosystem:"PyPI" externalImports vs requirements/pyproject/Pipfile ----
+// Import→dist naming is heuristic (yaml→PyYAML, python-X/X-python variants), so matching is GENEROUS for
+// suppression and every unused finding stays low-confidence. CLI-only tools (pytest, black, gunicorn …)
+// and stub/plugin conventions (types-*, *-stubs, pytest-*, flake8-*) are never flagged unused.
+const PY_TOOL_DISTS = new Set(("pytest tox nox black ruff flake8 pylint mypy pyright isort bandit coverage pre-commit pip setuptools wheel build twine poetry poetry-core " +
+  "pip-tools uv virtualenv pipenv gunicorn uwsgi supervisor ipython jupyter jupyterlab notebook ipykernel codecov autopep8 yapf commitizen detect-secrets safety pip-audit hatchling flit flit-core pdm").split(" "));
+const pyNorm = (n) => String(n || "").toLowerCase().replace(/[-_.]+/g, "-");
+
+export function computePyDepFindings({
+  externalImports = [], pyManifest = null, configTexts = new Map(),
+  managedDependencies = [], ignoredDependencies = [], nonRuntimeRoots = [],
+} = {}) {
+  const findings = [];
+  const deps = (pyManifest && pyManifest.deps) || [];
+  const present = !!(pyManifest && pyManifest.present);
+  const declared = new Set(deps.map((d) => pyNorm(d.name)));
+  const managed = new Set((managedDependencies || []).map(pyNorm));
+  const ignored = new Set((ignoredDependencies || []).map(pyNorm));
+  const inNonRuntimeRoot = (file) => (nonRuntimeRoots || []).some((root) => {
+    const f = String(file || "").replace(/\\/g, "/"), r = String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+    return !!r && (f === r || f.startsWith(`${r}/`));
+  });
+  for (const name of managed) declared.add(name);
+
+  const used = new Map(); // top import → { dist, files:Set, lines:Map }
+  for (const e of externalImports) {
+    if (e.ecosystem !== "PyPI" || e.builtin || e.unresolved || !e.pkg) continue;
+    const top = String(e.spec || e.pkg).split(".")[0];
+    let u = used.get(top);
+    if (!u) used.set(top, (u = { dist: e.pkg, files: new Set(), lines: new Map() }));
+    u.files.add(e.file);
+    if (!u.lines.has(e.file)) u.lines.set(e.file, e.line || 0);
+  }
+  // generous match: does declared dist D cover import top t (dist guess g)?
+  const covers = (D, t, g) => {
+    const d = pyNorm(D), nt = pyNorm(t), ng = pyNorm(g);
+    return d === nt || d === ng || d === `python-${nt}` || d === `${nt}-python` || d === `${nt}-binary` || d.replace(/\d+$/, "") === nt.replace(/\d+$/, "");
+  };
+
+  const configBlob = [...configTexts.values()].join("\n");
+  if (present) {
+    for (const d of deps) {
+      const n = pyNorm(d.name);
+      if (managed.has(n) || ignored.has(n)) continue;
+      if (d.buildSystem || PY_TOOL_DISTS.has(n) || /^types-|-stubs$|^pytest-|^flake8-|^sphinx/.test(n)) continue;
+      let hit = false;
+      for (const [top, u] of used) if (covers(d.name, top, u.dist)) { hit = true; break; }
+      if (hit || mentioned(configBlob, d.name)) continue;
+      findings.push(makeFinding({
+        category: "unused",
+        rule: "unused-dep",
+        severity: d.dev ? "info" : "low",
+        confidence: "low",
+        title: `Unused Python dependency: ${d.name}`,
+        detail: `"${d.name}" is declared but no .py file imports a module that maps to it. Import-name↔package-name mapping is heuristic and plugins/CLI tools load dynamically — review before removing.`,
+        package: d.name,
+        source: "internal",
+        fixHint: `remove "${d.name}" from the manifest after confirming nothing imports or shells out to it`,
+      }));
+    }
+  }
+  for (const [top, u] of used) {
+    if (ignored.has(pyNorm(top)) || ignored.has(pyNorm(u.dist)) || managed.has(pyNorm(top)) || managed.has(pyNorm(u.dist))) continue;
+    let hit = false;
+    for (const D of declared) if (covers(D, top, u.dist)) { hit = true; break; }
+    if (hit) continue;
+    const files = [...u.files];
+    if (files.every(inNonRuntimeRoot)) continue;
+    const testOnly = files.every((f) => TEST_PATH_RE.test(f));
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "missing-dep",
+      severity: present ? (testOnly ? "low" : "medium") : "low",
+      confidence: present ? "medium" : "low",
+      title: `Missing Python dependency: ${u.dist}`,
+      detail: `"${top}" is imported by ${files.length} file(s) but ${present ? "no declared dependency provides it" : "the repo has no Python dependency manifest (requirements.txt / pyproject / Pipfile); a bundled or managed runtime may provide it"}${u.dist !== top ? ` (PyPI package is likely "${u.dist}")` : ""}.${present ? "" : " If this is intentional, declare it under python.managedDependencies in .weavatrix-deps.json."}`,
+      package: u.dist,
+      file: files[0],
+      line: u.lines.get(files[0]) || 0,
+      evidence: files.slice(0, 5).map((f) => ({ file: f, line: u.lines.get(f) || 0, snippet: "" })),
+      source: "internal",
+      fixHint: present ? `pip install ${u.dist}  (and add it to requirements.txt / pyproject)` : `add ${u.dist} to a Python manifest, or declare it as a managed runtime dependency`,
+    }));
+  }
+  return { findings, declared, managed };
+}