weavatrix 0.1.2 → 0.1.4

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", nonRuntimeRoots = [],
+} = {}) {
   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,46 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
   };
   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.
+  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 +132,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 +151,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
         package: name,
         source: "internal",
         fixHint: `npm uninstall ${name} (after confirming no config/CLI usage)`,
+        ...meta,
       }));
     }
   }
@@ -102,6 +160,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
   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",
@@ -109,13 +168,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 +194,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,
     }));
   }
 
@@ -142,6 +203,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
   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
@@ -156,6 +218,7 @@ export function computeDepFindings({ externalImports = [], pkg = {}, workspacePk
       file: e.file,
       line: e.line || 0,
       source: "internal",
+      ...meta,
     }));
   }
   if (unresolvedCount > unresolvedSeen.size) {
@@ -167,144 +230,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 TEST_PATH_RE = /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z0-9]+$|_test\.go$/i;
+const normScope = (root) => String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+const ownsFile = (scope, file) => !scope || file === scope || String(file || "").startsWith(`${scope}/`);
 
-// ---- 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 }
+// 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(),
+  nonRuntimeRoots = [],
+} = {}) {
+  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) {
-    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);
+    const owner = scopes.find((s) => ownsFile(s.root, e.file)) || scopes[scopes.length - 1];
+    importsByScope.get(owner).push(e);
   }
-
-  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}`,
-    }));
+  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"),
+      nonRuntimeRoots,
+    });
+    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, declared };
+  return { findings, usedPackages, 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() } = {}) {
-  const findings = [];
-  const deps = (pyManifest && pyManifest.deps) || [];
-  const present = !!(pyManifest && pyManifest.present);
-  const declared = new Set(deps.map((d) => pyNorm(d.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 (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) {
-    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 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}")` : ""}.`,
-      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)`,
-    }));
-  }
-  return { findings, declared };
-}
+export { computeGoDepFindings, computePyDepFindings } from "./dep-check-ecosystems.js";

package/src/analysis/dep-rules.js

@@ -7,7 +7,6 @@
 // built from EXTRACTED import edges → high confidence.
 import { makeFinding } from "./findings.js";
 import { ENTRY_FILE } from "./dead-check.js";
-
 const TEST_FILE_RE = /(^|[/])(test|tests|__tests__|spec|e2e|__mocks__)([/]|$)|[._-](test|spec)\.[a-z0-9]+$/i;
 // config/data/docs: never "orphans" — nothing imports them by design
 const NON_CODE_RE = /\.(json|ya?ml|sh|ps1|md|txt|html?|css|scss|less)$|(^|[/])(dockerfile|containerfile)/i;
@@ -15,24 +14,54 @@ const NON_CODE_RE = /\.(json|ya?ml|sh|ps1|md|txt|html?|css|scss|less)$|(^|[/])(d
 const ep = (v) => String(v && typeof v === "object" ? v.id : v);
 const fileOf = (v) => { const s = ep(v); const h = s.indexOf("#"); return h < 0 ? s : s.slice(0, h); };
 const dirOf = (f) => (f.includes("/") ? f.slice(0, f.lastIndexOf("/")) : "");
-
 // File-level import adjacency. Go same-directory edges are excluded: a Go package IS the directory, the
 // compiler forbids real cross-package cycles, and our suffix-fallback Go resolution could fake them.
-export function buildFileImportGraph(graph) {
+export function buildFileImportGraph(graph, { includeTypeOnly = false, includeCompileOnly = false } = {}) {
   const fileIds = new Set();
   for (const n of graph.nodes || []) if (!String(n.id).includes("#")) fileIds.add(String(n.id));
-  const adj = new Map();
+  const runtimeAdj = new Map();       // runtime/value imports only
+  const allAdj = new Map();           // runtime + compile-time-only, used to describe architectural coupling
   const edges = [];
+  const allEdges = [];
+  const typeOnlyEdges = [];
+  const compileOnlyEdges = [];
+  const compileTimeEdges = [];
+  const runtimeSeen = new Set(), allSeen = new Set(), typeSeen = new Set(), compileSeen = new Set(), compileTimeSeen = new Set();
+  const add = (map, a, b) => {
+    let set = map.get(a);
+    if (!set) map.set(a, (set = new Set()));
+    set.add(b);
+  };
   for (const l of graph.links || []) {
     if (l.relation !== "imports" && l.relation !== "re_exports") continue;
     const a = ep(l.source), b = ep(l.target);
     if (!fileIds.has(a) || !fileIds.has(b) || a === b) continue;
     if (a.endsWith(".go") && b.endsWith(".go") && dirOf(a) === dirOf(b)) continue;
-    let set = adj.get(a);
-    if (!set) adj.set(a, (set = new Set()));
-    if (!set.has(b)) { set.add(b); edges.push([a, b]); }
+    const key = `${a}\0${b}`;
+    if (!allSeen.has(key)) { allSeen.add(key); add(allAdj, a, b); allEdges.push([a, b]); }
+    if (l.typeOnly === true || l.compileOnly === true) {
+      if (l.typeOnly === true && !typeSeen.has(key)) { typeSeen.add(key); typeOnlyEdges.push([a, b]); }
+      if (l.compileOnly === true && !compileSeen.has(key)) { compileSeen.add(key); compileOnlyEdges.push([a, b]); }
+      if (!compileTimeSeen.has(key)) { compileTimeSeen.add(key); compileTimeEdges.push([a, b]); }
+      continue;
+    }
+    if (!runtimeSeen.has(key)) { runtimeSeen.add(key); add(runtimeAdj, a, b); edges.push([a, b]); }
   }
-  return { fileIds, adj, edges };
+  const pureTypeOnlyEdges = typeOnlyEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`));
+  const pureCompileOnlyEdges = compileOnlyEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`));
+  const pureCompileTimeEdges = compileTimeEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`));
+  return {
+    fileIds,
+    adj: includeTypeOnly || includeCompileOnly ? allAdj : runtimeAdj,
+    edges: includeTypeOnly || includeCompileOnly ? allEdges : edges,
+    runtimeAdj,
+    runtimeEdges: edges,
+    allAdj,
+    allEdges,
+    typeOnlyEdges: pureTypeOnlyEdges,
+    compileOnlyEdges: pureCompileOnlyEdges,
+    compileTimeEdges: pureCompileTimeEdges,
+  };
 }
 
 // Iterative Tarjan (deep graphs must not blow the JS stack). Returns only non-trivial SCCs (size > 1).
@@ -144,12 +173,10 @@ export function checkBoundaries(edges, rules = {}) {
 
 const MAX_CYCLE_FINDINGS = 50;
 const MAX_BOUNDARY_FINDINGS = 100;
-
 // Assemble everything into unified Findings. rules comes from the repo's .weavatrix-deps.json (optional).
 export function computeStructureFindings(graph, { rules = {}, entrySet = new Set(), externalImportFiles = new Set() } = {}) {
-  const { adj, edges } = buildFileImportGraph(graph);
+  const { adj, edges, allAdj, allEdges, typeOnlyEdges, compileOnlyEdges, compileTimeEdges } = buildFileImportGraph(graph);
   const findings = [];
-
   const sccs = findSccs(adj).sort((a, b) => b.length - a.length);
   for (const scc of sccs.slice(0, MAX_CYCLE_FINDINGS)) {
     const cycle = representativeCycle(adj, scc);
@@ -167,6 +194,40 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
       fixHint: "extract the shared code into a module both sides import, or invert the weaker dependency",
     }));
   }
+
+  // TypeScript `import type` and Rust module/use edges are compile-time coupling. They can reveal real
+  // architecture, but cannot create an initialization-order/runtime cycle. Report SCCs that require
+  // either classification separately so agents do not churn working code for a phantom runtime hazard.
+  const runtimeKeys = new Set(sccs.map((s) => [...s].sort().join("\0")));
+  const allSccs = findSccs(allAdj).sort((a, b) => b.length - a.length);
+  const compileTimeCouplings = allSccs.filter((s) => !runtimeKeys.has([...s].sort().join("\0")));
+  const edgeCountIn = (scc, list) => {
+    const inside = new Set(scc);
+    return list.reduce((n, [a, b]) => n + (inside.has(a) && inside.has(b) ? 1 : 0), 0);
+  };
+  for (const scc of compileTimeCouplings.slice(0, MAX_CYCLE_FINDINGS)) {
+    const cycle = representativeCycle(allAdj, scc);
+    const runtimeInside = edgeCountIn(scc, edges);
+    const typeInside = edgeCountIn(scc, typeOnlyEdges);
+    const compileInside = edgeCountIn(scc, compileOnlyEdges);
+    const containsRuntimeCycle = sccs.some((runtime) => runtime.every((f) => scc.includes(f)));
+    const typeSpecific = compileInside === 0;
+    findings.push(makeFinding({
+      category: "structure",
+      rule: typeSpecific ? "type-coupling" : "compile-time-coupling",
+      severity: "info",
+      confidence: "high",
+      title: `${containsRuntimeCycle
+        ? (typeSpecific ? "Type imports expand dependency coupling" : "Compile-time edges expand dependency coupling")
+        : (typeSpecific ? "Type-induced dependency cycle (no runtime cycle)" : "Compile-time dependency cycle (no runtime cycle)")}: ${scc.length} files`,
+      detail: `${cycle.join(" → ")}. This strongly-connected group needs compile-time-only edges to close; it contains ${runtimeInside} runtime edge(s), ${typeInside} type-only edge(s), and ${compileInside} compile-only edge(s)${containsRuntimeCycle ? ", with a smaller runtime cycle reported separately" : ", while its runtime import graph is acyclic"}. Treat this as design coupling, not an initialization-order failure.`,
+      file: cycle[0],
+      graphNodeId: cycle[0],
+      evidence: cycle.map((f) => ({ file: f, line: 0, snippet: "" })),
+      source: "internal",
+      fixHint: "review the compile-time ownership only if the coupling impedes changes; no runtime-cycle fix is required",
+    }));
+  }
   if (sccs.length > MAX_CYCLE_FINDINGS) {
     findings.push(makeFinding({
       category: "structure", rule: "circular-dep", severity: "info", confidence: "high",
@@ -190,6 +251,8 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
     }));
   }
 
+  // Architecture boundaries describe executable dependencies by default. Type-only contract sharing is
+  // visible in typeCouplings above, but must not be presented as a runtime layer violation.
   const violations = checkBoundaries(edges, rules);
   for (const v of violations.slice(0, MAX_BOUNDARY_FINDINGS)) {
     findings.push(makeFinding({
@@ -216,6 +279,22 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
 
   return {
     findings,
-    stats: { importEdges: edges.length, cycles: sccs.length, largestCycle: sccs[0]?.length || 0, orphans: findings.filter((f) => f.rule === "orphan-file").length, boundaryViolations: violations.length },
+    stats: {
+      importEdges: allEdges.length,
+      runtimeImportEdges: edges.length,
+      typeOnlyImportEdges: typeOnlyEdges.length,
+      compileOnlyImportEdges: compileOnlyEdges.length,
+      compileTimeImportEdges: compileTimeEdges.length,
+      cycles: sccs.length,
+      runtimeCycles: sccs.length,
+      largestCycle: sccs[0]?.length || 0,
+      // Backward-compatible aliases remain for edgeTypesV 1 consumers.
+      typeCouplings: compileTimeCouplings.length,
+      largestTypeCoupling: compileTimeCouplings[0]?.length || 0,
+      compileTimeCouplings: compileTimeCouplings.length,
+      largestCompileTimeCoupling: compileTimeCouplings[0]?.length || 0,
+      orphans: findings.filter((f) => f.rule === "orphan-file").length,
+      boundaryViolations: violations.length,
+    },
   };
 }

package/src/analysis/duplicates.compute.js

@@ -1,9 +1,9 @@
 // duplicates.compute.js — fragment extraction, inverted-index pairing, and the computeDuplicates
 // pipeline (split from duplicates.js; see the facade there for the full algorithm overview).
-import { readFileSync, readdirSync } from "node:fs";
-import { join, extname } from "node:path";
+import { readFileSync } from "node:fs";
 import { isTestPath } from "../graph/graph-filter.js";
 import { createRepoBoundary } from "../repo-path.js";
+import { listRepoFiles } from "./internal-audit.collect.js";
 import { stripNonCode, bodyEndLineCount, tokenize, fingerprints, extractLargeStrings } from "./duplicates.tokenize.js";
 
 const FLOOR_TOKENS = 30;   // fragments below this never enter the index (UI slider min)
@@ -17,20 +17,7 @@ const WINDOW_EXTS = /\.(css|scss|sass|less|styl|html?|md|markdown|mdx|vue|svelte
 const WINDOW_LINES = 24;   // non-overlapping block size for windowed files
 // Asset files are DEDUP-ONLY — they are NOT put in the code graph (that would score md/css as fake
 // "methods" in Health and clutter the GUI board), so the clone scanner finds them by walking the repo.
-const WALK_SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", "vendor", "weavatrix-graphs", ".next", "out", "__pycache__", ".venv", "venv", "site-packages"]);
 const MAX_ASSET_FILES = 4000;
-function walkAssets(root, dir, acc, depth) {
-  if (depth > 40 || acc.length >= MAX_ASSET_FILES) return acc;
-  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
-  for (const e of entries) {
-    if (acc.length >= MAX_ASSET_FILES) break;
-    if (e.name.startsWith(".") || WALK_SKIP.has(e.name)) continue;
-    const full = join(dir, e.name);
-    if (e.isDirectory()) walkAssets(root, full, acc, depth + 1);
-    else if (WINDOW_EXTS.test(e.name)) acc.push(full.slice(root.length + 1).replace(/\\/g, "/"));
-  }
-  return acc;
-}
 // Fingerprints shared by MORE than this many fragments are ubiquitous boilerplate and are excluded
 // from BOTH the shared count AND the union (so jaccard stays honest — see pairsForMode). Set well
 // above realistic clone multiplicity: N byte-identical copies each put all their fingerprints in
@@ -55,7 +42,7 @@ function computeNameTwins(frags) {
   frags.forEach((f, i) => {
     if (f.kind === "string") return;
     const name = String(f.label || "").trim().replace(/\(\)$/, "");
-    if (name.length < 5 || !/^[A-Za-z_$][\w$]*$/.test(name) || TWIN_STOP.has(name.toLowerCase())) return;
+    if (name.length < 5 || !/^[A-Za-z_$][\w$]*$/.test(name) || TWIN_STOP.has(name.toLowerCase()) || /^do_(?:get|post|put|patch|delete|head|options)$/i.test(name)) return;
     const key = name.toLowerCase();
     let a = byName.get(key); if (!a) byName.set(key, (a = []));
     a.push(i);
@@ -66,15 +53,18 @@ function computeNameTwins(frags) {
     const files = new Set(idxs.map((i) => frags[i].file));
     if (files.size < 2 || idxs.length > 12) continue; // single-file overloads / framework-name explosions
     let simMin = 1, simMax = 0;
+    const pairs = [];
     for (let a = 0; a < idxs.length; a++) for (let b = a + 1; b < idxs.length; b++) {
       if (frags[idxs[a]].file === frags[idxs[b]].file) continue;
       const s = jac(frags[idxs[a]].fp.renamed, frags[idxs[b]].fp.renamed);
       if (s < simMin) simMin = s;
       if (s > simMax) simMax = s;
+      pairs.push({ a: idxs[a], b: idxs[b], similarity: Math.round(s * 100) });
     }
     out.push({
       label: String(frags[idxs[0]].label || "").replace(/\(\)$/, ""), members: idxs, files: files.size,
       simMin: Math.round(simMin * 100), simMax: Math.round(simMax * 100),
+      pairs,
       tokens: idxs.reduce((n, i) => n + frags[i].n, 0),
     });
   }
@@ -130,11 +120,14 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   // total symbol nodes in the graph — 0 means a file-only graph (built by an older builder before
   // symbol extraction, or a stale graph): clone detection has nothing to work with, and the UI must
   // say "rebuild the graph" instead of the misleading "no clones at these thresholds".
+  const repoFiles = listRepoFiles(repoPath);
+  const allowedFiles = new Set(repoFiles);
   let graphSymbols = 0;
-  for (const arr of byFile.values()) graphSymbols += arr.length;
+  for (const [file, arr] of byFile) if (allowedFiles.has(file)) graphSymbols += arr.length;
   const frags = [];
   const boundary = createRepoBoundary(repoPath);
   for (const [file, syms] of byFile) {
+    if (!allowedFiles.has(file)) continue;
     const resolved = boundary.resolve(file);
     if (!resolved.ok) continue;
     const full = resolved.path;
@@ -195,7 +188,8 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   // ---- windowed fragments for symbol-less file types (CSS/HTML/MD/…), found by walking the repo (NOT the
   // graph — assets are dedup-only). Each file is sliced into WINDOW_LINES blocks and fingerprinted.
   const symFiles = new Set(byFile.keys());
-  for (const file of walkAssets(repoPath, repoPath, [], 0)) {
+  const assetFiles = repoFiles.filter((file) => WINDOW_EXTS.test(file)).slice(0, MAX_ASSET_FILES);
+  for (const file of assetFiles) {
     if (symFiles.has(file)) continue;
     const resolved = boundary.resolve(file);
     if (!resolved.ok) continue;