weavatrix 0.1.3 → 0.1.4

package/README.md

@@ -79,7 +79,7 @@ claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.m
 
 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`
+`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.
@@ -91,15 +91,16 @@ 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`. Runtime dependencies and TypeScript type-only coupling are reported
-separately where that distinction changes the result.
+`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, runtime
-cycles, type-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat +
+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)
@@ -113,12 +114,14 @@ 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.3` reduces the most common sources of static-analysis noise:
+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.
@@ -126,9 +129,22 @@ Weavatrix `0.1.3` reduces the most common sources of static-analysis noise:
   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;
@@ -149,6 +165,7 @@ repository root:
 ```json
 {
   "entrypoints": ["scripts/publish-release.mjs"],
+  "nonRuntimeRoots": ["library", "catalogs/examples"],
   "python": {
     "managedDependencies": ["numpy", "openvino-genai"],
     "ignoreDependencies": ["vendor-sdk"]
@@ -157,6 +174,9 @@ repository root:
 ```
 
 `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.
@@ -175,7 +195,7 @@ 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.
-  Sync payload v2 preserves type-only edge metadata. Graphs built before `0.1.3` must be rebuilt
+  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
@@ -197,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 |
@@ -226,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.3",
+  "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

@@ -25,13 +25,14 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
   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`. A normal `open_repo` builds missing graphs and upgrades
-  pre-`0.1.3` graphs to typed import edges; `build:false` deliberately refuses that upgrade.
+  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 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.
+- **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.
@@ -69,7 +70,7 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
   `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`. Inspect the source behind shortlisted findings before proposing edits.
-- **API inventory**: `list_endpoints`.
+- **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 or upgrades the graph when needed; `build:false` probes without building).
@@ -77,13 +78,15 @@ If only `refresh_advisories` or `sync_graph` is missing, do not diagnose a broke
 ## 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:
+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"]
@@ -91,13 +94,17 @@ For project-specific entry points or Python dependencies supplied by an external
 }
 ```
 
-Keep exceptions narrow. `managedDependencies` documents modules provided outside the repo's Python
-manifest; `ignoreDependencies` suppresses intentionally unresolved imports.
+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 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
+`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

package/src/analysis/dead-check.js

@@ -8,6 +8,7 @@
 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();
@@ -19,7 +20,11 @@ const TEST_FILE = /(^|[\\/])[^\\/]*[._-](test|spec)\.[a-z0-9]+$|(^|[\\/])(test|t
 // 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, "/"));
+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 || ""));
@@ -93,7 +98,7 @@ 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).
@@ -168,7 +173,7 @@ 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));
+  for (const l of links) if (!isStructuralRelation(l.relation)) inbound.add(ep(l.target));
 
   const namespaceConsumed = namespaceConsumedFiles(sources, graph);
   const candidates = [];

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 };
+}

package/src/analysis/dep-check.js

@@ -47,7 +47,7 @@ const mentioned = (blob, name) => new RegExp(`(^|[^\\w@.-])${escRe(name)}($|[^\\
 //   configTexts     — Map<fileName, text> of root config files + CI workflows (mention scanning)
 export function computeDepFindings({
   externalImports = [], pkg = {}, workspacePkgNames = new Set(), configTexts = new Map(),
-  aliases = [], scope = "", manifest = "package.json",
+  aliases = [], scope = "", manifest = "package.json", nonRuntimeRoots = [],
 } = {}) {
   const findings = [];
   const meta = { scope: scope || ".", manifest };
@@ -68,6 +68,32 @@ export function computeDepFindings({
   };
   const allDeclared = new Set(Object.values(sections).flatMap((s) => Object.keys(s)));
   const selfName = String(pkg.name || "");
+  const normRoots = (nonRuntimeRoots || []).map((root) => String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "")).filter(Boolean);
+  const isNonRuntimeFile = (file) => {
+    const normalized = String(file || "").replace(/\\/g, "/").replace(/^\.\//, "");
+    return normRoots.some((root) => normalized === root || normalized.startsWith(`${root}/`));
+  };
+  const npmNameParts = (name) => {
+    const value = String(name || "");
+    const slash = value.startsWith("@") ? value.indexOf("/") : -1;
+    return slash > 0 ? { scope: value.slice(0, slash), base: value.slice(slash + 1) } : { scope: "", base: value };
+  };
+  const selfParts = npmNameParts(selfName);
+  const configuredNapi = npmNameParts(pkg.napi?.name || selfName);
+  const napiBinding = {
+    scope: configuredNapi.scope || (configuredNapi.base === selfParts.base ? selfParts.scope : ""),
+    base: configuredNapi.base,
+  };
+  const NAPI_PLATFORM_SUFFIX = /^(?:android-(?:arm64|arm-eabi)|win32-(?:x64|ia32|arm64)-msvc|darwin-(?:universal|x64|arm64)|freebsd-(?:x64|arm64)|linux-(?:x64|arm64|arm|riscv64|s390x|ppc64|loong64)-(?:gnu|musl|gnueabihf|musleabihf)|aix-ppc64|sunos-x64|wasm32-wasi(?:-preview1-threads)?)$/;
+  const isGeneratedNapiPackage = (name, files) => {
+    if (!pkg.napi || !napiBinding.base || !files.every((file) => /(^|\/)index\.[cm]?js$/i.test(String(file || "").replace(/\\/g, "/")))) return false;
+    const candidate = npmNameParts(name);
+    if (candidate.scope !== napiBinding.scope || !candidate.base.startsWith(`${napiBinding.base}-`)) return false;
+    return NAPI_PLATFORM_SUFFIX.test(candidate.base.slice(napiBinding.base.length + 1));
+  };
+  const isGeneratedNapiBinary = (entry) => !!pkg.napi
+    && /(^|\/)index\.[cm]?js$/i.test(String(entry.file || "").replace(/\\/g, "/"))
+    && /^\.\/[^/]+\.node$/i.test(String(entry.spec || ""));
   // Some frameworks consume required peers internally, so application source legitimately never imports
   // them. Keep this deliberately narrow: react-dom is a required Next.js runtime peer in the same package
   // scope, not a general React exemption and not a repo-wide whitelist.
@@ -134,6 +160,7 @@ export function computeDepFindings({
   for (const [name, use] of usedPackages) {
     if (allDeclared.has(name) || name === selfName || workspacePkgNames.has(name)) continue;
     const files = [...use.files];
+    if (files.every(isNonRuntimeFile) || isGeneratedNapiPackage(name, files)) continue;
     const testOnly = files.every((f) => /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z]+$/i.test(f));
     findings.push(makeFinding({
       category: "unused",
@@ -176,6 +203,7 @@ export function computeDepFindings({
   let unresolvedCount = 0;
   for (const e of externalImports) {
     if (!e.unresolved) continue;
+    if (isNonRuntimeFile(e.file) || isGeneratedNapiBinary(e)) continue;
     unresolvedCount++;
     const key = e.file + "|" + e.spec;
     if (unresolvedSeen.has(key) || unresolvedSeen.size >= 100) continue; // cap the findings, keep the count honest
@@ -216,6 +244,7 @@ const ownsFile = (scope, file) => !scope || file === scope || String(file || "")
 // Node's package scope and prevents nested Next/Vite apps from inheriting the root manifest by accident.
 export function computeScopedDepFindings({
   externalImports = [], packageScopes = [], workspacePkgNames = new Set(), configTexts = new Map(),
+  nonRuntimeRoots = [],
 } = {}) {
   const scopes = packageScopes.length
     ? packageScopes.map((s) => ({ ...s, root: normScope(s.root) })).sort((a, b) => b.root.length - a.root.length)
@@ -233,6 +262,7 @@ export function computeScopedDepFindings({
     const r = computeDepFindings({
       externalImports: importsByScope.get(s), pkg: s.pkg || {}, workspacePkgNames, configTexts: scopeConfig,
       aliases: s.aliases || [], scope: s.root, manifest: s.manifest || (s.root ? `${s.root}/package.json` : "package.json"),
+      nonRuntimeRoots,
     });
     findings.push(...r.findings);
     for (const [name, use] of r.usedPackages) usedPackages.set(`${s.root || "."}:${name}`, use);
@@ -241,146 +271,4 @@ export function computeScopedDepFindings({
   return { findings, usedPackages, declared };
 }
 
-const TEST_PATH_RE = /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z0-9]+$|_test\.go$/i;
-
-// ---- 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 } = {}) {
-  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 }
-  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];
-    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 = [],
-} = {}) {
-  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));
-  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];
-    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 };
-}
+export { computeGoDepFindings, computePyDepFindings } from "./dep-check-ecosystems.js";