weavatrix 0.3.12 → 0.3.14

package/README.md

@@ -12,9 +12,12 @@ questions. **34 network-free tools. No repository data leaves your machine.**
 - Source: [github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
 - npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix <repoRoot>`
 
-This package is the complete offline engine under the MIT license and initiates no outbound HTTP.
-Every network capability lives in the separately versioned `weavatrix-online` superset, which depends
-on this core through a supported extension API. The split is documented in
+This package is the complete offline engine under the MIT license: it reads and analyzes your code,
+initiates no outbound HTTP, and never edits your source. It is the read-only base of a layered stack —
+add [`weavatrix-refactor`](https://github.com/sergii-ziborov/weavatrix-refactor) (Apache-2.0) to apply
+hash-verified, reversible edits, or [`weavatrix-online`](https://github.com/sergii-ziborov/weavatrix-online)
+for authorized Cloud or self-hosted sync. Each is an optional superset that depends on this core through
+a supported extension API; the offline/online split is documented in
 [docs/adr/0001-v0.3-offline-online-split.md](docs/adr/0001-v0.3-offline-online-split.md).
 
 ## Install
@@ -125,7 +128,9 @@ The 34 methods project the same reusable graph into the smallest view a task nee
 - **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as `graph.prev.json`).
 - **retarget** *(in `offline`, absent from `pinned`)* — `open_repo`, `list_known_repos`.
 - **crossrepo** *(in `offline`, absent from `pinned`)* — `trace_api_contract` (joins routes to client
-  call-sites across registered local graphs; reads no source).
+  call-sites across registered local graphs; reads no source). Results are compact and paginated by
+  default (`page_size`, opaque `cursor`, and bounded `per_item_limit` samples); `response_detail="full"`
+  is an explicit opt-in and remains paginated.
 
 Every finding is review evidence, never an auto-delete verdict: `find_dead_code` /
 `run_audit category=unused` always return `REVIEW_REQUIRED` with `autoDelete:false`. Typecheck, tests

package/docs/releases/v0.3.13.md

@@ -0,0 +1,34 @@
+# Weavatrix 0.3.13
+
+0.3.13 fixes two misleading verification and graph-path signals found while
+dogfooding a real duplicate-removal refactor. It also bounds cross-repository
+contract responses with revision-bound pagination.
+
+## Honest refactor verification
+
+- `verified_change` no longer reports an enabled duplicate ratchet as
+  `SKIPPED: duplicate ratchet disabled` during the planning phase. An enabled
+  plan now reports `PLANNED`, `enabled: true`, and states that the ratchet runs
+  during `phase="verify"`. An explicit `duplicate_ratchet: false` remains the
+  only disabled state.
+- `shortest_path` remains an undirected connectivity query, but every rendered
+  hop now preserves the stored graph-edge direction. Reverse traversal renders
+  `<--imports--` or `<--calls--` instead of inventing a forward dependency.
+  Repeated and generic file names are widened in both the header and hop lines.
+
+## Bounded cross-repository contract evidence
+
+- `trace_api_contract` response schema v4 returns compact, paginated evidence
+  by default. `page_size`, `per_item_limit`, and a revision/filter-bound opaque
+  `cursor` keep responses bounded; `response_detail="full"` remains an explicit
+  opt-in and is still paginated.
+- Invalid, stale, or cross-query cursors fail closed with `INVALID_CURSOR`.
+- Repository graph reconciliation now reuses a persisted fresh graph before
+  invoking a rebuild, while stale or failed refreshes retain their explicit
+  completeness status.
+
+## Layer compatibility
+
+The read-only core keeps its 34-tool surface and `weavatrix.edit-plan.v1`
+contract unchanged. `weavatrix-refactor` 0.1.1 and `weavatrix-online` 0.2.0
+are the paired upper-layer releases for this core version.

package/docs/releases/v0.3.14.md

@@ -0,0 +1,37 @@
+# Weavatrix 0.3.14
+
+0.3.14 is a Repo Lens dogfood hardening release. It keeps the 34-tool,
+network-free Core surface while making large JavaScript graphs practical for
+UI consumers and reducing production-analysis noise.
+
+## Structured results and performance
+
+- `find_duplicates` and ordinary `run_audit` results now include bounded
+  structured groups/findings alongside their existing text summaries, so MCP
+  clients can render native views without parsing prose.
+- Local symbol references are indexed once per file and declaration ranges are
+  subtracted with binary search instead of rescanning the whole file for every
+  symbol. On the 8,117-node Repo Lens graph, aggregation fell from more than
+  64 seconds to about 0.93 seconds while preserving graph totals.
+
+## Production-first precision
+
+- `vendor`, `vendored`, and `third-party` paths are classified explicitly and
+  suppressed consistently across duplicates, audit, endpoints, context,
+  architecture, dead-code, hot-path, and graph-query surfaces.
+- Electron preload files are treated as entry points only when another source
+  contains a bounded `BrowserWindow` `preload:` option.
+- Endpoint extraction masks JavaScript regex literals and comments correctly
+  and recognizes bounded `node:http` method plus `url.pathname` guards. Repo
+  Lens now reports its four production control routes without comment/test
+  false positives in the production view.
+
+## Coverage interoperability
+
+- `coverage_map` reads Cargo Tarpaulin's official JSON report shape, including
+  component paths and `traces[].stats.Line`, and advertises both Tarpaulin JSON
+  and `cargo llvm-cov` LCOV workflows for Rust repositories.
+
+This Core release is paired with `weavatrix-refactor` 0.1.2 and
+`weavatrix-online` 0.2.0. Each layer keeps its own package, license, version,
+and release provenance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "type": "module",
   "description": "Local repository intelligence MCP for AI coding agents: an always-fresh architecture graph with production-first evidence — blast radius, dead code, endpoints, clones, history, Health and architecture safeguards, with honestly labeled precision.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",
@@ -47,6 +47,8 @@
     "docs/releases/v0.3.10.md",
     "docs/releases/v0.3.11.md",
     "docs/releases/v0.3.12.md",
+    "docs/releases/v0.3.13.md",
+    "docs/releases/v0.3.14.md",
     "docs/releases/v0.2.19.md",
     "README.md",
     "SECURITY.md",

package/src/analysis/coverage-reports-tarpaulin.js

@@ -0,0 +1,112 @@
+import { readFileSync } from "node:fs";
+
+function pct01(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return Math.max(0, Math.min(1, n > 1 ? n / 100 : n));
+}
+
+function pctFromCounts(covered, total) {
+  const c = Number(covered);
+  const t = Number(total);
+  if (!Number.isFinite(c) || !Number.isFinite(t) || t <= 0) return null;
+  return Math.max(0, Math.min(1, c / t));
+}
+
+function addLineHit(lines, line, hit) {
+  const value = Number(line);
+  if (!Number.isFinite(value) || value <= 0) return;
+  const n = Math.round(value);
+  if (n < 1) return;
+  const current = lines.get(n);
+  lines.set(n, Math.max(Number(current) || 0, Number(hit) || 0));
+}
+
+function numericLineList(value) {
+  const input = Array.isArray(value) ? value : [];
+  return input
+    .map((line) => Number(line))
+    .filter((line) => Number.isFinite(line) && line > 0)
+    .map((line) => Math.round(line));
+}
+
+function legacyLineGroups(record) {
+  if (!record || typeof record !== "object") return { covered: [], uncovered: [] };
+  const lines = record.lines && typeof record.lines === "object" ? record.lines : {};
+  return {
+    covered: [
+      ...numericLineList(record.covered),
+      ...numericLineList(record.covered_lines),
+      ...numericLineList(record.coveredLines),
+      ...numericLineList(lines.covered),
+      ...numericLineList(lines.covered_lines),
+    ],
+    uncovered: [
+      ...numericLineList(record.uncovered),
+      ...numericLineList(record.uncovered_lines),
+      ...numericLineList(record.uncoveredLines),
+      ...numericLineList(record.missing),
+      ...numericLineList(record.missing_lines),
+      ...numericLineList(lines.uncovered),
+      ...numericLineList(lines.uncovered_lines),
+      ...numericLineList(lines.missing),
+    ],
+  };
+}
+
+function recordPath(record) {
+  const raw = record?.path || record?.file || record?.filename || record?.name;
+  if (Array.isArray(raw)) return raw.map(String).filter(Boolean).join("/");
+  return raw;
+}
+
+function reportEntries(json) {
+  const files = json?.files || json?.coverage || json;
+  if (Array.isArray(files)) {
+    return files.map((record) => [recordPath(record), record]).filter(([raw]) => raw);
+  }
+  if (files && typeof files === "object") return Object.entries(files);
+  return [];
+}
+
+function coveragePct(record, covered, total) {
+  const summary = record?.summary && typeof record.summary === "object" ? record.summary : {};
+  return pct01(
+    record?.coverage
+    ?? record?.coverage_percentage
+    ?? record?.line_coverage
+    ?? summary.coverage
+    ?? summary.coverage_percentage
+    ?? summary.percent
+  )
+    ?? pctFromCounts(record?.covered, record?.coverable)
+    ?? pctFromCounts(covered, total);
+}
+
+export function readTarpaulinCoverage(filePath) {
+  const json = JSON.parse(readFileSync(filePath, "utf8"));
+  return reportEntries(json).map(([path, record]) => {
+    const lines = new Map();
+    for (const trace of Array.isArray(record?.traces) ? record.traces : []) {
+      if (!trace?.stats || typeof trace.stats !== "object" || !("Line" in trace.stats)) continue;
+      addLineHit(lines, trace.line, trace.stats.Line);
+    }
+    const legacy = legacyLineGroups(record);
+    for (const line of legacy.uncovered) addLineHit(lines, line, 0);
+    for (const line of legacy.covered) addLineHit(lines, line, 1);
+    const measuredTotal = lines.size;
+    const measuredCovered = [...lines.values()].filter((hit) => Number(hit) > 0).length;
+    const reportedTotal = Number(record?.coverable);
+    const reportedCovered = Number(record?.covered);
+    return {
+      path,
+      entry: {
+        pct: coveragePct(record, measuredCovered, measuredTotal),
+        total: Number.isFinite(reportedTotal) ? reportedTotal : measuredTotal,
+        covered: Number.isFinite(reportedCovered) ? reportedCovered : measuredCovered,
+        lines,
+        source: "tarpaulin-report.json",
+      },
+    };
+  });
+}

package/src/analysis/coverage-reports.js

@@ -4,6 +4,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { createRepoBoundary } from "../repo-path.js";
+import { readTarpaulinCoverage } from "./coverage-reports-tarpaulin.js";
 
 export function normRepoPath(value) {
   return String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
@@ -84,8 +85,10 @@ function mergeCoverageEntry(map, rawPath, entry, knownFiles, repoRoot) {
 }
 
 function addLineHit(lines, line, hit) {
-  const n = Math.max(1, Math.round(Number(line) || 0));
-  if (!n) return;
+  const value = Number(line);
+  if (!Number.isFinite(value) || value <= 0) return;
+  const n = Math.round(value);
+  if (n < 1) return;
   const current = lines.get(n);
   lines.set(n, Math.max(Number(current) || 0, Number(hit) || 0));
 }
@@ -208,6 +211,12 @@ function parseGoCoverage(map, filePath, knownFiles, repoRoot) {
   }
 }
 
+function parseTarpaulinJson(map, filePath, knownFiles, repoRoot) {
+  for (const record of readTarpaulinCoverage(filePath)) {
+    mergeCoverageEntry(map, record.path, record.entry, knownFiles, repoRoot);
+  }
+}
+
 export function readCoverageForRepo(repoRoot, knownFiles) {
   const out = new Map();
   if (!repoRoot) return out;
@@ -219,6 +228,8 @@ export function readCoverageForRepo(repoRoot, knownFiles) {
     ["lcov.info", parseLcov],
     ["coverage/coverage.json", parseCoveragePyJson],
     ["coverage.json", parseCoveragePyJson],
+    ["tarpaulin-report.json", parseTarpaulinJson],
+    ["coverage/tarpaulin-report.json", parseTarpaulinJson],
     ["coverage.out", parseGoCoverage],
     ["cover.out", parseGoCoverage]
   ];

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

@@ -12,7 +12,7 @@ export function hasDynamicCode(source, file = '') {
     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'])
+const NON_PRODUCT_CLASSES = Object.freeze(['generated', 'vendored', 'mock', 'story', 'docs', 'benchmark', 'temp'])
 
 export function deadCodePathAllowed(info, {includeTests, includeClassified}) {
     if (!includeTests && hasPathClass(info, 'test', 'e2e')) return {ok: false, bucket: 'tests'}

package/src/analysis/duplicate-groups.js

@@ -6,7 +6,7 @@ import {withGitRefCheckout} from './git-ref-graph.js'
 import {buildInternalGraph} from '../graph/internal-builder.js'
 import {filterGraphForMode} from '../graph/graph-filter.js'
 
-const NON_PRODUCT = new Set(['generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
+const NON_PRODUCT = new Set(['generated', 'vendored', 'mock', 'story', 'docs', 'benchmark', 'temp'])
 const eligible = (fragment, settings) => {
   const classes = new Set(fragment.classes || [])
   if (fragment.n < settings.tokMin) return false

package/src/analysis/endpoints/common.js

@@ -11,7 +11,15 @@ export function lineAt(text, index) {
 // 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;
+  let quote = "", escaped = false, lineComment = false, blockComment = false, regex = false, regexClass = false;
+  const startsRegex = (index) => {
+    let cursor = index - 1;
+    while (cursor >= 0 && /\s/.test(chars[cursor])) cursor--;
+    if (cursor < 0) return true;
+    if (/[=(:,!&|?{}[\];]/.test(chars[cursor])) return true;
+    const prefix = chars.slice(Math.max(0, cursor - 12), cursor + 1).join("");
+    return /(?:^|\b)(?:return|throw|case|yield|await)\s*$/i.test(prefix) || /=>\s*$/.test(prefix);
+  };
   for (let i = 0; i < chars.length; i++) {
     const ch = chars[i], next = chars[i + 1];
     if (lineComment) {
@@ -24,6 +32,14 @@ export function maskComments(text, { hashComments = false } = {}) {
       else if (ch !== "\n" && ch !== "\r") chars[i] = " ";
       continue;
     }
+    if (regex) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === "[") regexClass = true;
+      else if (ch === "]") regexClass = false;
+      else if (ch === "/" && !regexClass) regex = false;
+      continue;
+    }
     if (quote) {
       if (escaped) escaped = false;
       else if (ch === "\\") escaped = true;
@@ -33,6 +49,7 @@ export function maskComments(text, { hashComments = false } = {}) {
     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 === "/" && startsRegex(i)) { regex = true; regexClass = false; escaped = false; continue; }
     if (hashComments && ch === "#") { chars[i] = " "; lineComment = true; }
   }
   return chars.join("");

package/src/analysis/endpoints/extract.js

@@ -92,6 +92,19 @@ export function extractEndpointsFromText(text, file) {
     if (!HTTP_CLIENT_CALLER.test(match[1]) && handler && handler[0] !== "{") add(match[2], match[4], match[5], match.index);
   }
 
+  // Bare node:http servers commonly dispatch through request-method and URL-pathname guards rather
+  // than a router API. Keep the extraction bounded to files that actually construct an HTTP server;
+  // test assertions and arbitrary `object.method` comparisons are not enough to create endpoints.
+  if (!py && /\bcreateServer\s*\(|\b(?:node:)?https?\b/.test(scanText)) {
+    const guardedRoute = /\bif\s*\(([\s\S]{0,600}?)\)\s*(?:\{|return\b)/g;
+    while ((match = guardedRoute.exec(scanText))) {
+      const condition = match[1];
+      const methodMatch = /\b[A-Za-z_$][\w$]*\.method\s*={2,3}\s*(["'`])(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|CONNECT)\1/i.exec(condition);
+      const pathMatch = /\b[A-Za-z_$][\w$]*\.pathname\s*={2,3}\s*(["'`])(\/[^"'`]*)\1/i.exec(condition);
+      if (methodMatch && pathMatch) add(methodMatch[2], pathMatch[2], "", match.index);
+    }
+  }
+
   const go = /\.\s*(?:HandleFunc|Handle)\s*\(\s*(["'`])(\/[^"'`]*)\1\s*,\s*([\s\S]{0,120}?)\)/g;
   while ((match = go.exec(scanText))) add("ANY", match[2], match[3], match.index);
 

package/src/analysis/graph-analysis.aggregate.js

@@ -4,7 +4,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { normalizeRepoParts, readCoverageForRepo, pctFromCounts } from "./coverage-reports.js";
-import { bareSymbolName, countLocalRefsOutsideOwnRange, computeSymbolExternalRefs } from "./graph-analysis.refs.js";
+import { bareSymbolName, computeLocalSymbolRefs, computeSymbolExternalRefs } from "./graph-analysis.refs.js";
 import { createRepoBoundary } from "../repo-path.js";
 import { edgeList, folderModuleOf } from "./graph-analysis.edges.js";
 export { folderModuleOf } from "./graph-analysis.edges.js";
@@ -223,6 +223,7 @@ export function aggregateGraph(graph, repoRoot) {
       .map((s) => ({ id: s.id, label: s.label, start: parseInt(s.line, 10), end: parseInt(s.endLine, 10), ref: s }))
       .filter((s) => Number.isFinite(s.start) && s.start > 0)
       .sort((a, b) => a.start - b.start);
+    const ranges = [];
     for (let i = 0; i < sorted.length; i++) {
       const start = sorted[i].start;
       const next = i + 1 < sorted.length ? sorted[i + 1].start : total > start ? total + 1 : start + 1;
@@ -234,9 +235,9 @@ export function aggregateGraph(graph, repoRoot) {
       sorted[i].ref.endLine = end;
       const cov = coverageForRange(fid, start, end);
       if (cov != null) symbolCoverage.set(sorted[i].id, cov);
-      const refs = countLocalRefsOutsideOwnRange(txt, bareSymbolName(sorted[i].label), start, end);
-      if (refs > 0) symbolLocalRefs.set(sorted[i].id, refs);
+      ranges.push({id: sorted[i].id, name: bareSymbolName(sorted[i].label), startLine: start, endLine: end});
     }
+    for (const [id, refs] of computeLocalSymbolRefs(txt, ranges)) symbolLocalRefs.set(id, refs);
   }
   for (const s of symbols) {
     const fid = id2file.get(s.id);

package/src/analysis/graph-analysis.refs.js

@@ -41,6 +41,54 @@ export function countLocalRefsOutsideOwnRange(text, name, startLine, endLine) {
   return refs;
 }
 
+const lowerBound = (values, target) => {
+  let low = 0, high = values.length;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    if (values[middle] < target) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+};
+
+// Count every wanted identifier in a file once, then subtract occurrences inside each declaration
+// with binary searches over occurrence line numbers. The former per-symbol full-file scan became
+// quadratic on large vendored files (thousands of symbols over tens of thousands of lines).
+export function computeLocalSymbolRefs(text, symbols) {
+  const candidates = (symbols || []).map((symbol) => ({
+    id: symbol.id,
+    name: bareSymbolName(symbol.name ?? symbol.label),
+    start: Number(symbol.startLine ?? symbol.start),
+    end: Number(symbol.endLine ?? symbol.end),
+  })).filter((symbol) => symbol.id && isIdentifierName(symbol.name));
+  if (!text || !candidates.length) return new Map();
+  const wanted = new Set(candidates.map((symbol) => symbol.name));
+  const occurrenceLines = new Map();
+  const identifier = /[A-Za-z_$][\w$]*/g;
+  const lines = String(text).split(/\r?\n/);
+  for (let index = 0; index < lines.length; index++) {
+    identifier.lastIndex = 0;
+    let match;
+    while ((match = identifier.exec(lines[index]))) {
+      const name = match[0];
+      if (!wanted.has(name)) continue;
+      const positions = occurrenceLines.get(name) || [];
+      positions.push(index + 1);
+      occurrenceLines.set(name, positions);
+    }
+  }
+  const refs = new Map();
+  for (const symbol of candidates) {
+    const positions = occurrenceLines.get(symbol.name) || [];
+    const start = Number.isFinite(symbol.start) && symbol.start > 0 ? symbol.start : 0;
+    const end = Number.isFinite(symbol.end) && symbol.end >= start ? symbol.end : start;
+    const inside = start ? lowerBound(positions, end + 1) - lowerBound(positions, start) : 0;
+    const outside = Math.max(0, positions.length - inside);
+    if (outside > 0) refs.set(symbol.id, outside);
+  }
+  return refs;
+}
+
 function importCandidates(fromFile, spec) {
   const raw = String(spec || "");
   if (!raw.startsWith(".")) return [];

package/src/analysis/hot-path-review.js

@@ -7,7 +7,7 @@ import {createPathClassifier, hasPathClass} from '../path-classification.js'
 import {isStructuralRelation} from '../graph/relations.js'
 import {boundedInteger} from '../util.js'
 
-const NON_PRODUCT = ['generated', 'mock', 'story', 'docs', 'benchmark', 'temp']
+const NON_PRODUCT = ['generated', 'vendored', 'mock', 'story', 'docs', 'benchmark', 'temp']
 const endpoint = (value) => String(value && typeof value === 'object' ? value.id : value || '')
 const normalize = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
 const boundedInt = boundedInteger

package/src/analysis/internal-audit.reach.js

@@ -53,6 +53,30 @@ export function springConventionEntries(sources, fileSet = null) {
   return out.sort((a, b) => a.file.localeCompare(b.file));
 }
 
+// Electron loads preload scripts from BrowserWindow.webPreferences rather than through a normal
+// import edge. Require both a conventional preload filename and a bounded `preload:` option that
+// names that exact file, so an unrelated helper called preload.js is not silently blessed.
+export function electronPreloadEntries(sources, fileSet = null) {
+  const files = fileSet || new Set((sources || new Map()).keys());
+  const out = [];
+  for (const rawFile of files) {
+    const file = String(rawFile || "").replace(/\\/g, "/");
+    if (!/(^|\/)preload\.[cm]?[jt]s$/i.test(file)) continue;
+    const basename = posix.basename(file).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const marker = new RegExp(`\\bpreload\\s*:\\s*[\\s\\S]{0,240}?["'\\x60]${basename}["'\\x60]`, "i");
+    const owner = [...(sources || [])].find(([other, text]) => String(other).replace(/\\/g, "/") !== file && marker.test(String(text || "")));
+    if (!owner) continue;
+    out.push({
+      file,
+      framework: "electron",
+      marker: `BrowserWindow preload option in ${String(owner[0]).replace(/\\/g, "/")}`,
+      confidence: "high",
+      reason: "Electron loads this exact preload script outside the static import graph",
+    });
+  }
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+
 // Entry set for reachability: conventional entry names + package.json main/module/browser/bin/exports +
 // html pages (they root classic-script apps) + test files (the runner enters them) + root config files +
 // dynamic-import targets. Anything reachable from here is "used"; the rest corroborates unused-file.
@@ -136,6 +160,10 @@ export function entryFiles(graph, pkgOrScopes, dynamicTargets = new Set(), { dec
     entries.add(evidence.file);
     conventionEvidence.push(evidence);
   }
+  for (const evidence of electronPreloadEntries(sources, fileSet)) {
+    entries.add(evidence.file);
+    conventionEvidence.push(evidence);
+  }
   for (const raw of Array.isArray(declaredEntries) ? declaredEntries : [declaredEntries]) {
     const resolved = resolveEntry("", raw);
     if (resolved && fileSet.has(resolved)) entries.add(resolved);

package/src/analysis/internal-audit.run.js

@@ -61,7 +61,7 @@ export async function runInternalAudit(repoPath, {
   };
   const isNonProductPath = (file) => {
     const info = classifyPath(file);
-    return info.excluded || hasPathClass(info, "test", "e2e", "generated", "mock", "story", "docs", "benchmark", "temp");
+    return info.excluded || hasPathClass(info, "test", "e2e", "generated", "vendored", "mock", "story", "docs", "benchmark", "temp");
   };
 
   const conventionEvidence = [];

package/src/analysis/static-test-reachability.js

@@ -47,7 +47,7 @@ export function computeStaticTestReachability(graph, {
   const isTest = (file) => hasPathClass(classify(file), "test", "e2e");
   const isProduct = (file) => {
     const info = classify(file);
-    return !info.excluded && !hasPathClass(info, "test", "e2e", "generated", "mock", "story", "docs", "benchmark", "temp");
+    return !info.excluded && !hasPathClass(info, "test", "e2e", "generated", "vendored", "mock", "story", "docs", "benchmark", "temp");
   };
 
   const idToFile = new Map();

package/src/mcp/architecture-starter.mjs

@@ -30,7 +30,7 @@ const CODE_EXTENSIONS = new Set([
     '.cjs', '.cs', '.css', '.go', '.htm', '.html', '.java', '.js', '.jsx', '.less', '.mjs', '.py', '.pyi',
     '.rs', '.scss', '.sol', '.sql', '.ts', '.tsx',
 ])
-const CLASSIFIED = ['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp']
+const CLASSIFIED = ['test', 'e2e', 'generated', 'vendored', 'mock', 'story', 'docs', 'benchmark', 'temp']
 const EDGE_RELATIONS = new Set(['imports', 're_exports', 'calls', 'references'])
 
 const slash = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '')

package/src/mcp/catalog.mjs

@@ -111,6 +111,10 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
                     max_matches: {type: 'integer', minimum: 1, maximum: 5000, default: 1000},
                     max_affected_files: {type: 'integer', minimum: 1, maximum: 500, default: 100},
                     top_n: {type: 'integer', minimum: 1, maximum: 50, default: 10},
+                    response_detail: {type: 'string', enum: ['compact', 'full'], default: 'compact', description: 'Compact returns bounded samples and counts. Full is explicit opt-in and still paginated.'},
+                    page_size: {type: 'integer', minimum: 1, maximum: 50, default: 10, description: 'Maximum HTTP/transport/uncertain evidence items returned on this page.'},
+                    per_item_limit: {type: 'integer', minimum: 1, maximum: 25, default: 5, description: 'Compact-mode sample limit for callsites, affected files, screens and modules per item.'},
+                    cursor: {type: 'string', maxLength: 256, description: 'Opaque nextCursor from the previous page; bound to repository revisions and filters.'},
                 },
                 required: ['backend', 'clients'],
             },
@@ -120,12 +124,12 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
         {cap: 'search', name: 'search_code', description: 'Full-text or regex search across the repo source (ripgrep-backed, Node fallback). The graph only stores structure — use this to find literal text/patterns, then get_node/get_neighbors for structure.', inputSchema: {type: 'object', properties: {query: {type: 'string', description: 'text or regex to search for'}, is_regex: {type: 'boolean', default: false}, glob: {type: 'string', description: 'optional path glob, e.g. "*.js" or "src/**"'}, max_results: {type: 'integer', default: 40}}, required: ['query']}, run: (g, a, ctx) => searchCode({repoRoot: ctx.repoRoot, resolveRg}, a)},
           {cap: 'source', name: 'read_source', description: "Read the actual source of a node (by label/ID) or a repo-relative file path — the symbol's lines with context. The graph stores only locations, not source text. For a path read, pass start_line to anchor the window anywhere in the file (otherwise it shows the head).", inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'node label or ID'}, path: {type: 'string', description: 'or a repo-relative file path'}, start_line: {type: 'integer', description: 'anchor line: window = start_line-before .. start_line+after'}, before: {type: 'integer', default: 3}, after: {type: 'integer', default: 40}}}, run: (g, a, ctx) => readSource({repoRoot: ctx.repoRoot, resolveNode, isSymbol}, g, a)},
           {cap: 'source', refreshGraph: true, name: 'inspect_symbol', description: 'Inspect one exact symbol with an on-demand TypeScript/JavaScript LSP reference query, grouped occurrence containers, graph blast radius, complexity facts and bounded local source context. Ambiguous labels fail closed; point queries never replace the broad precision overlay.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Exact node ID or unambiguous symbol label'}, precision: {type: 'string', enum: ['auto', 'graph', 'lsp'], default: 'auto'}, max_references: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_containers: {type: 'integer', minimum: 1, maximum: 50, default: 15}, context_lines: {type: 'integer', minimum: 0, maximum: 40, default: 8}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 60000, default: 30000}}, required: ['label']}, run: (g, a, ctx) => ts.tInspectSymbol(g, a, ctx)},
-          {cap: 'source', refreshGraph: true, name: 'context_bundle', description: 'Return one compact, bounded source bundle for an exact symbol: definition, production-first inbound/outbound containers, exact re-export sites, on-demand TS/JS reference evidence and diverse excerpts around call sites. Use before an edit when query_graph would be too broad.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Exact node ID or unambiguous symbol label'}, precision: {type: 'string', enum: ['auto', 'graph', 'lsp'], default: 'auto'}, max_references: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_related: {type: 'integer', minimum: 1, maximum: 30, default: 10}, max_reexports: {type: 'integer', minimum: 1, maximum: 100, default: 20}, max_source_files: {type: 'integer', minimum: 1, maximum: 8, default: 4}, context_lines: {type: 'integer', minimum: 0, maximum: 12, default: 4}, include_classified: {type: 'boolean', default: false, description: 'Include test/e2e/generated/mock/story/docs/benchmark/temp callers after production callers'}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 60000, default: 30000}}, required: ['label']}, run: (g, a, ctx) => tb.tContextBundle(g, a, ctx, ts.tInspectSymbol)},
-        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over production code (MOSS winnowing over method bodies). Supports high-confidence small clones down to 12 tokens when min_tokens is lowered. Tests, classified non-product paths, all-router framework boilerplate and immutable declarative catalogs are excluded by default; opt them in explicitly.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', minimum: 12, maximum: 400, description: 'min fragment size, 12-400; default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, include_boilerplate: {type: 'boolean', default: false, description: 'Include clone groups made entirely of conventional *.router.js/ts router symbols'}, include_declarative: {type: 'boolean', default: false, description: 'Include repeated immutable array/object catalogs that contain no executable control flow'}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
-        {cap: 'health', name: 'find_dead_code', description: 'Conservative review queue for statically unreferenced files, functions, methods and symbols. Returns confidence, reason, bounded evidence and explicit framework/dynamic/reflection/public-API caveats; never an auto-delete verdict. Tests, generated code, mocks, stories, docs, benchmarks and temporary roots are excluded by default.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repo-relative path prefix'}, kinds: {type: 'array', items: {type: 'string', enum: ['file', 'function', 'method', 'symbol']}, maxItems: 4, uniqueItems: true, description: 'Optional candidate kinds; defaults to all'}, min_confidence: {type: 'string', enum: ['high', 'medium', 'low'], default: 'medium', description: 'Minimum confidence to include. low explicitly includes public/framework/dynamic review candidates'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 30}}}, run: (g, a, ctx) => th.tFindDeadCode(g, a, ctx)},
-        {cap: 'health', name: 'run_audit', description: 'Core production-first repository Health review with an explicit capability/completeness matrix for structure, dependencies, bounded runtime-correctness/concurrency patterns, advisories, malware and coverage. Unsupported Maven/Gradle import verification is NOT_SUPPORTED/PARTIAL, never a clean zero. Findings whose evidence is entirely test/e2e/generated/mock/story/docs/benchmark/temp or explicitly excluded are suppressed by default; opt them in with include_classified. category=dependencies is a dedicated dependency-health projection across missing, unused and duplicate declarations while preserving each finding\'s native category. With base_ref, builds and audits an immutable Git checkout and compares stable deterministic finding IDs; debt defaults to genuinely new findings. Supply-chain checks remain explicitly uncomparable across the source-only baseline. changed_files without base_ref is only changed-scope, never a new-debt claim.', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['dependencies', 'unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category; dependencies selects dependency manifest/import findings across native categories'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_classified: {type: 'boolean', default: false, description: 'Include findings whose evidence is entirely tests/e2e/generated/mocks/stories/docs/benchmarks/temp or explicitly excluded'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}, base_ref: {type: 'string', maxLength: 200, description: 'Optional immutable Git baseline (for example HEAD~1 or origin/main). Enables honest new/existing/fixed debt comparison'}, changed_files: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 500, description: 'Optional explicit repo-relative scope. Without base_ref this is changed-scope only; when omitted with base_ref, files are derived from the Git diff'}, debt: {type: 'string', enum: ['new', 'existing', 'all'], default: 'new', description: 'Baseline comparison view. Defaults to genuinely new deterministic findings when base_ref is present'}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
+          {cap: 'source', refreshGraph: true, name: 'context_bundle', description: 'Return one compact, bounded source bundle for an exact symbol: definition, production-first inbound/outbound containers, exact re-export sites, on-demand TS/JS reference evidence and diverse excerpts around call sites. Use before an edit when query_graph would be too broad.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Exact node ID or unambiguous symbol label'}, precision: {type: 'string', enum: ['auto', 'graph', 'lsp'], default: 'auto'}, max_references: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_related: {type: 'integer', minimum: 1, maximum: 30, default: 10}, max_reexports: {type: 'integer', minimum: 1, maximum: 100, default: 20}, max_source_files: {type: 'integer', minimum: 1, maximum: 8, default: 4}, context_lines: {type: 'integer', minimum: 0, maximum: 12, default: 4}, include_classified: {type: 'boolean', default: false, description: 'Include test/e2e/generated/vendored/mock/story/docs/benchmark/temp callers after production callers'}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 60000, default: 30000}}, required: ['label']}, run: (g, a, ctx) => tb.tContextBundle(g, a, ctx, ts.tInspectSymbol)},
+        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over production code (MOSS winnowing over method bodies). Supports high-confidence small clones down to 12 tokens when min_tokens is lowered. Tests, classified non-product paths, all-router framework boilerplate and immutable declarative catalogs are excluded by default; opt them in explicitly.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', minimum: 12, maximum: 400, description: 'min fragment size, 12-400; default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/vendored/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, include_boilerplate: {type: 'boolean', default: false, description: 'Include clone groups made entirely of conventional *.router.js/ts router symbols'}, include_declarative: {type: 'boolean', default: false, description: 'Include repeated immutable array/object catalogs that contain no executable control flow'}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
+        {cap: 'health', name: 'find_dead_code', description: 'Conservative review queue for statically unreferenced files, functions, methods and symbols. Returns confidence, reason, bounded evidence and explicit framework/dynamic/reflection/public-API caveats; never an auto-delete verdict. Tests, generated/vendored code, mocks, stories, docs, benchmarks and temporary roots are excluded by default.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repo-relative path prefix'}, kinds: {type: 'array', items: {type: 'string', enum: ['file', 'function', 'method', 'symbol']}, maxItems: 4, uniqueItems: true, description: 'Optional candidate kinds; defaults to all'}, min_confidence: {type: 'string', enum: ['high', 'medium', 'low'], default: 'medium', description: 'Minimum confidence to include. low explicitly includes public/framework/dynamic review candidates'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/vendored/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 30}}}, run: (g, a, ctx) => th.tFindDeadCode(g, a, ctx)},
+        {cap: 'health', name: 'run_audit', description: 'Core production-first repository Health review with an explicit capability/completeness matrix for structure, dependencies, bounded runtime-correctness/concurrency patterns, advisories, malware and coverage. Unsupported Maven/Gradle import verification is NOT_SUPPORTED/PARTIAL, never a clean zero. Findings whose evidence is entirely test/e2e/generated/vendored/mock/story/docs/benchmark/temp or explicitly excluded are suppressed by default; opt them in with include_classified. category=dependencies is a dedicated dependency-health projection across missing, unused and duplicate declarations while preserving each finding\'s native category. With base_ref, builds and audits an immutable Git checkout and compares stable deterministic finding IDs; debt defaults to genuinely new findings. Supply-chain checks remain explicitly uncomparable across the source-only baseline. changed_files without base_ref is only changed-scope, never a new-debt claim.', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['dependencies', 'unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category; dependencies selects dependency manifest/import findings across native categories'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_classified: {type: 'boolean', default: false, description: 'Include findings whose evidence is entirely tests/e2e/generated/vendored/mocks/stories/docs/benchmarks/temp or explicitly excluded'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}, base_ref: {type: 'string', maxLength: 200, description: 'Optional immutable Git baseline (for example HEAD~1 or origin/main). Enables honest new/existing/fixed debt comparison'}, changed_files: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 500, description: 'Optional explicit repo-relative scope. Without base_ref this is changed-scope only; when omitted with base_ref, files are derived from the Git diff'}, debt: {type: 'string', enum: ['new', 'existing', 'all'], default: 'new', description: 'Baseline comparison view. Defaults to genuinely new deterministic findings when base_ref is present'}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
         {cap: 'health', name: 'coverage_map', description: 'Map a real existing coverage report onto the graph. If no report exists, return clearly labelled static test reachability (a test imports/reaches a source file) with actualCoverage=NOT_AVAILABLE; reachability is never presented as measured coverage.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
-        {cap: 'health', name: 'hot_path_review', description: 'Rank a focused production-symbol hot-path queue from parser-derived local complexity, inside-loop allocations/copies/scans/sorts/recursion, graph fan-in/fan-out, and measured coverage or clearly labelled static test reachability. The default score gate is 85 with a narrow strong-local fallback; set min_score=0 for the full diagnostic queue. This is not profiler data or interprocedural Big-O.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repository-relative path prefix'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 20}, min_score: {type: 'integer', minimum: 0, maximum: 100, default: 85, description: 'Focused default is 85; lower explicitly to broaden, or use 0 for every threshold-matching diagnostic candidate'}, cyclomatic_threshold: {type: 'integer', minimum: 2, maximum: 1000, default: 8}, call_threshold: {type: 'integer', minimum: 1, maximum: 10000, default: 12}, loop_depth_threshold: {type: 'integer', minimum: 1, maximum: 10, default: 2}, time_rank_threshold: {type: 'integer', minimum: 0, maximum: 5, default: 2}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and explicitly excluded paths; tests still require include_tests'}}}, run: (g, a, ctx) => th.tHotPathReview(g, a, ctx)},
+        {cap: 'health', name: 'hot_path_review', description: 'Rank a focused production-symbol hot-path queue from parser-derived local complexity, inside-loop allocations/copies/scans/sorts/recursion, graph fan-in/fan-out, and measured coverage or clearly labelled static test reachability. The default score gate is 85 with a narrow strong-local fallback; set min_score=0 for the full diagnostic queue. This is not profiler data or interprocedural Big-O.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repository-relative path prefix'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 20}, min_score: {type: 'integer', minimum: 0, maximum: 100, default: 85, description: 'Focused default is 85; lower explicitly to broaden, or use 0 for every threshold-matching diagnostic candidate'}, cyclomatic_threshold: {type: 'integer', minimum: 2, maximum: 1000, default: 8}, call_threshold: {type: 'integer', minimum: 1, maximum: 10000, default: 12}, loop_depth_threshold: {type: 'integer', minimum: 1, maximum: 10, default: 2}, time_rank_threshold: {type: 'integer', minimum: 0, maximum: 5, default: 2}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/vendored/mock/story/docs/benchmark/temp and explicitly excluded paths; tests still require include_tests'}}}, run: (g, a, ctx) => th.tHotPathReview(g, a, ctx)},
         {cap: 'graph', name: 'list_communities', description: 'List graph communities named by their dominant folder (largest first) with sample files — a readable module overview; feed the list position into get_community.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max communities to list, default 20'}}}, run: (g, a, ctx) => th.tListCommunities(g, a, ctx)},
         {cap: 'graph', name: 'module_map', description: 'First orientation view for understanding an unfamiliar application with little context: a production-first folder architecture map with file/symbol counts and strongest module dependencies, separating runtime, TypeScript type-only and language compile-only coupling.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}, include_non_product: {type: 'boolean', default: false, description: 'Include tests, fixtures, benchmarks, generated output, docs and other classified non-product files; false by default'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
         {cap: 'source', refreshGraph: true, name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web/Spring MVC and WebFlux): declared and reachable composed paths, static mount provenance, confidence, handler, file:line, and Spring conditional/default-active state.', inputSchema: {type: 'object', properties: {method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT', 'ALL', 'ANY']}, path: {type: 'string', maxLength: 2048, description: 'Optional exact composed path or segment-aligned suffix'}, max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}, include_classified: {type: 'boolean', default: false, description: 'Include test/e2e/generated/mock/story/docs/benchmark/temp and explicitly excluded targets'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},