weavatrix 0.2.4 → 0.2.5

package/README.md

@@ -5,7 +5,7 @@
 Grep sees text. Weavatrix sees structure. It builds a dependency graph of any local repository —
 files, symbols, and the imports/calls/inheritance connecting them — and serves it to Claude Code,
 Codex, or any MCP client: change impact, transitive dependents, health audit, clone detection,
-coverage mapping. **32 tools available; 29 enabled by the default offline profile. Local-first: with
+coverage mapping. **34 tools available; 31 enabled by the default offline profile. Local-first: with
 the defaults, no repository data leaves your machine.**
 
 - Website: [weavatrix.com](https://weavatrix.com)
@@ -21,8 +21,9 @@ answers grep can't produce:
   untracked included), maps the changed files and symbols onto the graph, and lists everything that
   depends on them — with test coverage attached, so the **untested part of the blast radius** stands
   out before you ship.
-- *"Who calls this function?"* → `get_dependents` walks reverse edges transitively: every caller,
-  importer and subclass that can feel the refactor, ranked by proximity × connectivity.
+- *"Who calls this function?"* → `inspect_symbol` returns exact bounded TS/JS occurrences plus
+  source context; `get_dependents` walks the symbol-level reverse graph transitively. Opt into
+  `include_container_importers:true` only when a broader module-import radius is intended.
 - *"Did my refactor actually decouple anything?"* → `graph_diff base_ref=HEAD~1` builds an immutable
   baseline graph without checking it out, then reports the structural delta: new module
   dependencies, broken or introduced import cycles, and symbols that lost their last caller.
@@ -117,7 +118,7 @@ confirmed by its bundled `typescript-language-server` + TypeScript runtime to `E
 `CONFLICT` means evidence disagrees. `graph_stats` reports the provenance breakdown and the semantic
 provider's `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, or `OFF` state; `OFF` means precision was explicitly
 disabled and only static evidence is active. Java and Rust language-server providers are not bundled
-in 0.2.4: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
+in 0.2.5: their edges never become `EXACT_LSP`, even when a mixed repository reports a complete
 TypeScript/JavaScript overlay.
 
 The bounded JS/TS provider is enabled by default for new graphs. Set `WEAVATRIX_PRECISION=off`
@@ -126,19 +127,27 @@ before starting the MCP server for parser-only operation from the first build, o
 choice as **TypeScript/JavaScript semantic precision**.
 
 **search / source** — `search_code` (ripgrep-backed, pure-Node fallback), `read_source` (a
-symbol's actual code in one hop), `list_endpoints` (HTTP route inventory:
+symbol's actual code in one hop), `inspect_symbol` (one exact bounded TS/JS reference query,
+logical containers, impact and source excerpts), `list_endpoints` (HTTP route inventory:
 Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …)
 
-**health** — `find_dead_code` (bounded review queue for statically unreferenced files, functions,
-methods, and symbols, with confidence/evidence and explicit public/framework/dynamic caveats),
-`run_audit` (unused files/exports/dependencies, missing npm/Go/Python deps, runtime
+**health** — `find_dead_code` (bounded review queue for statically unreferenced and test-only files,
+functions, methods, and symbols, with confidence/evidence and explicit public/framework/dynamic caveats),
+`run_audit` (unused files/exports/dependencies with an explicit manifest-check summary,
+missing npm/Go/Python deps, runtime
 cycles, type-only/compile-only coupling, orphans, boundary rules, offline OSV vulnerabilities + typosquat +
 lockfile drift; accepts an immutable `base_ref`, `changed_files`, and `debt: new|existing|all` for
 review-scoped results), `find_duplicates` (MOSS winnowing over method bodies — catches copy-paste even
-after renames), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
-ranked by connectivity — tests are never executed), `verify_architecture`,
+after renames and can inspect strict small clones down to 12 tokens), `coverage_map` (existing coverage reports mapped onto the graph; untested hotspots
+ranked by connectivity — tests are never executed), `hot_path_review` (bounded local-cost evidence
+with separate graph/test risk), `verify_architecture`,
 `explain_architecture_violation`, `propose_architecture_exception`
 
+`hot_path_review` ranks production symbols using parser-derived local time, memory, cyclomatic and
+call-site facts plus exact inside-loop allocation, copy, scan, sort and recursion evidence. Graph
+fan-in/fan-out and measured coverage (or explicitly labelled static test reachability) remain
+separate from local syntax cost. The ranking is not profiler data or interprocedural Big-O.
+
 **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as
 `graph.prev.json`)
 
@@ -184,6 +193,23 @@ disclosed instead of silently guessed; and the server **hot-reloads its watched
 modules and catalog** when those files change — other MCP helpers and analysis engines require a
 reconnect.
 
+### 0.2.5 exact-symbol and graph-fidelity patch
+
+- New `inspect_symbol` spends a bounded LSP query on one requested TS/JS declaration, groups exact
+  occurrences by logical container, and returns definition/caller source context. Its separate LRU
+  cache is revision/config fingerprinted and never replaces the broad precision overlay.
+- Default-object service facades resolve to their underlying helpers, while `get_dependents` no
+  longer silently expands every symbol query to all importers of its file.
+- Python receiver-aware method dispatch and unambiguous wildcard imports distinguish same-named
+  methods across classes without promoting ambiguous dynamic evidence.
+- `run_audit` makes unused-dependency checking visible even when clean; dead-code review identifies
+  production symbols referenced only by tests; small-clone scanning can be lowered to 12 tokens with
+  stricter evidence rules.
+- `hot_path_review` adds a bounded offline performance-review queue with line-addressable local cost
+  evidence, separate graph risk, and honest measured/unavailable coverage states.
+
+Full patch notes: [docs/releases/v0.2.5.md](docs/releases/v0.2.5.md).
+
 ### 0.2.4 graph-mode correctness and semantic precision patch
 
 - `graph_diff base_ref=...` builds the immutable baseline in the current graph mode, so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "description": "Weavatrix — code graph & blast-radius MCP server for AI coding agents: change impact, transitive dependents, health audit, duplicate detection, and coverage mapping over any local repository.",
   "author": "Sergii Ziborov <sergii.ziborov@gmail.com>",

package/skill/SKILL.md

@@ -40,12 +40,13 @@ Start from the task, not from the complete tool list:
   `get_dependents` and `read_source`.
 - **Trace an API across repositories**: `list_known_repos` -> `trace_api_contract` with an explicit
   backend and client list; inspect each `graphReconciliation.buildMode` before using the verdict.
-- **Inspect exact symbol references**: start with `graph_stats` and read semantic precision state,
-  provider and `EXACT_LSP` count. For TypeScript/JavaScript, use an exact node id with
-  `get_dependents` and inspect the edge provenance; use `find_dead_code` for bounded zero-reference
+- **Inspect exact symbol references**: start with `graph_stats`, then call `inspect_symbol` with an
+  exact node ID (or an unambiguous label). It spends a bounded point query beyond the broad overlay
+  cap and returns occurrence containers plus source context. Use `get_dependents` for transitive
+  graph impact and `find_dead_code` for bounded zero-reference
   candidates. Treat `PARTIAL`, `UNAVAILABLE`, `OFF`, or zero exact edges as incomplete evidence, not
   a compiler-exact result; `OFF` means the caller explicitly selected static-only mode. Java and Rust
-  providers are not bundled in 0.2.4, so their edges never become `EXACT_LSP` even when a mixed
+  providers are not bundled in 0.2.5, so their edges never become `EXACT_LSP` even when a mixed
   repository has a complete TypeScript/JavaScript overlay.
 - **Explore an architectural question**: use broad `query_graph` when entry points are unknown; its
   bootstrap/tool-execution ranking prefers production executables over docs, sites and fixtures.
@@ -89,7 +90,13 @@ Start from the task, not from the complete tool list:
   `seed_files` to `query_graph` when the intended entry points are already known.
 - **Coverage**: `coverage_map` reads an existing report. `unavailable` means no supported report was
   found, not 0% coverage; do not rank testing risk from that state.
-- **Audit completeness**: read `checks.osv.status` and `checks.malware.status`. For OSV, `OK` is
+- **Local hot paths**: `hot_path_review` ranks parser-derived local syntax cost and reports graph
+  fan-in/fan-out plus test evidence separately. `actualCoverage: NOT_AVAILABLE` is not zero coverage,
+  and the score is not profiler data or an interprocedural Big-O proof. Inspect its line evidence and
+  measure runtime before scheduling a performance rewrite.
+- **Audit completeness**: read `dependencyReport.status` plus its unused/missing counts, then
+  `checks.osv.status` and `checks.malware.status`. A dependency result from a partial graph is not a
+  repository-wide clean zero. For OSV, `OK` is
   complete for the recorded dependency fingerprint; `PARTIAL` is incomplete or stale,
   `NOT_CHECKED` has no repository-specific result, and `ERROR` means the local check failed. Treat
   the same non-`OK` states as incomplete for malware scanning. Refresh OSV only when the user has
@@ -118,8 +125,10 @@ Start from the task, not from the complete tool list:
 - **Orient in the configured repo**: `module_map` → `list_communities` → `god_nodes`. Hub ranking
   is production-only by default; use `include_classified:true` only when tests/generated/build
   surfaces are deliberately part of the question.
-- **Refactor safety for one symbol**: `get_dependents` → `coverage_map` (low coverage × many
+- **Refactor safety for one symbol**: `inspect_symbol` → `get_dependents` → `coverage_map` (low coverage × many
   dependents ⇒ write tests first) → `read_source`.
+- **Performance review**: `hot_path_review` → inspect its local evidence with `read_source` → use
+  `get_dependents` for change risk → confirm with the repository's profiler/benchmark before editing.
 - **Pre-PR review of your current changes**: `change_impact` (auto merge-base; includes uncommitted
   and untracked work, coverage attached, untested hotspots called out) → drill with `get_dependents`.
 - **Impact of a PR that is NOT checked out**: pass its changed-file list explicitly —
@@ -131,7 +140,8 @@ Start from the task, not from the complete tool list:
   orphan drift rather than raw edge counts.
 - **Health sweep**: for a branch/PR review prefer
   `run_audit base_ref=<merge-base> debt=new changed_files=[…]`; for repository maintenance use
-  `run_audit debt=all`. Then call `find_dead_code`, `find_duplicates` and `coverage_map`. A changed-file-only audit is
+  `run_audit debt=all`. Then call `find_dead_code`, `find_duplicates`, `coverage_map` and
+  `hot_path_review`. A changed-file-only audit is
   scope, not proof of new debt. Inspect the source behind shortlisted findings before proposing edits.
 - **Dead-code and dead-method review**: call `find_dead_code` for a bounded production-code queue of
   files, functions, methods and symbols. Narrow with `path` or `kinds=["method"]`; keep the default

package/src/analysis/dead-check.js

@@ -100,7 +100,16 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
   const nodes = graph.nodes || [], links = graph.links || [];
   const ep = (v) => (v && typeof v === "object" ? v.id : v);
   const inbound = new Set();
-  for (const l of links) if (!isStructuralRelation(l.relation)) inbound.add(ep(l.target));
+  const inboundSources = new Map();
+  const nodesById = new Map(nodes.map((node) => [String(node.id), node]));
+  for (const l of links) if (!isStructuralRelation(l.relation)) {
+    const target = String(ep(l.target));
+    const source = String(ep(l.source));
+    inbound.add(target);
+    const values = inboundSources.get(target) || [];
+    values.push(source);
+    inboundSources.set(target, values);
+  }
 
   // whole-repo identifier frequency: a symbol whose name appears MORE than once total (its definition + at least
   // one use, same-file OR cross-file) is referenced. Errs toward "alive" (common-named symbols never flagged).
@@ -115,6 +124,16 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
     (symsByFile.get(n.source_file) || symsByFile.set(n.source_file, []).get(n.source_file)).push(n);
   }
 
+  const symbolNames = new Set([...symById.values()].map((node) => bareName(node.label)).filter(Boolean));
+  const occurrenceFiles = new Map();
+  for (const [file, text] of sources) for (const match of String(text || "").matchAll(IDENT_RE)) {
+    const name = match[0];
+    if (!symbolNames.has(name)) continue;
+    const files = occurrenceFiles.get(name) || new Set();
+    files.add(file);
+    occurrenceFiles.set(name, files);
+  }
+
   // decorated defs (@app.route/@app.event/@pytest.fixture…) are entered by the framework: trust the
   // builder's flag when present, else walk the source line(s) above the definition (graph-builder graphs).
   const lineCache = new Map();
@@ -151,6 +170,32 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
   }
   const deadSet = new Set(deadSymbols.map((s) => s.id));
 
+  // A production declaration consumed only by tests is live to the raw graph but dead to production.
+  // Keep it in a separate review class: this is useful evidence, never an automatic delete verdict.
+  const testOnlySymbols = [];
+  for (const n of symById.values()) {
+    if (deadSet.has(n.id) || isTestFile(n.source_file) || isDecorated(n)) continue;
+    const sourcesForSymbol = inboundSources.get(String(n.id)) || [];
+    const sourceFiles = sourcesForSymbol.map((id) => nodesById.get(id)?.source_file || (id.includes("#") ? id.split("#")[0] : id));
+    const hasTestInbound = sourceFiles.some((file) => isTestFile(file));
+    const hasProductionInbound = sourceFiles.some((file) => file && !isTestFile(file));
+    const name = bareName(n.label);
+    const occurrenceSet = occurrenceFiles.get(name) || new Set();
+    const externalOccurrences = [...occurrenceSet].filter((file) => file !== n.source_file);
+    const lexicalTestOnly = externalOccurrences.length > 0 && externalOccurrences.every((file) => isTestFile(file));
+    if (hasProductionInbound || (!hasTestInbound && !lexicalTestOnly)) continue;
+    testOnlySymbols.push({
+      id: n.id,
+      file: n.source_file,
+      label: n.label,
+      test: false,
+      reason: "referenced only from test/e2e code; no production consumer was found",
+      testConsumerFiles: [...new Set(sourceFiles.filter((file) => file && isTestFile(file)))].sort(),
+      evidence: hasTestInbound ? "graph" : "lexical",
+      publicApi: n.exported === true || ["public", "protected"].includes(String(n.visibility || "").toLowerCase()),
+    });
+  }
+
   const deadFiles = [];
   for (const n of nodes) {
     if (String(n.id).includes("#")) continue;                   // file nodes only
@@ -161,9 +206,10 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
 
   return {
     deadSymbols,
+    testOnlySymbols,
     deadFiles,
     referencedIds: [...symById.values()].filter(isReferenced).map((n) => n.id),
-    stats: { symbols: symById.size, deadSymbols: deadSymbols.length, files: nodes.filter((n) => !String(n.id).includes("#")).length, deadFiles: deadFiles.length },
+    stats: { symbols: symById.size, deadSymbols: deadSymbols.length, testOnlySymbols: testOnlySymbols.length, files: nodes.filter((n) => !String(n.id).includes("#")).length, deadFiles: deadFiles.length },
   };
 }
 

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

@@ -45,6 +45,7 @@ function symbolCandidate(item, node, context) {
   const source = String(context.sources.get(file) || "");
   const pathInfo = context.classify(file, source);
   const publicSurface = isPublicSurface(node);
+  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);
@@ -86,7 +87,7 @@ function symbolCandidate(item, node, context) {
   return {
     id: String(item.id),
     kind,
-    classification: publicSurface ? `public-${kind}` : kind === "method" ? "internal-method" : kind === "function" ? "internal-function" : "unreferenced-symbol",
+    classification: testOnly ? `test-only-${kind}` : publicSurface ? `public-${kind}` : kind === "method" ? "internal-method" : kind === "function" ? "internal-function" : "unreferenced-symbol",
     file,
     line: lineOf(node),
     symbol: bareLabel(node?.label || item.label),
@@ -96,8 +97,8 @@ function symbolCandidate(item, node, context) {
     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." },
+      ...(testOnly ? [{kind: item.evidence || "graph", fact: `Only test/e2e consumers were found${item.testConsumerFiles?.length ? `: ${item.testConsumerFiles.join(", ")}` : "."}`}]
+        : [{ 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." }]),
       ...(exactNoReference ? [{kind: "exact-lsp", fact: "The active language server returned no in-workspace references for this exact declaration."}] : []),
     ],
     caveats,
@@ -105,7 +106,9 @@ function symbolCandidate(item, node, context) {
     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.",
+    reviewAction: testOnly
+      ? "Confirm that no production/config/framework consumer exists; decide whether the declaration is intentional test support or removable with its tests. Never auto-delete."
+      : "Confirm with read_source, get_dependents, exact search, framework/config inspection and tests; never auto-delete.",
   };
 }
 
@@ -182,7 +185,7 @@ export function computeDeadCodeReview(graph, sources, options = {}) {
   const context = { sources, entrySet, dynamicTargets, frameworkByFile, classify, repoSignals, exactNoReferenceIds };
   const dead = computeDead(graph, sources, { entrySet });
   const nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
-  const rawSymbols = dead.deadSymbols
+  const rawSymbols = [...dead.deadSymbols, ...(dead.testOnlySymbols || []).map((item) => ({...item, testOnly: true}))]
     .map((item) => ({ item, node: nodesById.get(String(item.id)) }))
     .filter((entry) => entry.node)
     .map(({ item, node }) => symbolCandidate(item, node, context));
@@ -236,6 +239,7 @@ export function computeDeadCodeReview(graph, sources, options = {}) {
       indexedSymbols: dead.stats.symbols,
       indexedFiles: dead.stats.files,
       rawDeadSymbols: rawSymbols.length,
+      rawTestOnlySymbols: (dead.testOnlySymbols || []).length,
       rawDeadFiles: rawFiles.length,
       reviewCandidates: candidates.length,
       byConfidence: {

package/src/analysis/duplicates.compute.js

@@ -6,7 +6,7 @@ import { createPathClassifier, hasPathClass } from "../path-classification.js";
 import { listRepoFiles } from "./internal-audit.collect.js";
 import { stripNonCode, bodyEndLineCount, tokenize, fingerprints, extractLargeStrings } from "./duplicates.tokenize.js";
 
-const FLOOR_TOKENS = 30;   // fragments below this never enter the index (UI slider min)
+const FLOOR_TOKENS = 12;   // absolute safety floor; normal scans still default to 30+ tokens
 const FLOOR_SIM = 0.5;     // pairs below this are not reported (UI slider min)
 const MAX_BODY_LINES = 400;
 // File types with no code SYMBOLS to fragment (stylesheets, markup, docs, single-file components). The
@@ -93,7 +93,11 @@ function pairsForMode(frags, mode) {
     const i = Math.floor(key / 1000000), j = key % 1000000;
     const union = eff[i] + eff[j] - count;
     const sim = union > 0 ? count / union : 0;
-    if (sim >= FLOOR_SIM && count >= MIN_SHARED_FP) pairs.push([i, j, Math.round(sim * 100)]);
+    const smallFragment = Math.min(frags[i].n, frags[j].n) < 30;
+    const enoughEvidence = smallFragment
+      ? sim >= 0.95 && count >= 2
+      : count >= MIN_SHARED_FP;
+    if (sim >= FLOOR_SIM && enoughEvidence) pairs.push([i, j, Math.round(sim * 100)]);
   }
   return pairs;
 }
@@ -125,6 +129,7 @@ function loadGraph(graphInput) {
 
 export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   const includeStrings = !!opts.includeStrings;
+  const scanTokenFloor = Math.max(FLOOR_TOKENS, Math.min(400, Number(opts.minTokens) || 30));
   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
@@ -169,7 +174,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       const end = start + body.length - 1;
       if (end - start < 2) continue;
       const toks = tokenize(stripNonCode(body.join("\n"), py));
-      if (toks.strict.length < FLOOR_TOKENS) continue;
+      if (toks.strict.length < scanTokenFloor) continue;
       frags.push({
         id: syms[i].id, label: syms[i].label, file, start, end,
         n: toks.strict.length,
@@ -184,7 +189,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       const base = file.split("/").pop();
       const pushStr = (startLine, endLine, content) => {
         const toks = tokenize(content);
-        if (toks.strict.length < FLOOR_TOKENS) return;
+        if (toks.strict.length < scanTokenFloor) return;
         frags.push({
           id: `${file}#str@${startLine}`, label: `${base}:${startLine} ~${endLine - startLine + 1}-line string`,
           file, start: startLine, end: endLine, n: toks.strict.length, ...classificationFields(pathInfo), kind: "string",
@@ -224,7 +229,7 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       const end = Math.min(start + WINDOW_LINES - 1, lines.length);
       if (end - start < 2) continue;
       const toks = tokenize(stripNonCode(lines.slice(start - 1, end).join("\n"), false));
-      if (toks.strict.length < FLOOR_TOKENS) continue;
+      if (toks.strict.length < scanTokenFloor) continue;
       frags.push({
         id: `${file}#win@${start}`, label: `${file.split("/").pop()}:${start}-${end}`, file, start, end,
         n: toks.strict.length, ...classificationFields(pathInfo),
@@ -250,6 +255,6 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
       },
       nameTwinsTruncated: !!nameTwins && nameTwins.length >= 200,
     },
-    floors: { tokens: FLOOR_TOKENS, sim: FLOOR_SIM * 100 },
+    floors: { tokens: scanTokenFloor, absoluteTokens: FLOOR_TOKENS, sim: FLOOR_SIM * 100 },
   };
 }

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

@@ -0,0 +1,228 @@
+// Bounded local hot-path review over parser-derived complexity facts. This deliberately keeps
+// local syntax cost, graph coupling and test evidence separate: it is a review queue, not a runtime
+// profiler or an interprocedural Big-O proof.
+import {readCoverageForRepo, normalizeRepoParts} from './coverage-reports.js'
+import {computeStaticTestReachability} from './static-test-reachability.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
+import {isStructuralRelation} from '../graph/relations.js'
+
+const NON_PRODUCT = ['generated', '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 = (value, fallback, min, max) => {
+    const number = Number(value)
+    return Number.isInteger(number) ? Math.max(min, Math.min(max, number)) : fallback
+}
+const round = (value) => Math.round(Number(value || 0) * 100) / 100
+const clamp = (value, min = 0, max = 100) => Math.max(min, Math.min(max, Number(value) || 0))
+
+function normalizeScope(value) {
+    const path = normalize(value)
+    if (!path) return {ok: true, path: ''}
+    if (path.includes('\0') || /^[a-z]:\//i.test(path) || path.startsWith('/') || path.split('/').includes('..')) {
+        return {ok: false, error: 'path must be repository-relative and cannot contain traversal segments'}
+    }
+    return {ok: true, path}
+}
+
+function coverageForRange(record, startLine, endLine) {
+    if (!record) return null
+    if (!(record.lines instanceof Map) || !record.lines.size) return Number.isFinite(record.pct) ? record.pct : null
+    let total = 0
+    let covered = 0
+    for (let line = Math.max(1, startLine); line <= Math.max(startLine, endLine); line++) {
+        if (!record.lines.has(line)) continue
+        total++
+        if (Number(record.lines.get(line)) > 0) covered++
+    }
+    return total ? covered / total : Number.isFinite(record.pct) ? record.pct : null
+}
+
+function graphRiskBySymbol(graph, symbolIds) {
+    const state = new Map([...symbolIds].map((id) => [id, {
+        incoming: 0, outgoing: 0, callers: new Set(), callees: new Set(),
+    }]))
+    for (const link of graph?.links || []) {
+        if (!link || link.typeOnly === true || link.compileOnly === true || link.barrelProxy === true || isStructuralRelation(link.relation)) continue
+        const source = endpoint(link.source)
+        const target = endpoint(link.target)
+        if (!source || !target || source === target) continue
+        if (state.has(source)) {
+            const item = state.get(source)
+            item.outgoing++
+            item.callees.add(target)
+        }
+        if (state.has(target)) {
+            const item = state.get(target)
+            item.incoming++
+            item.callers.add(source)
+        }
+    }
+    return new Map([...state].map(([id, item]) => [id, {
+        fanIn: item.callers.size,
+        fanOut: item.callees.size,
+        incomingEdges: item.incoming,
+        outgoingEdges: item.outgoing,
+    }]))
+}
+
+function localSyntaxScore(complexity, thresholds) {
+    const insideLoop = Number(complexity.allocationsInLoops || 0)
+        + Number(complexity.copiesInLoops || 0)
+        + Number(complexity.linearOpsInLoops || 0)
+        + Number(complexity.sortsInLoops || 0) * 2
+        + Number(complexity.recursionInLoops || 0) * 2
+    const score = Number(complexity.timeRank || 0) * 12
+        + Number(complexity.memoryRank || 0) * 5
+        + Math.min(18, Number(complexity.cyclomatic || 1) / thresholds.cyclomatic * 10)
+        + Math.min(12, Number(complexity.callCount || 0) / thresholds.calls * 6)
+        + Math.min(18, Number(complexity.maxLoopDepth || 0) * 5)
+        + Math.min(24, insideLoop * 5)
+        + (complexity.recursion ? 6 : 0)
+    return round(clamp(score))
+}
+
+function couplingScore(risk) {
+    return round(clamp(Math.log2(1 + risk.fanIn) * 20 + Math.log2(1 + risk.fanOut) * 10))
+}
+
+function reasonsFor(complexity, thresholds) {
+    const reasons = []
+    if (Number(complexity.timeRank || 0) >= thresholds.timeRank) reasons.push(String(complexity.timeLabel || `local time rank ${complexity.timeRank}`))
+    if (Number(complexity.cyclomatic || 0) >= thresholds.cyclomatic) reasons.push(`cyclomatic ${complexity.cyclomatic} >= ${thresholds.cyclomatic}`)
+    if (Number(complexity.callCount || 0) >= thresholds.calls) reasons.push(`${complexity.callCount} local call sites >= ${thresholds.calls}`)
+    if (Number(complexity.maxLoopDepth || 0) >= thresholds.loopDepth) reasons.push(`loop depth ${complexity.maxLoopDepth} >= ${thresholds.loopDepth}`)
+    if (complexity.allocationsInLoops) reasons.push(`${complexity.allocationsInLoops} allocation(s) inside iteration`)
+    if (complexity.copiesInLoops) reasons.push(`${complexity.copiesInLoops} copy/copies inside iteration`)
+    if (complexity.linearOpsInLoops) reasons.push(`${complexity.linearOpsInLoops} linear operation(s) inside iteration`)
+    if (complexity.sortsInLoops) reasons.push(`${complexity.sortsInLoops} sort(s) inside iteration`)
+    if (complexity.recursionInLoops) reasons.push(`${complexity.recursionInLoops} recursive call(s) inside iteration`)
+    if (complexity.recursion) reasons.push('direct recursion; bound remains unknown')
+    return [...new Set(reasons)].slice(0, 12)
+}
+
+export function computeHotPathReview(graph, options = {}) {
+    const scope = normalizeScope(options.path)
+    if (!scope.ok) return {ok: false, error: scope.error}
+    const thresholds = {
+        cyclomatic: boundedInt(options.cyclomaticThreshold, 8, 2, 1000),
+        calls: boundedInt(options.callThreshold, 12, 1, 10000),
+        loopDepth: boundedInt(options.loopDepthThreshold, 2, 1, 10),
+        timeRank: boundedInt(options.timeRankThreshold, 2, 0, 5),
+        minScore: boundedInt(options.minScore, 0, 0, 100),
+    }
+    const topN = boundedInt(options.topN, 20, 1, 100)
+    const classifier = createPathClassifier(options.repoRoot || null)
+    const knownFiles = [...new Set((graph?.nodes || []).map((node) => normalize(node?.source_file)).filter(Boolean))]
+    const measuredCoverage = options.repoRoot ? readCoverageForRepo(options.repoRoot, knownFiles) : new Map()
+    const coverageSources = [...new Set([...measuredCoverage.values()].map((item) => item?.source).filter(Boolean))].sort()
+    const staticTests = measuredCoverage.size || !options.repoRoot
+        ? null
+        : computeStaticTestReachability(graph, {repoRoot: options.repoRoot, path: scope.path})
+    const staticByFile = new Map((staticTests?.reachable || []).map((item) => [normalize(item.file), item]))
+
+    const eligible = []
+    const excluded = {tests: 0, classified: 0, outOfScope: 0}
+    for (const node of graph?.nodes || []) {
+        const complexity = node?.complexity
+        const file = normalize(node?.source_file)
+        if (!complexity || !file || !String(node?.id || '').includes('#')) continue
+        if (scope.path && file !== scope.path && !file.startsWith(`${scope.path}/`)) { excluded.outOfScope++; continue }
+        const classification = classifier.explain(file)
+        const test = hasPathClass(classification, 'test', 'e2e')
+        const classified = classification.excluded || hasPathClass(classification, ...NON_PRODUCT)
+        if (test && options.includeTests !== true) { excluded.tests++; continue }
+        if (classified && options.includeClassified !== true) { excluded.classified++; continue }
+        eligible.push({node, complexity, file, classification: test ? 'test' : classified ? 'classified' : 'production'})
+    }
+
+    const riskById = graphRiskBySymbol(graph, new Set(eligible.map(({node}) => String(node.id))))
+    const candidates = []
+    for (const entry of eligible) {
+        const {node, complexity, file} = entry
+        const reasons = reasonsFor(complexity, thresholds)
+        if (!reasons.length) continue
+        const risk = riskById.get(String(node.id)) || {fanIn: 0, fanOut: 0, incomingEdges: 0, outgoingEdges: 0}
+        const syntaxScore = localSyntaxScore(complexity, thresholds)
+        const graphScore = couplingScore(risk)
+        const startLine = Number(complexity.startLine) || Number(String(node.source_location || '').replace(/^L/, '')) || 0
+        const endLine = Number(complexity.endLine) || Number(String(node.source_end || '').replace(/^L/, '')) || startLine
+        const coverageRecord = measuredCoverage.get(normalizeRepoParts(file)) || null
+        const actualCoverage = coverageForRange(coverageRecord, startLine, endLine)
+        const nearest = staticByFile.get(file)?.nearestTests?.[0] || null
+        const coverageRisk = actualCoverage == null ? 0 : (1 - actualCoverage) * 100
+        const score = round(clamp(syntaxScore * 0.72 + graphScore * 0.2 + coverageRisk * 0.08))
+        if (score < thresholds.minScore) continue
+        const directHotEvidence = Array.isArray(complexity.hotEvidence) ? complexity.hotEvidence.slice(0, 12) : []
+        const confidence = directHotEvidence.length ? 'HIGH' : complexity.recursion ? 'LOW' : 'MEDIUM'
+        candidates.push({
+            id: String(node.id),
+            label: String(node.label || node.norm_label || node.id),
+            kind: String(node.symbol_kind || 'symbol'),
+            file,
+            startLine,
+            endLine,
+            classification: entry.classification,
+            score,
+            confidence,
+            localSyntax: {
+                score: syntaxScore,
+                timeRank: Number(complexity.timeRank || 0),
+                timeLabel: String(complexity.timeLabel || ''),
+                memoryRank: Number(complexity.memoryRank || 0),
+                memoryLabel: String(complexity.memoryLabel || ''),
+                cyclomatic: Number(complexity.cyclomatic || 0),
+                calls: Number(complexity.callCount || 0),
+                loops: Number(complexity.loops || 0),
+                maxLoopDepth: Number(complexity.maxLoopDepth || 0),
+                allocationsInLoops: Number(complexity.allocationsInLoops || 0),
+                copiesInLoops: Number(complexity.copiesInLoops || 0),
+                linearOpsInLoops: Number(complexity.linearOpsInLoops || 0),
+                sortsInLoops: Number(complexity.sortsInLoops || 0),
+                recursionInLoops: Number(complexity.recursionInLoops || 0),
+                recursion: complexity.recursion === true,
+            },
+            graphRisk: {...risk, score: graphScore},
+            testEvidence: actualCoverage != null
+                ? {actualCoverage, source: coverageRecord?.source || 'coverage report'}
+                : nearest
+                    ? {actualCoverage: 'NOT_AVAILABLE', staticReachable: true, nearestTest: nearest.test, distance: nearest.distance, confidence: nearest.confidence}
+                    : {actualCoverage: 'NOT_AVAILABLE', staticReachable: false},
+            reasons,
+            sourceEvidence: directHotEvidence,
+        })
+    }
+    candidates.sort((left, right) => right.score - left.score
+        || right.localSyntax.score - left.localSyntax.score
+        || right.graphRisk.fanIn - left.graphRisk.fanIn
+        || left.id.localeCompare(right.id))
+    const hotspots = candidates.slice(0, topN)
+    return {
+        ok: true,
+        modelVersion: 1,
+        complexityVersion: Number(graph?.complexityV) || 0,
+        scope: {
+            path: scope.path || null,
+            includeTests: options.includeTests === true,
+            includeClassified: options.includeClassified === true,
+        },
+        thresholds,
+        analyzedSymbols: eligible.length,
+        candidateSymbols: candidates.length,
+        coverage: measuredCoverage.size
+            ? {actualCoverage: 'AVAILABLE', measuredFiles: measuredCoverage.size, sources: coverageSources}
+            : {actualCoverage: 'NOT_AVAILABLE', staticReachability: staticTests ? {
+                reachableFiles: staticTests.reachableFiles,
+                productFiles: staticTests.productFiles,
+                truncated: staticTests.bounds.truncated,
+            } : null},
+        excluded,
+        hotspots,
+        bounds: {topN, returned: hotspots.length, totalCandidates: candidates.length, truncated: candidates.length > hotspots.length},
+        caveats: [
+            'Scores rank parser-derived local syntax cost; they are not profiler measurements.',
+            'Graph risk is reported separately and does not propagate loop complexity through callees.',
+            'Recursion bounds, CFG reachability, dead stores and taint flow are not inferred by this model.',
+        ],
+    }
+}

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

@@ -139,6 +139,21 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
     }));
     unusedExportCount++;
   }
+  for (const symbol of dead.testOnlySymbols || []) {
+    if (isNonProductPath(symbol.file)) continue;
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "test-only-symbol",
+      severity: "low",
+      confidence: symbol.publicApi ? "low" : "medium",
+      title: `Production symbol used only by tests: ${symbol.label}`,
+      detail: `${symbol.reason}. Static analysis cannot rule out external or reflective consumers, so review before removal.`,
+      file: symbol.file,
+      graphNodeId: symbol.id,
+      source: "internal",
+      fixHint: "verify production/config consumers, then keep as intentional test support or remove it together with obsolete tests",
+    }));
+  }
 
   // ---- supply-chain: installed packages × cached OSV advisories. 100% OFFLINE here — the cache is
   // refreshed only by the explicit repos:advisory-refresh action. Never blocks the rest of the audit.
@@ -247,6 +262,13 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
   }
 
   const sorted = sortFindings(findings);
+  const dependencyFindings = sorted.filter((finding) => ["unused-dep", "missing-dep", "duplicate-dep"].includes(finding.rule));
+  const dependencyStatus = (graph.graphBuildMode && graph.graphBuildMode !== "full") || graph.graphBuildScope
+    ? "PARTIAL"
+    : "COMPLETE";
+  const importedPackages = new Set(externalImports
+    .filter((entry) => entry?.pkg && !entry.builtin && !entry.unresolved)
+    .map((entry) => `${entry.ecosystem || "npm"}:${entry.pkg}`));
   return {
     ok: true,
     engine: "internal",
@@ -276,10 +298,24 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
     },
     summary: summarizeFindings(sorted),
     findings: sorted,
+    dependencyReport: {
+      status: dependencyStatus,
+      declared: dep.declared.size + goDep.declared.size + pyDep.declared.size,
+      importedPackages: importedPackages.size,
+      importRecords: externalImports.length,
+      unused: dependencyFindings.filter((finding) => finding.rule === "unused-dep").length,
+      missing: dependencyFindings.filter((finding) => finding.rule === "missing-dep").length,
+      duplicateDeclarations: dependencyFindings.filter((finding) => finding.rule === "duplicate-dep").length,
+      packageScopes: packageScopes.length,
+      reason: dependencyStatus === "COMPLETE"
+        ? "All discovered dependency manifests were compared with the complete indexed import set."
+        : "The dependency result is scoped to a partial graph and is not a repository-wide clean bill.",
+    },
     deadReport: {
       deadSymbols: dead.deadSymbols.filter((symbol) => !isNonProductPath(symbol.file)).length,
       deadFiles: actionableDeadFiles.length,
       unusedExports: unusedExportCount,
+      testOnlySymbols: (dead.testOnlySymbols || []).filter((symbol) => !isNonProductPath(symbol.file)).length,
     },
     conventionReachability: {
       count: conventionEvidence.length,