weavatrix 0.1.3 → 0.2.0

package/src/analysis/dep-check.js

@@ -36,6 +36,18 @@ const FRAMEWORK_RUNTIME_PEERS = new Map([
   ["@cloudflare/vite-plugin", ["vite", "wrangler"]],
 ]);
 
+// Style preprocessors are compiler inputs rather than JavaScript imports. Their presence is proven by
+// source extensions in the same package scope, so do not report them as unused merely because Vite,
+// webpack, etc. load them internally. Keep this list to exact compiler/package contracts.
+const IMPLICIT_STYLE_COMPILERS = new Map([
+  ["sass", /\.(?:scss|sass)$/i],
+  ["sass-embedded", /\.(?:scss|sass)$/i],
+  ["less", /\.less$/i],
+  ["stylus", /\.styl(?:us)?$/i],
+]);
+
+const isStylesheetSpecifier = (spec) => /\.(?:css|scss|sass|less|styl(?:us)?)(?:[?#].*)?$/i.test(String(spec || ""));
+
 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);
@@ -47,7 +59,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 = [], sourceFiles = [],
 } = {}) {
   const findings = [];
   const meta = { scope: scope || ".", manifest };
@@ -68,6 +80,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.
@@ -75,9 +113,15 @@ export function computeDepFindings({
   for (const [provider, peers] of FRAMEWORK_RUNTIME_PEERS) {
     if (allDeclared.has(provider)) for (const peer of peers) frameworkRuntime.add(peer);
   }
+  const implicitCompilerUsage = new Set();
+  for (const [name, sourcePattern] of IMPLICIT_STYLE_COMPILERS) {
+    if (allDeclared.has(name) && sourceFiles.some((file) => sourcePattern.test(String(file || "")))) {
+      implicitCompilerUsage.add(name);
+    }
+  }
 
   // ---- usage index from the graph's recorded imports ----
-  const usedPackages = new Map(); // pkgName -> { files:Set, lines:Map(file→first line), kinds:Set }
+  const usedPackages = new Map(); // pkgName -> { files:Set, lines:Map(file→first line), kinds/specs:Set, typeOnly:boolean }
   let builtinUsed = false;
   for (const e of externalImports) {
     if (e.ecosystem && e.ecosystem !== "npm") continue; // go/python imports have their own checkers
@@ -86,10 +130,12 @@ export function computeDepFindings({
     if (e.builtin) { builtinUsed = true; continue; }
     if (!e.pkg) continue;
     let u = usedPackages.get(e.pkg);
-    if (!u) usedPackages.set(e.pkg, (u = { files: new Set(), lines: new Map(), kinds: new Set() }));
+    if (!u) usedPackages.set(e.pkg, (u = { files: new Set(), lines: new Map(), kinds: new Set(), specs: new Set(), typeOnly: true }));
     u.files.add(e.file);
     if (!u.lines.has(e.file)) u.lines.set(e.file, e.line || 0);
     u.kinds.add(e.kind);
+    u.specs.add(e.spec || e.pkg);
+    if (!e.typeOnly) u.typeOnly = false;
   }
 
   const scriptBlob = Object.values(pkg.scripts || {}).join("\n");
@@ -106,7 +152,7 @@ export function computeDepFindings({
   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) || frameworkRuntime.has(name)) continue;
+      if (name === selfName || usedPackages.has(name) || frameworkRuntime.has(name) || implicitCompilerUsage.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) || frameworkRuntime.has(tb) || mentioned(configBlob, tb)) continue;
@@ -121,6 +167,7 @@ export function computeDepFindings({
         severity: dev ? "info" : "low",
         confidence: dev || ecosystem ? "low" : "medium",
         title: `Unused ${section === "dependencies" ? "dependency" : section.replace(/ies$/, "y")}: ${name}`,
+        reason: "No recorded package import, package-script command, recognized config mention, framework peer contract, or implicit style-compiler input uses this declaration.",
         detail: `"${name}" is declared in ${section} but never imported in source, never referenced by a script, and not mentioned in any known config file. Dynamic/config-convention usage can't be fully ruled out — review before removing.`,
         package: name,
         source: "internal",
@@ -134,13 +181,21 @@ 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));
+    const stylesheetOnly = [...use.specs].length > 0 && [...use.specs].every(isStylesheetSpecifier);
+    const usageReason = stylesheetOnly
+      ? `Direct stylesheet import(s) resolve through "${name}"; CSS-only imports are build/runtime inputs even without JavaScript bindings.`
+      : use.typeOnly
+        ? `Direct type-only import(s) resolve through "${name}"; the compiler still requires a declared package.`
+        : `Direct source import(s) resolve through "${name}", but the nearest package manifest does not declare it.`;
     findings.push(makeFinding({
       category: "unused",
       rule: "missing-dep",
       severity: testOnly ? "low" : "medium",
       confidence: "high",
       title: `Missing dependency: ${name}`,
+      reason: usageReason,
       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],
@@ -164,6 +219,7 @@ export function computeDepFindings({
       severity: "info",
       confidence: "high",
       title: `Duplicate declaration: ${name}`,
+      reason: `The same package is declared in multiple manifest sections: ${ss.join(" + ")}.`,
       detail: `"${name}" is declared in ${ss.join(" + ")} — npm resolves one of them; keep a single section.`,
       package: name,
       source: "internal",
@@ -176,6 +232,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,15 +273,21 @@ 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 = [], sourceFiles = [],
 } = {}) {
   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, []]));
+  const sourceFilesByScope = 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);
   }
+  for (const file of sourceFiles) {
+    const owner = scopes.find((s) => ownsFile(s.root, file)) || scopes[scopes.length - 1];
+    sourceFilesByScope.get(owner).push(file);
+  }
   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();
@@ -233,6 +296,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, sourceFiles: sourceFilesByScope.get(s),
     });
     findings.push(...r.findings);
     for (const [name, use] of r.usedPackages) usedPackages.set(`${s.root || "."}:${name}`, use);
@@ -241,146 +305,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";

package/src/analysis/dep-rules.js

@@ -7,26 +7,26 @@
 // built from EXTRACTED import edges → high confidence.
 import { makeFinding } from "./findings.js";
 import { ENTRY_FILE } from "./dead-check.js";
-
+import { formatRepresentativeCycle } from "./cycle-route.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;
-
 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, { includeTypeOnly = false } = {}) {
+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 runtimeAdj = new Map();       // runtime/value imports only
-  const allAdj = new Map();           // runtime + type-only, used to describe architectural coupling
+  const allAdj = new Map();           // runtime + compile-time-only, used to describe architectural coupling
   const edges = [];
   const allEdges = [];
   const typeOnlyEdges = [];
-  const runtimeSeen = new Set(), allSeen = new Set(), typeSeen = new Set();
+  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()));
@@ -39,25 +39,30 @@ export function buildFileImportGraph(graph, { includeTypeOnly = false } = {}) {
     if (a.endsWith(".go") && b.endsWith(".go") && dirOf(a) === dirOf(b)) continue;
     const key = `${a}\0${b}`;
     if (!allSeen.has(key)) { allSeen.add(key); add(allAdj, a, b); allEdges.push([a, b]); }
-    if (l.typeOnly === true) {
-      if (!typeSeen.has(key)) { typeSeen.add(key); typeOnlyEdges.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]); }
   }
   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 ? allAdj : runtimeAdj,
-    edges: includeTypeOnly ? allEdges : edges,
+    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).
 export function findSccs(adj) {
   const index = new Map(), low = new Map(), onStack = new Set(), S = [];
@@ -93,7 +98,6 @@ export function findSccs(adj) {
   }
   return sccs;
 }
-
 // One representative (shortest) cycle through an SCC's lexicographically-first file — a readable path,
 // not the full Johnson enumeration (which explodes combinatorially on big tangles).
 export function representativeCycle(adj, scc) {
@@ -103,7 +107,7 @@ export function representativeCycle(adj, scc) {
   const q = [start];
   while (q.length) {
     const cur = q.shift();
-    for (const nxt of adj.get(cur) || []) {
+    for (const nxt of [...(adj.get(cur) || [])].sort()) {
       if (nxt === start) {
         const path = [];
         for (let c = cur; c != null; c = prev.get(c)) path.push(c);
@@ -114,9 +118,9 @@ export function representativeCycle(adj, scc) {
       q.push(nxt);
     }
   }
-  return [...scc, scc[0]]; // unreachable in a true SCC; safe fallback
+  const fallback = [...scc].sort();
+  return [...fallback, fallback[0]]; // unreachable in a true SCC; deterministic safe fallback
 }
-
 // Orphans: file nodes with ZERO non-contains graph degree (nothing in, nothing out — imports, calls,
 // references all collapsed to files). Entries/tests/config-data are exempt. A file that DOES import
 // npm packages (externalImports) is a working script, not an island — confidence drops, not the verdict.
@@ -140,7 +144,6 @@ export function findOrphans(graph, { entrySet = new Set(), externalImportFiles =
   }
   return out;
 }
-
 // Boundary DSL — the useful subset of depcruise's forbidden rules, as plain JSON globs:
 //   { "forbidden":  [{ "name", "comment"?, "severity"?, "from": "main/**", "to": "renderer/**" }],
 //     "allowedOnly":[{ "name", "comment"?, "severity"?, "from": "src/ui/**", "to": ["src/ui/**", "src/shared/**"] }] }
@@ -167,22 +170,23 @@ 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, allAdj, allEdges, typeOnlyEdges } = 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);
+    const cycleRoute = formatRepresentativeCycle(cycle);
     findings.push(makeFinding({
       category: "structure",
       rule: "circular-dep",
       severity: scc.length > 4 ? "high" : "medium",
       confidence: "high",
       title: `Circular dependency: ${scc.length} files`,
-      detail: `${cycle.join(" → ")}${scc.length + 1 > cycle.length ? ` (representative loop; the tangle spans ${scc.length} files)` : ""}. Break the cycle by extracting the shared piece or inverting one import.`,
+      detail: `${cycleRoute}${scc.length + 1 > cycle.length ? ` (representative loop; the tangle spans ${scc.length} files)` : ""}. Break the cycle by extracting the shared piece or inverting one import.`,
+      cycleRoute,
+      cycleMembers: [...scc].sort(),
       file: cycle[0],
       graphNodeId: cycle[0],
       evidence: cycle.map((f) => ({ file: f, line: 0, snippet: "" })),
@@ -191,33 +195,40 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
     }));
   }
 
-  // A TypeScript `import type` is erased before runtime. It can still reveal architectural coupling, but
-  // it cannot create an initialization-order/runtime cycle. Report SCCs that grow only because of type
-  // edges separately and at info severity so agents do not churn working code to fix a phantom hazard.
+  // 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 typeCouplings = allSccs.filter((s) => !runtimeKeys.has([...s].sort().join("\0")));
+  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 typeCouplings.slice(0, MAX_CYCLE_FINDINGS)) {
+  for (const scc of compileTimeCouplings.slice(0, MAX_CYCLE_FINDINGS)) {
     const cycle = representativeCycle(allAdj, scc);
+    const cycleRoute = formatRepresentativeCycle(cycle);
     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: "type-coupling",
+      rule: typeSpecific ? "type-coupling" : "compile-time-coupling",
       severity: "info",
       confidence: "high",
-      title: `${containsRuntimeCycle ? "Type imports expand dependency coupling" : "Type-induced dependency cycle (no runtime cycle)"}: ${scc.length} files`,
-      detail: `${cycle.join(" → ")}. This strongly-connected group needs type-only edges to close; it contains ${runtimeInside} runtime edge(s) and ${typeInside} type-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.`,
+      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: `${cycleRoute}. 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.`,
+      cycleRoute,
+      cycleMembers: [...scc].sort(),
       file: cycle[0],
       graphNodeId: cycle[0],
       evidence: cycle.map((f) => ({ file: f, line: 0, snippet: "" })),
       source: "internal",
-      fixHint: "review the shared type ownership only if the coupling impedes changes; no runtime-cycle fix is required",
+      fixHint: "review the compile-time ownership only if the coupling impedes changes; no runtime-cycle fix is required",
     }));
   }
   if (sccs.length > MAX_CYCLE_FINDINGS) {
@@ -275,11 +286,16 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
       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,
-      typeCouplings: typeCouplings.length,
-      largestTypeCoupling: typeCouplings[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,8 +1,8 @@
 // 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 } from "node:fs";
-import { isTestPath } from "../graph/graph-filter.js";
 import { createRepoBoundary } from "../repo-path.js";
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
 import { listRepoFiles } from "./internal-audit.collect.js";
 import { stripNonCode, bodyEndLineCount, tokenize, fingerprints, extractLargeStrings } from "./duplicates.tokenize.js";
 
@@ -113,9 +113,19 @@ function symbolRanges(graph) {
   return byFile;
 }
 
+function loadGraph(graphInput) {
+  if (graphInput && typeof graphInput === "object" && !Array.isArray(graphInput)) {
+    return { nodes: Array.isArray(graphInput.nodes) ? graphInput.nodes : [] };
+  }
+  if (typeof graphInput !== "string" || !graphInput) throw new TypeError("graph path or graph object is required");
+  const parsed = JSON.parse(readFileSync(graphInput, "utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("graph must be an object");
+  return { nodes: Array.isArray(parsed.nodes) ? parsed.nodes : [] };
+}
+
 export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   const includeStrings = !!opts.includeStrings;
-  const graph = JSON.parse(readFileSync(graphJsonPath, "utf8"));
+  const graph = loadGraph(graphJsonPath);
   const byFile = symbolRanges(graph);
   // 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
@@ -126,6 +136,18 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   for (const [file, arr] of byFile) if (allowedFiles.has(file)) graphSymbols += arr.length;
   const frags = [];
   const boundary = createRepoBoundary(repoPath);
+  const classifier = createPathClassifier(repoPath);
+  const classificationByFile = new Map();
+  const classify = (file, content) => {
+    if (!classificationByFile.has(file)) classificationByFile.set(file, classifier.explain(file, { content }));
+    return classificationByFile.get(file);
+  };
+  const classificationFields = (info) => ({
+    test: hasPathClass(info, "test", "e2e"),
+    classes: info.classes,
+    excluded: info.excluded,
+    matchedRule: info.matchedRule,
+  });
   for (const [file, syms] of byFile) {
     if (!allowedFiles.has(file)) continue;
     const resolved = boundary.resolve(file);
@@ -134,6 +156,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
     let lines;
     try { lines = readFileSync(full, "utf8").split(/\r?\n/); } catch { continue; }
     const py = /\.py$/i.test(file);
+    const pathInfo = classify(file, lines.join("\n"));
     for (let i = 0; i < syms.length; i++) {
       const start = syms[i].line;
       // hard cap first (next symbol, or EOF, whichever comes first, ≤ MAX_BODY_LINES) …
@@ -150,7 +173,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       frags.push({
         id: syms[i].id, label: syms[i].label, file, start, end,
         n: toks.strict.length,
-        test: isTestPath(file),
+        ...classificationFields(pathInfo),
         fp: { strict: fingerprints(toks.strict), renamed: fingerprints(toks.renamed) },
       });
     }
@@ -164,7 +187,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
         if (toks.strict.length < FLOOR_TOKENS) return;
         frags.push({
           id: `${file}#str@${startLine}`, label: `${base}:${startLine} ~${endLine - startLine + 1}-line string`,
-          file, start: startLine, end: endLine, n: toks.strict.length, test: isTestPath(file), kind: "string",
+          file, start: startLine, end: endLine, n: toks.strict.length, ...classificationFields(pathInfo), kind: "string",
           fp: { strict: fingerprints(toks.strict), renamed: fingerprints(toks.renamed) },
         });
       };
@@ -188,13 +211,15 @@ 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());
-  const assetFiles = repoFiles.filter((file) => WINDOW_EXTS.test(file)).slice(0, MAX_ASSET_FILES);
+  const allAssetFiles = repoFiles.filter((file) => WINDOW_EXTS.test(file));
+  const assetFiles = allAssetFiles.slice(0, MAX_ASSET_FILES);
   for (const file of assetFiles) {
     if (symFiles.has(file)) continue;
     const resolved = boundary.resolve(file);
     if (!resolved.ok) continue;
     let lines;
     try { lines = readFileSync(resolved.path, "utf8").split(/\r?\n/); } catch { continue; }
+    const pathInfo = classify(file, lines.join("\n"));
     for (let start = 1; start <= lines.length; start += WINDOW_LINES) {
       const end = Math.min(start + WINDOW_LINES - 1, lines.length);
       if (end - start < 2) continue;
@@ -202,7 +227,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       if (toks.strict.length < FLOOR_TOKENS) continue;
       frags.push({
         id: `${file}#win@${start}`, label: `${file.split("/").pop()}:${start}-${end}`, file, start, end,
-        n: toks.strict.length, test: isTestPath(file),
+        n: toks.strict.length, ...classificationFields(pathInfo),
         fp: { strict: fingerprints(toks.strict), renamed: fingerprints(toks.renamed) },
       });
     }
@@ -211,5 +236,20 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   const nameTwins = opts.nameTwins ? computeNameTwins(frags) : null;
   // fp sets are worker-internal — strip them from the payload that crosses the thread boundary
   const slim = frags.map(({ fp, ...rest }) => rest);
-  return { ok: true, frags: slim, modes, ...(nameTwins ? { nameTwins } : {}), graphSymbols, floors: { tokens: FLOOR_TOKENS, sim: FLOOR_SIM * 100 } };
+  return {
+    ok: true,
+    frags: slim,
+    modes,
+    ...(nameTwins ? { nameTwins } : {}),
+    graphSymbols,
+    completeness: {
+      assetFiles: {
+        total: allAssetFiles.length,
+        scanned: assetFiles.length,
+        truncated: allAssetFiles.length > assetFiles.length,
+      },
+      nameTwinsTruncated: !!nameTwins && nameTwins.length >= 200,
+    },
+    floors: { tokens: FLOOR_TOKENS, sim: FLOOR_SIM * 100 },
+  };
 }