weavatrix 0.1.4 → 0.2.0

package/src/analysis/dead-code-review.js

@@ -0,0 +1,245 @@
+// Conservative, source-free review queue for statically unreferenced code. This deliberately builds
+// on computeDead instead of inventing a second liveness model. Candidates are evidence for review,
+// never deletion instructions: framework entry, dynamic loading, reflection and public API surfaces
+// lower confidence and remain explicit in the returned record.
+import { computeDead, isFrameworkEntryFile } from "./dead-check.js";
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
+
+const CONFIDENCE_RANK = Object.freeze({ high: 0, medium: 1, low: 2 });
+const CLASSIFIED_NON_PRODUCT = Object.freeze(["generated", "mock", "story", "docs", "benchmark", "temp"]);
+const DYNAMIC_RE = /(?:\bimport\s*\(|\brequire\s*\(\s*(?!["'])|\bcreateRequire\s*\(|\b__import__\s*\(|\bimportlib\.|(?:^|[^\w.$])(?:eval|exec)\s*\()/m;
+const REFLECTION_RE = /(?:\b(?:Class\.forName|get(?:Declared)?Method|getattr|setattr|hasattr|Method\.Invoke|GetMethod|GetProcAddress|dlsym)\s*\(|\b(?:globals|locals)\s*\(\s*\)\s*\[|\breflect\.[A-Za-z_$][\w$]*\s*\()/i;
+
+const normalizedPath = (value) => String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
+const lineOf = (node) => {
+  const match = /@(\d+)$/.exec(String(node?.id || "")) || /L(\d+)/.exec(String(node?.source_location || ""));
+  return match ? Number(match[1]) : 0;
+};
+const bareLabel = (value) => String(value || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
+
+function kindOf(node) {
+  const symbolKind = String(node?.symbol_kind || "").toLowerCase();
+  if (symbolKind === "method" || symbolKind === "constructor") return "method";
+  if (["function", "function_definition", "func", "fn"].includes(symbolKind)) return "function";
+  // Old graphs may not retain symbol_kind. Only use call syntax as a compatibility fallback;
+  // member_of alone also describes fields and must never promote them to methods.
+  if (!symbolKind && /\([^)]*\)\s*$/.test(String(node?.label || ""))) return node?.member_of ? "method" : "function";
+  return "symbol";
+}
+
+function isPublicSurface(node) {
+  const visibility = String(node?.visibility || "").toLowerCase();
+  return node?.exported === true || visibility === "public" || visibility === "protected";
+}
+
+function pathAllowed(info, { includeTests, includeClassified }) {
+  if (!includeTests && hasPathClass(info, "test", "e2e")) return { ok: false, bucket: "tests" };
+  if (!includeClassified && (info?.excluded || hasPathClass(info, ...CLASSIFIED_NON_PRODUCT))) {
+    return { ok: false, bucket: "classified" };
+  }
+  return { ok: true };
+}
+
+function symbolCandidate(item, node, context) {
+  const file = normalizedPath(item.file);
+  const source = String(context.sources.get(file) || "");
+  const pathInfo = context.classify(file, source);
+  const publicSurface = isPublicSurface(node);
+  const externalEntry = context.entrySet.has(file) || isFrameworkEntryFile(file);
+  const framework = context.frameworkByFile.get(file) || null;
+  const dynamicFile = context.dynamicTargets.has(file) || DYNAMIC_RE.test(source);
+  const reflectionFile = REFLECTION_RE.test(source);
+  const kind = kindOf(node);
+  let confidence = (String(node?.visibility || "").toLowerCase() === "private" || (!publicSurface && ["method", "function"].includes(kind)))
+    ? "high" : "medium";
+  const caveats = [];
+
+  if (publicSurface) {
+    confidence = "low";
+    caveats.push("Public/exported APIs can be consumed by downstream packages, interfaces, reflection, dependency injection, templates, or configuration outside this repository.");
+  }
+  if (externalEntry || framework) {
+    confidence = "low";
+    caveats.push(framework?.reason || "This file is an externally entered or framework-owned surface; static inbound edges are not complete usage evidence.");
+  }
+  if (node?.decorated) {
+    confidence = "low";
+    caveats.push("Decorators/annotations can register this symbol without a direct caller.");
+  }
+  if (dynamicFile) {
+    confidence = "low";
+    caveats.push("The declaring file uses or is reached through dynamic loading, so the static graph can miss callers.");
+  }
+  if (reflectionFile || (publicSurface && context.repoSignals.reflection)) {
+    confidence = "low";
+    caveats.push("Reflection is present and may invoke names without a resolvable static edge.");
+  }
+
+  return {
+    id: String(item.id),
+    kind,
+    classification: publicSurface ? `public-${kind}` : kind === "method" ? "internal-method" : kind === "function" ? "internal-function" : "unreferenced-symbol",
+    file,
+    line: lineOf(node),
+    symbol: bareLabel(node?.label || item.label),
+    owner: node?.member_of || null,
+    symbolKind: node?.symbol_kind || null,
+    visibility: node?.visibility || (node?.exported ? "exported" : "internal"),
+    confidence,
+    reason: item.reason,
+    evidence: [
+      { kind: "graph", fact: "No inbound non-structural graph edge targets this symbol." },
+      { kind: "source-index", fact: "Its identifier has no second indexed occurrence that establishes a caller." },
+    ],
+    caveats,
+    publicApi: publicSurface,
+    externallyEnteredFile: externalEntry,
+    pathClasses: pathInfo.classes || [],
+    matchedPathRule: pathInfo.matchedRule || null,
+    reviewAction: "Confirm with read_source, get_dependents, exact search, framework/config inspection and tests; never auto-delete.",
+  };
+}
+
+function fileCandidate(item, symbols, context) {
+  const file = normalizedPath(item.file);
+  const source = String(context.sources.get(file) || "");
+  const pathInfo = context.classify(file, source);
+  const publicSymbols = symbols.filter((symbol) => symbol.publicApi);
+  const dynamicFile = context.dynamicTargets.has(file) || DYNAMIC_RE.test(source);
+  const reflectionFile = REFLECTION_RE.test(source);
+  // Whole-file liveness always remains at most medium: external launchers/manifests can exist outside
+  // the indexed import graph even when every internal symbol signal is otherwise strong.
+  let confidence = "medium";
+  const caveats = ["Files can be launched by scripts, plugins, manifests, framework conventions, generated consumers, or external tooling without an import edge."];
+  if (publicSymbols.length) {
+    confidence = "low";
+    caveats.push(`${publicSymbols.length} indexed public/exported symbol(s) may be consumed outside this repository.`);
+  }
+  if (dynamicFile) {
+    confidence = "low";
+    caveats.push("Dynamic loading is present in or targets this file.");
+  }
+  if (reflectionFile) {
+    confidence = "low";
+    caveats.push("Reflection is present in this file.");
+  }
+  return {
+    id: `file:${file}`,
+    kind: "file",
+    classification: "unreferenced-file",
+    file,
+    line: 1,
+    symbol: null,
+    owner: null,
+    symbolKind: null,
+    visibility: null,
+    confidence,
+    reason: item.reason,
+    evidence: [
+      { kind: "graph", fact: "No indexed module imports this file." },
+      { kind: "symbol-liveness", fact: "Every indexed symbol in the file is statically unreferenced." },
+    ],
+    caveats,
+    publicApi: publicSymbols.length > 0,
+    externallyEnteredFile: false,
+    pathClasses: pathInfo.classes || [],
+    matchedPathRule: pathInfo.matchedRule || null,
+    reviewAction: "Verify package scripts, manifests, framework discovery, dynamic loading and external consumers; never auto-delete.",
+  };
+}
+
+// Pure review model. Filesystem collection/entry inference stays in the MCP adapter so tests can pass
+// exact source maps and convention evidence without touching the working tree.
+export function computeDeadCodeReview(graph, sources, options = {}) {
+  const entrySet = options.entrySet instanceof Set ? options.entrySet : new Set(options.entrySet || []);
+  const dynamicTargets = options.dynamicTargets instanceof Set ? options.dynamicTargets : new Set(options.dynamicTargets || []);
+  const frameworkByFile = new Map((options.frameworkEvidence || []).map((entry) => [normalizedPath(entry.file), entry]));
+  const classifier = options.pathClassifier || createPathClassifier(null);
+  const classificationCache = new Map();
+  const classify = (file, source) => {
+    if (!classificationCache.has(file)) classificationCache.set(file, classifier.explain(file, { content: source }));
+    return classificationCache.get(file);
+  };
+  const repoSignals = {
+    dynamicLoading: (graph.externalImports || []).some((entry) => entry?.dynamic) || [...sources.values()].some((text) => DYNAMIC_RE.test(String(text || ""))),
+    reflection: [...sources.values()].some((text) => REFLECTION_RE.test(String(text || ""))),
+  };
+  const includeTests = options.includeTests === true;
+  const includeClassified = options.includeClassified === true;
+  const minConfidence = Object.hasOwn(CONFIDENCE_RANK, options.minConfidence) ? options.minConfidence : "medium";
+  const pathPrefix = normalizedPath(options.path || "").replace(/\/+$/, "");
+  const requestedKinds = new Set(Array.isArray(options.kinds) && options.kinds.length ? options.kinds : ["file", "function", "method", "symbol"]);
+  const context = { sources, entrySet, dynamicTargets, frameworkByFile, classify, repoSignals };
+  const dead = computeDead(graph, sources, { entrySet });
+  const nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
+  const rawSymbols = dead.deadSymbols
+    .map((item) => ({ item, node: nodesById.get(String(item.id)) }))
+    .filter((entry) => entry.node)
+    .map(({ item, node }) => symbolCandidate(item, node, context));
+  const symbolsByFile = new Map();
+  for (const candidate of rawSymbols) {
+    if (!symbolsByFile.has(candidate.file)) symbolsByFile.set(candidate.file, []);
+    symbolsByFile.get(candidate.file).push(candidate);
+  }
+  const rawFiles = dead.deadFiles.map((item) => fileCandidate(item, symbolsByFile.get(normalizedPath(item.file)) || [], context));
+  const raw = [...rawSymbols, ...rawFiles];
+  const suppressed = { tests: 0, classified: 0, confidence: 0, path: 0, kind: 0 };
+  const candidates = [];
+  for (const candidate of raw) {
+    const info = classify(candidate.file, sources.get(candidate.file));
+    const allowed = pathAllowed(info, { includeTests, includeClassified });
+    if (!allowed.ok) { suppressed[allowed.bucket] += 1; continue; }
+    if (pathPrefix && candidate.file !== pathPrefix && !candidate.file.startsWith(`${pathPrefix}/`)) { suppressed.path += 1; continue; }
+    if (!requestedKinds.has(candidate.kind)) { suppressed.kind += 1; continue; }
+    if (CONFIDENCE_RANK[candidate.confidence] > CONFIDENCE_RANK[minConfidence]) { suppressed.confidence += 1; continue; }
+    candidates.push(candidate);
+  }
+  candidates.sort((left, right) =>
+    CONFIDENCE_RANK[left.confidence] - CONFIDENCE_RANK[right.confidence]
+    || left.file.localeCompare(right.file)
+    || left.line - right.line
+    || left.id.localeCompare(right.id));
+
+  const warnings = [{
+    code: "STATIC_LIVENESS_IS_NOT_RUNTIME_PROOF",
+    message: "No static reference is not proof of dead runtime code. Review every candidate; never bulk-delete or auto-delete.",
+  }];
+  if (repoSignals.dynamicLoading) warnings.push({
+    code: "DYNAMIC_LOADING_PRESENT",
+    message: "Dynamic loading exists in the repository; static callers may be incomplete.",
+  });
+  if (repoSignals.reflection) warnings.push({
+    code: "REFLECTION_PRESENT",
+    message: "Reflection-like APIs exist in the repository; public or name-addressed symbols may be invoked without graph edges.",
+  });
+  if (suppressed.confidence) warnings.push({
+    code: "LOW_CONFIDENCE_SUPPRESSED",
+    message: `${suppressed.confidence} low-confidence candidate(s), including public/framework-sensitive code, were suppressed; set min_confidence=low to review them explicitly.`,
+  });
+
+  return {
+    candidates,
+    warnings,
+    suppressed,
+    repoSignals,
+    totals: {
+      indexedSymbols: dead.stats.symbols,
+      indexedFiles: dead.stats.files,
+      rawDeadSymbols: rawSymbols.length,
+      rawDeadFiles: rawFiles.length,
+      reviewCandidates: candidates.length,
+      byConfidence: {
+        high: candidates.filter((candidate) => candidate.confidence === "high").length,
+        medium: candidates.filter((candidate) => candidate.confidence === "medium").length,
+        low: candidates.filter((candidate) => candidate.confidence === "low").length,
+      },
+    },
+    policy: {
+      verdict: "REVIEW_REQUIRED",
+      autoDelete: false,
+      minConfidence,
+      includeTests,
+      includeClassified,
+    },
+  };
+}

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

@@ -40,6 +40,7 @@ export function computeGoDepFindings({ externalImports = [], goMod = null, nonRu
       severity: "low",
       confidence: "medium",
       title: `Unused Go module: ${r.path}`,
+      reason: "A direct go.mod requirement has no matching recorded Go import; build-tagged usage remains possible.",
       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,
@@ -57,6 +58,7 @@ export function computeGoDepFindings({ externalImports = [], goMod = null, nonRu
       severity: "medium",
       confidence: "medium",
       title: `Missing Go module: ${pkg}`,
+      reason: "A recorded Go import has no matching direct go.mod requirement or replace entry.",
       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],
@@ -123,6 +125,7 @@ export function computePyDepFindings({
         severity: d.dev ? "info" : "low",
         confidence: "low",
         title: `Unused Python dependency: ${d.name}`,
+        reason: "No recorded Python import maps to this declared distribution; import-to-distribution mapping and plugin loading are heuristic.",
         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",
@@ -144,6 +147,9 @@ export function computePyDepFindings({
       severity: present ? (testOnly ? "low" : "medium") : "low",
       confidence: present ? "medium" : "low",
       title: `Missing Python dependency: ${u.dist}`,
+      reason: present
+        ? `A recorded Python import maps to "${u.dist}", but no declared distribution covers it.`
+        : `A recorded Python import maps to "${u.dist}", but no Python dependency manifest is present; a managed runtime may provide it.`,
       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],

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", nonRuntimeRoots = [],
+  aliases = [], scope = "", manifest = "package.json", nonRuntimeRoots = [], sourceFiles = [],
 } = {}) {
   const findings = [];
   const meta = { scope: scope || ".", manifest };
@@ -101,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
@@ -112,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");
@@ -132,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;
@@ -147,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",
@@ -162,12 +183,19 @@ export function computeDepFindings({
     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],
@@ -191,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",
@@ -244,16 +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 = [],
+  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();
@@ -262,7 +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,
+      nonRuntimeRoots, sourceFiles: sourceFilesByScope.get(s),
     });
     findings.push(...r.findings);
     for (const [name, use] of r.usedPackages) usedPackages.set(`${s.root || "."}:${name}`, use);

package/src/analysis/dep-rules.js

@@ -7,10 +7,10 @@
 // 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("/")) : "");
@@ -63,7 +63,6 @@ export function buildFileImportGraph(graph, { includeTypeOnly = false, includeCo
     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 = [];
@@ -99,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) {
@@ -109,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);
@@ -120,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.
@@ -146,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/**"] }] }
@@ -180,13 +177,16 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
   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: "" })),
@@ -207,6 +207,7 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
   };
   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);
@@ -220,7 +221,9 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
       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.`,
+      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: "" })),

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