weavatrix 0.2.12 → 0.2.14

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

@@ -0,0 +1,23 @@
+import {hasPathClass} from '../../path-classification.js'
+
+export const DEAD_CODE_CONFIDENCE_RANK = Object.freeze({high: 0, medium: 1, low: 2})
+export const DYNAMIC_CODE_RE = /(?:\brequire\s*\(\s*(?!["'])|\bcreateRequire\s*\(|\b__import__\s*\(|\bimportlib\.|(?:^|[^\w.$])(?:eval|exec)\s*\()/m
+const JS_DYNAMIC_IMPORT_RE = /\bimport\s*\(/
+const JS_LIKE_PATH_RE = /\.(?:[cm]?js|jsx|[cm]?ts|tsx)$/i
+export const REFLECTION_CODE_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
+export const normalizedReviewPath = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '')
+
+export function hasDynamicCode(source, file = '') {
+    const text = String(source || '')
+    return DYNAMIC_CODE_RE.test(text) || (JS_LIKE_PATH_RE.test(String(file)) && JS_DYNAMIC_IMPORT_RE.test(text))
+}
+
+const NON_PRODUCT_CLASSES = Object.freeze(['generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
+
+export function deadCodePathAllowed(info, {includeTests, includeClassified}) {
+    if (!includeTests && hasPathClass(info, 'test', 'e2e')) return {ok: false, bucket: 'tests'}
+    if (!includeClassified && (info?.excluded || hasPathClass(info, ...NON_PRODUCT_CLASSES))) {
+        return {ok: false, bucket: 'classified'}
+    }
+    return {ok: true}
+}

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

@@ -3,14 +3,12 @@
 // 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(/^\.\//, "");
+import { createPathClassifier } from "../path-classification.js";
+import {
+  DEAD_CODE_CONFIDENCE_RANK as CONFIDENCE_RANK, hasDynamicCode,
+  REFLECTION_CODE_RE as REFLECTION_RE, deadCodePathAllowed as pathAllowed,
+  normalizedReviewPath as normalizedPath,
+} from './dead-code-review/policy.js'
 const lineOf = (node) => {
   const match = /@(\d+)$/.exec(String(node?.id || "")) || /L(\d+)/.exec(String(node?.source_location || ""));
   return match ? Number(match[1]) : 0;
@@ -32,14 +30,6 @@ function isPublicSurface(node) {
   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) || "");
@@ -48,7 +38,7 @@ function symbolCandidate(item, node, context) {
   const testOnly = item.testOnly === true;
   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 dynamicFile = context.dynamicTargets.has(file) || hasDynamicCode(source, file);
   const reflectionFile = REFLECTION_RE.test(source);
   const kind = kindOf(node);
   const exactNoReference = context.exactNoReferenceIds.has(String(item.id));
@@ -143,7 +133,7 @@ function fileCandidate(item, symbols, context) {
   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 dynamicFile = context.dynamicTargets.has(file) || hasDynamicCode(source, file);
   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.
@@ -219,7 +209,7 @@ export function computeDeadCodeReview(graph, sources, options = {}) {
     return classificationCache.get(file);
   };
   const repoSignals = {
-    dynamicLoading: (graph.externalImports || []).some((entry) => entry?.dynamic) || [...sources.values()].some((text) => DYNAMIC_RE.test(String(text || ""))),
+    dynamicLoading: (graph.externalImports || []).some((entry) => entry?.dynamic) || [...sources].some(([file, text]) => hasDynamicCode(text, file)),
     reflection: [...sources.values()].some((text) => REFLECTION_RE.test(String(text || ""))),
   };
   const includeTests = options.includeTests === true;

package/src/analysis/dep-check.js

@@ -7,47 +7,37 @@
 // script/config-text mention scanning + a config-ecosystem prefix rule, and we NEVER say "safe to
 // auto-remove", only "review".
 import { makeFinding } from "./findings.js";
+import {createScopedDepFindings} from './dependency/scoped-dependencies.js'
 
 // Packages referenced by config CONVENTION, not imports (eslint extends "airbnb" → eslint-config-airbnb).
 // Flagged only at low confidence when nothing mentions them anywhere.
-const CONFIG_ECOSYSTEM_RE =
-  /^(eslint-(config|plugin)-|@typescript-eslint\/|@eslint\/|prettier-plugin-|postcss-|autoprefixer$|tailwindcss$|babel-(plugin|preset)-|@babel\/(plugin|preset)-|stylelint-|@commitlint\/|commitlint-|remark-|rehype-|@semantic-release\/|karma-|grunt-|gulp-)/;
+const CONFIG_ECOSYSTEM_RE = /^(eslint-(config|plugin)-|@typescript-eslint\/|@eslint\/|prettier-plugin-|postcss-|autoprefixer$|tailwindcss$|babel-(plugin|preset)-|@babel\/(plugin|preset)-|stylelint-|@commitlint\/|commitlint-|remark-|rehype-|@semantic-release\/|karma-|grunt-|gulp-)/;
 
 // CLI name → package name, for script commands whose binary doesn't equal the package
 // (`tsc` comes from typescript, `depcruise` from dependency-cruiser, …).
 const BIN_PKG = {
-  tsc: "typescript",
-  depcruise: "dependency-cruiser",
-  "vue-cli-service": "@vue/cli-service",
-  ng: "@angular/cli",
-  nest: "@nestjs/cli",
-  sb: "storybook",
-  "electron-rebuild": "@electron/rebuild",
-  playwright: "@playwright/test",
+  tsc: "typescript", depcruise: "dependency-cruiser", "vue-cli-service": "@vue/cli-service",
+  ng: "@angular/cli", nest: "@nestjs/cli", sb: "storybook",
+  "electron-rebuild": "@electron/rebuild", 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"]],
+  ["next", ["react-dom"]], ["vinext", ["@vitejs/plugin-react", "@vitejs/plugin-rsc", "react-server-dom-webpack", "vite"]],
+  ["electron-vite", ["vite"]], ["@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],
+  ["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);
@@ -305,43 +295,6 @@ export function computeDepFindings({
   return { findings, usedPackages, declared: allDeclared };
 }
 
-const normScope = (root) => String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
-const ownsFile = (scope, file) => !scope || file === scope || String(file || "").startsWith(`${scope}/`);
-
-// Judge every import against its nearest ancestor package.json. This is the dependency equivalent of
-// Node's package scope and prevents nested Next/Vite apps from inheriting the root manifest by accident.
-export function computeScopedDepFindings({
-  externalImports = [], packageScopes = [], workspacePkgNames = new Set(), configTexts = new Map(),
-  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();
-  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, sourceFiles: sourceFilesByScope.get(s),
-    });
-    findings.push(...r.findings);
-    for (const [name, use] of r.usedPackages) usedPackages.set(`${s.root || "."}:${name}`, use);
-    for (const name of r.declared) declared.add(`${s.root || "."}:${name}`);
-  }
-  return { findings, usedPackages, declared };
-}
+export const computeScopedDepFindings = createScopedDepFindings(computeDepFindings)
 
 export { computeGoDepFindings, computePyDepFindings } from "./dep-check-ecosystems.js";

package/src/analysis/dep-rules.js

@@ -1,303 +1,10 @@
-// Pure structure checker (replaces dependency-cruiser's core): circular dependencies (iterative Tarjan
-// SCC + one representative cycle each), orphan files, and a small glob boundary-rule DSL evaluated over
-// the graph's file-level import edges. NO filesystem — internal-audit.js feeds it. DEPS_SECURITY_PLAN P2.
-//
-// Honest gaps vs depcruise: we don't follow imports INTO node_modules and don't run enhanced-resolve
-// (package.json#exports / webpack resolution), so some cycles it sees we can't. Cycles we DO report are
-// 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, 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 + 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;
-    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]); }
-  }
-  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).
-export function findSccs(adj) {
-  const index = new Map(), low = new Map(), onStack = new Set(), S = [];
-  let counter = 0;
-  const sccs = [];
-  for (const root of adj.keys()) {
-    if (index.has(root)) continue;
-    index.set(root, counter); low.set(root, counter); counter++;
-    S.push(root); onStack.add(root);
-    const stack = [{ v: root, ci: 0, neigh: [...(adj.get(root) || [])] }];
-    while (stack.length) {
-      const fr = stack[stack.length - 1];
-      if (fr.ci < fr.neigh.length) {
-        const w = fr.neigh[fr.ci++];
-        if (!index.has(w)) {
-          index.set(w, counter); low.set(w, counter); counter++;
-          S.push(w); onStack.add(w);
-          stack.push({ v: w, ci: 0, neigh: [...(adj.get(w) || [])] });
-        } else if (onStack.has(w)) {
-          low.set(fr.v, Math.min(low.get(fr.v), index.get(w)));
-        }
-      } else {
-        stack.pop();
-        if (stack.length) { const p = stack[stack.length - 1]; low.set(p.v, Math.min(low.get(p.v), low.get(fr.v))); }
-        if (low.get(fr.v) === index.get(fr.v)) {
-          const comp = [];
-          let w;
-          do { w = S.pop(); onStack.delete(w); comp.push(w); } while (w !== fr.v);
-          if (comp.length > 1) sccs.push(comp);
-        }
-      }
-    }
-  }
-  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) {
-  const inScc = new Set(scc);
-  const start = [...scc].sort()[0];
-  const prev = new Map([[start, null]]);
-  const q = [start];
-  while (q.length) {
-    const cur = q.shift();
-    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);
-        return [...path.reverse(), start];
-      }
-      if (!inScc.has(nxt) || prev.has(nxt)) continue;
-      prev.set(nxt, cur);
-      q.push(nxt);
-    }
-  }
-  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.
-export function findOrphans(graph, { entrySet = new Set(), externalImportFiles = new Set() } = {}) {
-  const deg = new Map();
-  for (const l of graph.links || []) {
-    if (l.relation === "contains") continue;
-    const a = fileOf(l.source), b = fileOf(l.target);
-    if (a === b) continue;
-    deg.set(a, (deg.get(a) || 0) + 1);
-    deg.set(b, (deg.get(b) || 0) + 1);
-  }
-  const out = [];
-  for (const n of graph.nodes || []) {
-    const id = String(n.id);
-    if (id.includes("#")) continue;
-    if ((deg.get(id) || 0) > 0) continue;
-    const f = n.source_file;
-    if (entrySet.has(f) || ENTRY_FILE.test(f) || TEST_FILE_RE.test(f) || NON_CODE_RE.test(f)) continue;
-    out.push({ file: f, importsExternals: externalImportFiles.has(f) });
-  }
-  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/**"] }] }
-// forbidden fires when an edge matches from AND to; allowedOnly fires when from matches and to matches NONE.
-export function globToRe(glob) {
-  // split on ** first so single-* expansion cannot touch the multi-segment wildcards
-  const parts = String(glob).split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]"));
-  let s = parts.join(".*");
-  s = s.replace(/\/\.\*\//g, "/(?:.*/)?"); // a/**/b also matches a/b (zero middle dirs)
-  s = s.replace(/^\.\*\//, "(?:.*/)?");    // **/b also matches root-level b
-  return new RegExp(`^${s}$`);
-}
-
-export function checkBoundaries(edges, rules = {}) {
-  const violations = [];
-  const forbidden = (rules.forbidden || []).map((r) => ({ ...r, fromRe: globToRe(r.from), toRe: globToRe(r.to) }));
-  const allowedOnly = (rules.allowedOnly || []).map((r) => ({ ...r, fromRe: globToRe(r.from), toRes: (Array.isArray(r.to) ? r.to : [r.to]).map(globToRe) }));
-  for (const [a, b] of edges) {
-    for (const r of forbidden) if (r.fromRe.test(a) && r.toRe.test(b)) violations.push({ name: r.name, comment: r.comment || "", severity: r.severity, from: a, to: b, kind: "forbidden" });
-    for (const r of allowedOnly) if (r.fromRe.test(a) && !r.toRes.some((re) => re.test(b))) violations.push({ name: r.name, comment: r.comment || "", severity: r.severity, from: a, to: b, kind: "allowedOnly" });
-  }
-  return violations;
-}
-
-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, 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: `${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: "" })),
-      source: "internal",
-      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 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: 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: `${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 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",
-      title: `…and ${sccs.length - MAX_CYCLE_FINDINGS} more dependency cycles`,
-      detail: `Cycle findings are capped at ${MAX_CYCLE_FINDINGS}; ${sccs.length} strongly-connected groups exist in total.`,
-      source: "internal",
-    }));
-  }
-
-  for (const o of findOrphans(graph, { entrySet, externalImportFiles })) {
-    findings.push(makeFinding({
-      category: "structure",
-      rule: "orphan-file",
-      severity: "info",
-      confidence: o.importsExternals ? "low" : "medium",
-      title: `Orphan file: ${o.file}`,
-      detail: `No repo file imports it and it imports/calls nothing in the repo${o.importsExternals ? " (it does use npm packages — possibly a standalone script or tool)" : ""}. Possibly dead, possibly an undeclared entry point.`,
-      file: o.file,
-      graphNodeId: o.file,
-      source: "internal",
-    }));
-  }
-
-  // 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({
-      category: "structure",
-      rule: "boundary-violation",
-      severity: ["critical", "high", "medium", "low", "info"].includes(v.severity) ? v.severity : "medium",
-      confidence: "high",
-      title: `Boundary violation (${v.name}): ${v.from} → ${v.to}`,
-      detail: `${v.kind === "allowedOnly" ? "Import leaves the allowed set" : "Forbidden import"}${v.comment ? `: ${v.comment}` : ""}.`,
-      file: v.from,
-      graphNodeId: v.from,
-      evidence: [{ file: v.from, line: 0, snippet: `imports ${v.to}` }],
-      source: "internal",
-    }));
-  }
-  if (violations.length > MAX_BOUNDARY_FINDINGS) {
-    findings.push(makeFinding({
-      category: "structure", rule: "boundary-violation", severity: "info", confidence: "high",
-      title: `…and ${violations.length - MAX_BOUNDARY_FINDINGS} more boundary violations`,
-      detail: `Boundary findings are capped at ${MAX_BOUNDARY_FINDINGS}; ${violations.length} edges violate the rules in total.`,
-      source: "internal",
-    }));
-  }
-
-  return {
-    findings,
-    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,
-    },
-  };
-}
+// Stable facade for structural dependency analysis.
+export {
+    buildFileImportGraph,
+    checkBoundaries,
+    findOrphans,
+    findSccs,
+    globToRe,
+    representativeCycle,
+} from './structure/dependency-graph.js'
+export {computeStructureFindings} from './structure/findings.js'

package/src/analysis/dependency/scoped-dependencies.js

@@ -0,0 +1,40 @@
+const normalizeScope = (root) => String(root || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '')
+const ownsFile = (scope, file) => !scope || file === scope || String(file || '').startsWith(`${scope}/`)
+
+// Bind the ecosystem-specific core without introducing a facade/helper import cycle.
+export function createScopedDepFindings(computeDepFindings) {
+    return function computeScopedDepFindings({
+        externalImports = [], packageScopes = [], workspacePkgNames = new Set(), configTexts = new Map(),
+        nonRuntimeRoots = [], sourceFiles = [],
+    } = {}) {
+        const scopes = packageScopes.length
+            ? packageScopes.map((scope) => ({...scope, root: normalizeScope(scope.root)})).sort((a, b) => b.root.length - a.root.length)
+            : [{root: '', manifest: 'package.json', pkg: {}, aliases: []}]
+        const importsByScope = new Map(scopes.map((scope) => [scope, []]))
+        const sourceFilesByScope = new Map(scopes.map((scope) => [scope, []]))
+        for (const item of externalImports) {
+            const owner = scopes.find((scope) => ownsFile(scope.root, item.file)) || scopes[scopes.length - 1]
+            importsByScope.get(owner).push(item)
+        }
+        for (const file of sourceFiles) {
+            const owner = scopes.find((scope) => ownsFile(scope.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()
+        for (const scope of scopes) {
+            const scopeConfig = new Map([...configTexts].filter(([file]) => configOwner.get(file) === scope))
+            const result = computeDepFindings({
+                externalImports: importsByScope.get(scope), pkg: scope.pkg || {}, workspacePkgNames,
+                configTexts: scopeConfig, aliases: scope.aliases || [], scope: scope.root,
+                manifest: scope.manifest || (scope.root ? `${scope.root}/package.json` : 'package.json'),
+                nonRuntimeRoots, sourceFiles: sourceFilesByScope.get(scope),
+            })
+            findings.push(...result.findings)
+            for (const [name, use] of result.usedPackages) usedPackages.set(`${scope.root || '.'}:${name}`, use)
+            for (const name of result.declared) declared.add(`${scope.root || '.'}:${name}`)
+        }
+        return {findings, usedPackages, declared}
+    }
+}

package/src/analysis/endpoints/common.js

@@ -0,0 +1,62 @@
+export const MAX_ENDPOINT_FILES = 3_000;
+export const MAX_ENDPOINTS = 2_000;
+export const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT", "ALL", "ANY"]);
+
+export function lineAt(text, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === "\n") line++;
+  return line;
+}
+
+// Preserve offsets and literals while hiding comments from regex extractors.
+export function maskComments(text, { hashComments = false } = {}) {
+  const chars = String(text || "").split("");
+  let quote = "", escaped = false, lineComment = false, blockComment = false;
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i], next = chars[i + 1];
+    if (lineComment) {
+      if (ch === "\n" || ch === "\r") lineComment = false;
+      else chars[i] = " ";
+      continue;
+    }
+    if (blockComment) {
+      if (ch === "*" && next === "/") { chars[i] = chars[i + 1] = " "; i++; blockComment = false; }
+      else if (ch !== "\n" && ch !== "\r") chars[i] = " ";
+      continue;
+    }
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") { quote = ch; continue; }
+    if (ch === "/" && next === "/") { chars[i] = chars[i + 1] = " "; i++; lineComment = true; continue; }
+    if (ch === "/" && next === "*") { chars[i] = chars[i + 1] = " "; i++; blockComment = true; continue; }
+    if (hashComments && ch === "#") { chars[i] = " "; lineComment = true; }
+  }
+  return chars.join("");
+}
+
+export function handlerName(expr) {
+  const source = String(expr || "").trim();
+  if (!source || /=>/.test(source) || /^\s*(async\s+)?function\b/.test(source) || /^\s*(?:async\s+)?(?:move\s+)?\|[^|]*\|/.test(source)) return "";
+  const turbofish = /(?:^|::)([A-Za-z_][\w]*)\s*::<[\s\S]*>\s*$/.exec(source);
+  if (turbofish) return turbofish[1];
+  const identifiers = source.match(/[A-Za-z_$][\w$]*/g);
+  if (!identifiers) return "";
+  const skipped = new Set(["async", "function", "await", "req", "res", "ctx", "request", "response", "next", "return"]);
+  for (let i = identifiers.length - 1; i >= 0; i--) if (!skipped.has(identifiers[i])) return identifiers[i];
+  return "";
+}
+
+export function handlerReference(expr) {
+  const source = String(expr || "").trim();
+  if (!source || /=>/.test(source) || /^\s*(async\s+)?function\b/.test(source)) return "";
+  const refs = [...source.matchAll(/([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)+)/g)];
+  return refs.length ? refs.at(-1)[1].replace(/\s+/g, "") : "";
+}
+
+export const looksLikePath = (path) => typeof path === "string" && /^\/[\w\-./:{}*$?]*$/.test(path) && !path.includes("://");
+export const cleanPath = (path) => String(path || "").replace(/\/+$/, "") || "/";
+export const normalizedFile = (file) => String(file || "").replace(/\\/g, "/").replace(/^\.\//, "");