weavatrix 0.1.2 → 0.1.3

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.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`.
@@ -89,17 +91,18 @@ 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 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`)
@@ -113,6 +116,51 @@ 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, clone scans and repository switching run locally. The default capability set
@@ -127,7 +175,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 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

package/package.json

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

package/skill/SKILL.md

@@ -15,12 +15,34 @@ 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
@@ -46,16 +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; `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`, 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` → `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,6 +6,7 @@
 // `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";
 
 const IDENT_RE = /[A-Za-z_$][\w$]*/g;
@@ -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);
   }

package/src/analysis/dep-check.js

@@ -26,6 +26,16 @@ const BIN_PKG = {
   playwright: "@playwright/test",
 };
 
+// Required peers consumed inside a framework/build tool rather than imported by application source.
+// These contracts are package-scope local and deliberately narrow; declaring the provider is required
+// for suppression, so an unrelated app still gets the normal unused-dependency finding.
+const FRAMEWORK_RUNTIME_PEERS = new Map([
+  ["next", ["react-dom"]],
+  ["vinext", ["@vitejs/plugin-react", "@vitejs/plugin-rsc", "react-server-dom-webpack", "vite"]],
+  ["electron-vite", ["vite"]],
+  ["@cloudflare/vite-plugin", ["vite", "wrangler"]],
+]);
+
 const escRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 // word-ish mention: the name not embedded inside a longer identifier/path segment
 const mentioned = (blob, name) => new RegExp(`(^|[^\\w@.-])${escRe(name)}($|[^\\w.-])`).test(blob);
@@ -35,8 +45,21 @@ const mentioned = (blob, name) => new RegExp(`(^|[^\\w@.-])${escRe(name)}($|[^\\
 //   pkg             — parsed package.json ({} for non-JS repos → no dep findings)
 //   workspacePkgNames — Set of monorepo-local package names (never "missing")
 //   configTexts     — Map<fileName, text> of root config files + CI workflows (mention scanning)
-export function computeDepFindings({ externalImports = [], pkg = {}, workspacePkgNames = new Set(), configTexts = new Map() } = {}) {
+export function computeDepFindings({
+  externalImports = [], pkg = {}, workspacePkgNames = new Set(), configTexts = new Map(),
+  aliases = [], scope = "", manifest = "package.json",
+} = {}) {
   const findings = [];
+  const meta = { scope: scope || ".", manifest };
+  const isAliasSpec = (spec) => aliases.some((a) => {
+    const s = String(spec || "");
+    const key = typeof a === "string" ? a : String(a?.key || "");
+    const prefix = typeof a === "string" ? a.replace(/\*.*$/, "") : String(a?.prefix || "");
+    const suffix = key.includes("*") ? key.slice(key.indexOf("*") + 1) : String(a?.suffix || "");
+    return key.includes("*")
+      ? !!prefix && s.startsWith(prefix) && (!suffix || s.endsWith(suffix))
+      : !!key && s === key;
+  });
   const sections = {
     dependencies: pkg.dependencies || {},
     devDependencies: pkg.devDependencies || {},
@@ -45,12 +68,20 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
   };
   const allDeclared = new Set(Object.values(sections).flatMap((s) => Object.keys(s)));
   const selfName = String(pkg.name || "");
+  // 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.
+  const frameworkRuntime = new Set();
+  for (const [provider, peers] of FRAMEWORK_RUNTIME_PEERS) {
+    if (allDeclared.has(provider)) for (const peer of peers) frameworkRuntime.add(peer);
+  }
 
   // ---- usage index from the graph's recorded imports ----
   const usedPackages = new Map(); // pkgName -> { files:Set, lines:Map(file→first line), kinds:Set }
   let builtinUsed = false;
   for (const e of externalImports) {
     if (e.ecosystem && e.ecosystem !== "npm") continue; // go/python imports have their own checkers
+    if (isAliasSpec(e.spec)) continue;
     if (e.unresolved) continue;
     if (e.builtin) { builtinUsed = true; continue; }
     if (!e.pkg) continue;
@@ -75,10 +106,10 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
   for (const [section, deps] of Object.entries(sections)) {
     if (section === "peerDependencies") continue; // peers are consumer-facing contracts, not usage
     for (const name of Object.keys(deps)) {
-      if (name === selfName || usedPackages.has(name)) continue;
+      if (name === selfName || usedPackages.has(name) || frameworkRuntime.has(name)) continue;
       const tb = typesBase(name);
       if (tb) { // @types/x is used iff x is used (or it types the Node builtins)
-        if (tb === "node" ? builtinUsed : usedPackages.has(tb) || mentioned(configBlob, tb)) continue;
+        if (tb === "node" ? builtinUsed : usedPackages.has(tb) || frameworkRuntime.has(tb) || mentioned(configBlob, tb)) continue;
       }
       if (binReferenced(name) || mentioned(configBlob, name)) continue; // scripts/config keep it alive
       const ecosystem = CONFIG_ECOSYSTEM_RE.test(name);
@@ -94,6 +125,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
         package: name,
         source: "internal",
         fixHint: `npm uninstall ${name} (after confirming no config/CLI usage)`,
+        ...meta,
       }));
     }
   }
@@ -109,13 +141,14 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
       severity: testOnly ? "low" : "medium",
       confidence: "high",
       title: `Missing dependency: ${name}`,
-      detail: `"${name}" is imported by ${files.length} file(s) but not declared in package.json — it only works via a transitive install (phantom dependency) and can break on any lockfile change.`,
+      detail: `"${name}" is imported by ${files.length} file(s) in scope ${meta.scope} but not declared in ${manifest} — it only works via a transitive install (phantom dependency) and can break on any lockfile change.`,
       package: name,
       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: `npm install ${testOnly ? "--save-dev " : ""}${name}`,
+      ...meta,
     }));
   }
 
@@ -134,6 +167,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
       detail: `"${name}" is declared in ${ss.join(" + ")} — npm resolves one of them; keep a single section.`,
       package: name,
       source: "internal",
+      ...meta,
     }));
   }
 
@@ -156,6 +190,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
       file: e.file,
       line: e.line || 0,
       source: "internal",
+      ...meta,
     }));
   }
   if (unresolvedCount > unresolvedSeen.size) {
@@ -167,12 +202,45 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
       title: `…and ${unresolvedCount - unresolvedSeen.size} more unresolved imports`,
       detail: "Finding list capped at 100 unique unresolved imports; the count above is the true total.",
       source: "internal",
+      ...meta,
     }));
   }
 
   return { findings, usedPackages, declared: allDeclared };
 }
 
+const normScope = (root) => String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+const ownsFile = (scope, file) => !scope || file === scope || String(file || "").startsWith(`${scope}/`);
+
+// Judge every import against its nearest ancestor package.json. This is the dependency equivalent of
+// 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(),
+} = {}) {
+  const scopes = packageScopes.length
+    ? packageScopes.map((s) => ({ ...s, root: normScope(s.root) })).sort((a, b) => b.root.length - a.root.length)
+    : [{ root: "", manifest: "package.json", pkg: {}, aliases: [] }];
+  const importsByScope = new Map(scopes.map((s) => [s, []]));
+  for (const e of externalImports) {
+    const owner = scopes.find((s) => ownsFile(s.root, e.file)) || scopes[scopes.length - 1];
+    importsByScope.get(owner).push(e);
+  }
+  const configOwner = new Map();
+  for (const [file] of configTexts) configOwner.set(file, scopes.find((scope) => ownsFile(scope.root, file)) || scopes[scopes.length - 1]);
+  const findings = [], usedPackages = new Map(), declared = new Set();
+  for (const s of scopes) {
+    const scopeConfig = new Map([...configTexts].filter(([f]) => configOwner.get(f) === s));
+    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"),
+    });
+    findings.push(...r.findings);
+    for (const [name, use] of r.usedPackages) usedPackages.set(`${s.root || "."}:${name}`, use);
+    for (const name of r.declared) declared.add(`${s.root || "."}:${name}`);
+  }
+  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 ----
@@ -243,11 +311,17 @@ const PY_TOOL_DISTS = new Set(("pytest tox nox black ruff flake8 pylint mypy pyr
   "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() } = {}) {
+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) {
@@ -268,6 +342,7 @@ export function computePyDepFindings({ externalImports = [], pyManifest = null,
   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; }
@@ -286,6 +361,7 @@ export function computePyDepFindings({ externalImports = [], pyManifest = null,
     }
   }
   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;
@@ -297,14 +373,14 @@ export function computePyDepFindings({ externalImports = [], pyManifest = null,
       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 declares no Python dependencies at all (no requirements.txt / pyproject / Pipfile)"} — it only works because the environment happens to have it${u.dist !== top ? ` (PyPI package is likely "${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: `pip install ${u.dist}  (and add it to requirements.txt / pyproject)`,
+      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 };
+  return { findings, declared, managed };
 }