weavatrix 0.2.3 → 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.
@@ -111,25 +112,42 @@ An agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — instal
 compile-only edges (Rust module/use, Java imports) are reported separately where that distinction
 changes the result.
 
-Every current edge also carries versioned provenance: `EXTRACTED`, `RESOLVED`, or `INFERRED` today,
-with `EXACT_LSP` and `CONFLICT` reserved for the optional precision overlay. `graph_stats` reports
-the complete breakdown; provenance describes how the relationship was established, while the older
-`confidence` field remains for compatibility.
+Every current edge carries versioned provenance. The parser emits `EXTRACTED`, `RESOLVED`, and
+`INFERRED`; the built-in bounded TypeScript/JavaScript precision overlay upgrades only references
+confirmed by its bundled `typescript-language-server` + TypeScript runtime to `EXACT_LSP`.
+`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.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`
+before starting the MCP server for parser-only operation from the first build, or pass
+`precision:"off"` to `rebuild_graph` / `open_repo`. The MCPB installer exposes the same `lsp` / `off`
+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`)
 
@@ -159,8 +177,10 @@ in the per-user cache and never need to be committed to Git.
 
 `query_graph` accepts optional `seed_files` when an architectural question must start from exact
 entry points. Resolved explicit seeds are exclusive by default; set `augment_seeds:true` only when
-fuzzy question-derived seeds are also wanted. Broad bootstrap/routing/authentication questions
-without explicit seeds rank conventional entry points and high-level modules ahead of incidental matches.
+question-derived seeds are also wanted. Broad bootstrap/tool-execution/routing questions now rank
+conventional executables and graph-declared production entry points ahead of site, documentation, benchmark
+and fixture matches. Broad ranking remains orientation evidence; use `seed_files` when the intended
+entry point is already known.
 
 **advisories** *(network, explicit opt-in)* — `refresh_advisories`
 
@@ -173,6 +193,57 @@ 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
+  `no-tests` graph is never compared with a hidden `full` universe. Previous-rebuild snapshots with
+  mismatched modes are rejected instead of reporting false removals or cycle drift.
+- `trace_api_contract` preserves each registered repository's build mode during refresh and exposes
+  that mode in `graphReconciliation`.
+- `graph_stats` and `open_repo` expose the canonical graph path and build mode; an explicit mode
+  mismatch with `build:false` fails closed instead of silently retargeting.
+- `module_map` is production-only by default and can opt back into classified tests, fixtures,
+  benchmarks, generated output and docs with `include_non_product:true`.
+- A bundled, read-only TypeScript/JavaScript language server validates a bounded set of semantic
+  references after graph reconciliation. Confirmed edges become `EXACT_LSP`; zero-reference evidence
+  can strengthen an internal dead-code candidate only after a successful exact query. Partial,
+  unavailable and revision-mismatched overlays stay visible and never become cosmetic exactness.
+  The provider is Weavatrix's pinned `typescript-language-server` + TypeScript runtime, never a
+  repository binary or `npx` download. Automatic type acquisition is disabled. Its child environment
+  is reduced to OS/temp/locale basics with a Node/System path; registry, proxy, cloud, token and
+  `NODE_OPTIONS` values are not inherited. TypeScript may still read locally declared project
+  configuration, dependencies and type declarations; Weavatrix accepts returned evidence only after
+  repository realpath containment. Applicable config chains are audited before provider startup;
+  configured language-service plugins and unresolved/outside config are refused, while semantic
+  inputs are fingerprinted before cache reuse and rechecked after each run. No source or evidence is
+  transmitted, and the provider performs no Weavatrix HTTP request. MCP EOF/SIGTERM drains or
+  tree-terminates TLS and tsserver before the stdio process exits.
+- Broad `query_graph` bootstrap and tool-execution ranking now prefers production executables and
+  graph-declared entry points over site, docs, benchmark and fixture surfaces. Exact `seed_files` remain
+  the deterministic option when the caller already knows the entry point.
+- The bundled skill routes orientation, diff review, cross-repository API tracing and exact-symbol
+  work through Weavatrix's own evidence states. Java/Rust exact providers remain `UNAVAILABLE` in
+  this release instead of being presented as compiler-confirmed.
+
+Full patch notes: [docs/releases/v0.2.4.md](docs/releases/v0.2.4.md).
+
 ### 0.2.3 real-wrapper patch
 
 - Auto-discovery recognizes wrappers that pass a fixed HTTP client method and argument array to a
@@ -379,9 +450,9 @@ vulnerability findings. This is where each capability comes from and how it is c
 | Capability alert | Why it exists | Activation and boundary |
 |---|---|---|
 | Network access | `refresh_advisories` sends pinned package names and versions to OSV; `pull_architecture_contract` sends an opaque repository UUID and receives an owner-approved contract; `sync_graph` sends a normalized repository label plus an allowlisted graph/evidence payload. Evidence is derived locally from source and manifests, but source bodies, snippets, absolute paths, environment values, credentials and Git remotes are excluded | `offline` and `pinned` expose no network tools. `osv` exposes only advisory refresh. `hosted`/`full` expose all three; every request still requires an explicit tool call, and hosted calls require `WEAVATRIX_SYNC_URL` |
-| Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; timed-out Windows child processes may be terminated | Used only by the corresponding local operation; it does not imply network access |
+| Shell access | Local `git` powers staleness/change impact; `rg` accelerates search; the bundled TLS/tsserver process supplies bounded JS/TS semantic evidence; timed-out Windows child trees may be terminated | Used only by the corresponding local operation. The semantic provider is package-pinned, disables automatic type acquisition, and never invokes a repository binary, script, installer or `npx` |
 | Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool entry modules; `createRequire` loads package metadata and parser dependencies | Loads files from the installed package; no `eval` |
-| Environment access | Reads `WEAVATRIX_*` configuration; local child processes inherit the normal host environment | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment and read only by `sync_graph` / `pull_architecture_contract` |
+| Environment access | Reads `WEAVATRIX_*` configuration; ordinary local helpers inherit a credential-stripped environment, while TLS/tsserver receives only allowlisted OS/temp/locale values and a constrained executable path | `WEAVATRIX_SYNC_TOKEN` is removed from every child-process and worker environment. TLS/tsserver also receives no registry/proxy/cloud credentials or `NODE_OPTIONS` |
 | Filesystem access | Reads the active repository, graph, lockfiles and coverage reports; writes derived graphs and advisory/architecture caches | Realpath containment blocks traversal and symlink/junction escapes. The `pinned` profile removes `open_repo`; the default `offline` profile permits only explicit local switching. The optional malware dependency scan may inspect installed dependency caches such as GOPATH |
 | URL strings | Fixed OSV/documentation URLs plus a user-configured sync URL | A URL string causes no request by itself; only the three network-profile tools perform requests |
 
@@ -435,9 +506,9 @@ loader) behind the thin stdio entry `src/mcp-server.mjs`.
   [app.weavatrix.com](https://app.weavatrix.com): explicit source-free sync,
   immutable history, Flow/DSM/Map, target architecture and bounded review
   evidence. Hosted use remains optional and owner-authenticated.
-- **Semantic precision bridge** — optional local language-server validation for
-  ambiguous impact, reference and dead-code evidence; the current parser graph
-  remains the offline fallback.
+- **Semantic precision bridge** shipped for TypeScript/JavaScript in 0.2.4: a bounded, revision-bound
+  local overlay validates references with the bundled language server while the parser graph remains
+  the fallback. Java and Rust providers are not bundled yet and stay explicitly `UNAVAILABLE`.
 - **Git-native architecture history** — bounded tag/ref timelines and branch
   reports built outside the worktree; graph artifacts stay out of Git.
 - **Cross-repository company evidence** — endpoints, events and internal

package/SECURITY.md

@@ -28,6 +28,24 @@ dependency caches such as GOPATH. `offline` permits repository switching only th
 local `open_repo` call; select `pinned` to remove that tool, the global repository listing, and
 cross-repository API tracing, holding a hard startup-repository boundary.
 
+The JS/TS precision overlay is enabled by default for new graphs and runs the package-pinned `typescript-language-server` and
+TypeScript runtime as local child processes. It never resolves a repository executable, invokes
+`npx`, runs package scripts, or installs dependencies. Automatic type acquisition is disabled, and
+the provider receives an allowlisted OS/temp/locale environment with a constrained executable path;
+registry, proxy, cloud, token and `NODE_OPTIONS` values are excluded. The provider makes no
+Weavatrix HTTP request and Weavatrix transmits no source or evidence. TypeScript may still read
+locally declared project configuration, dependencies and type declarations; returned evidence is
+accepted only after repository realpath containment. Before spawning the provider, Weavatrix parses
+the applicable repo-contained TypeScript/JavaScript config chains with its bundled TypeScript API and
+refuses semantic mode when a configured language-service plugin, unresolved/outside config, or input
+safety limit is encountered. Config and configured-project inputs are fingerprinted and rechecked
+before cached evidence is used and after each provider run.
+This is an application/process boundary rather than an operating-system
+network sandbox. On stdio EOF, SIGTERM or SIGINT, the MCP server stops new providers, performs a
+bounded graph-work drain, and closes or tree-terminates TLS/tsserver before exiting.
+Set `WEAVATRIX_PRECISION=off` before server startup (or select `off` in the MCPB semantic-precision
+setting) to keep new graphs parser-only from their first build.
+
 Network capabilities are split by purpose. `osv` adds only `refresh_advisories`, which sends pinned
 package names and versions to OSV.dev when called. `hosted` / `full` also expose `sync_graph` and
 `pull_architecture_contract`; both require a user-configured endpoint, and contract pull requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weavatrix",
-  "version": "0.2.3",
+  "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>",
@@ -55,6 +55,8 @@
   ],
   "dependencies": {
     "tree-sitter-wasms": "0.1.13",
+    "typescript": "5.9.3",
+    "typescript-language-server": "4.4.1",
     "web-tree-sitter": "0.25.10"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -29,6 +29,29 @@ Profiles use the same npm package and binary:
 The legacy `online` capability remains a compatibility alias for `advisories,hosted`; prefer the
 named profiles for new registrations.
 
+## Intent router
+
+Start from the task, not from the complete tool list:
+
+- **Orient in a repository**: `graph_stats` -> verify `Repo`, `Graph`, and `Build mode`; if the target
+  is wrong, call `open_repo`, then `graph_stats` again -> `module_map` (production-only by default).
+- **Review a branch/diff**: `change_impact` for changed-file blast radius; add
+  `graph_diff base_ref=<merge-base>` for structural drift, then drill into exact candidates with
+  `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`, 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.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.
+  Pass exact `seed_files` when the intended entry points are already known.
+
 ## Ground rules
 
 - **Evidence, not verdicts**: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a
@@ -47,11 +70,12 @@ named profiles for new registrations.
   `change_impact` and `graph_diff` label the distinction; `god_nodes` ranks unique connectivity and
   reports repeated references separately. Do not schedule a runtime-cycle refactor from
   compile-time-only edges.
-- **Edge provenance**: distinguish how an edge was established from legacy confidence. Current
-  graphs use `EXTRACTED`, `RESOLVED`, and `INFERRED`; `EXACT_LSP` is reserved for a bounded local
-  precision overlay and `CONFLICT` means evidence disagrees. Treat `INFERRED` and `CONFLICT` as
-  review signals rather than compiler-exact facts; an `UNKNOWN` count in `graph_stats` requires a
-  rebuild before precision-sensitive work.
+- **Edge provenance**: distinguish how an edge was established from legacy confidence. The parser
+  emits `EXTRACTED`, `RESOLVED`, and `INFERRED`; the bundled bounded TypeScript/JavaScript language
+  server emits `EXACT_LSP` only for references it confirms. `CONFLICT` means evidence disagrees.
+  Treat `INFERRED`, `CONFLICT`, `PARTIAL`, `UNAVAILABLE`, and `OFF` as review signals rather than
+  compiler-exact facts; an `UNKNOWN` count or revision-mismatched overlay in `graph_stats` requires
+  a rebuild before precision-sensitive work.
 - **Repository universe**: in Git repositories, graph and duplicate scans include tracked plus
   non-ignored untracked files. If an old graph still contains packaged/generated output, rebuild it
   before interpreting the result. Repository-root `.weavatrixignore` applies the same tracked-file
@@ -60,19 +84,28 @@ named profiles for new registrations.
   roots. Dead-code/clone/audit review also suppresses `benchmarks/**` and `**/__temp/**` as classified
   non-production surfaces. A verified production benchmark can opt back in narrowly through
   `.weavatrix.json` `classify.product`, for example `{"classify":{"product":["benchmarks/core/**"]}}`.
-- **Architectural queries**: for bootstrap/routing/authentication questions, inspect the returned
-  seeds before trusting the traversal. Pass exact repository-relative `seed_files` to `query_graph`
-  when the intended entry points are already known.
+- **Architectural queries**: broad bootstrap/tool-execution/routing questions rank conventional
+  production and graph-declared entry points ahead of classified docs, sites, benchmarks and
+  fixtures. Inspect the returned seeds before trusting the traversal. Pass exact repository-relative
+  `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
   authorized selecting the optional `osv` profile (or `advisories` capability) and then
   invoking `refresh_advisories`; enabling the group alone sends nothing.
-- **Offline by design**: scans and graph queries run in-process against local files; coverage tools
-  read existing reports and never run tests. The ONLY network-touching tools live in the optional
+- **Offline by design**: scans and graph queries use local files; the semantic overlay may launch
+  Weavatrix's bundled read-only TypeScript language-server child process, but it never runs repository
+  scripts or downloads a provider. Coverage tools read existing reports and never run tests. The
+  ONLY network-touching tools live in the optional
   `advisories` / `hosted` capabilities and run solely when explicitly called:
   `refresh_advisories` (queries OSV.dev with
   package names + versions so `run_audit` has fresh vulnerability data) and `sync_graph` (derives a
@@ -92,8 +125,10 @@ named profiles for new registrations.
 - **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 —
@@ -105,7 +140,8 @@ named profiles for new registrations.
   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,15 +45,24 @@ 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);
   const reflectionFile = REFLECTION_RE.test(source);
   const kind = kindOf(node);
-  let confidence = (String(node?.visibility || "").toLowerCase() === "private" || (!publicSurface && ["method", "function"].includes(kind)))
-    ? "high" : "medium";
+  const exactNoReference = context.exactNoReferenceIds.has(String(item.id));
+  const internallyScoped = String(node?.visibility || "").toLowerCase() === "private"
+    || (!publicSurface && ["method", "function"].includes(kind));
+  // Static absence alone is never high-confidence dead code. High is reserved for a successfully
+  // queried semantic declaration whose language server also returned no in-workspace references.
+  let confidence = internallyScoped && exactNoReference ? "high" : "medium";
   const caveats = [];
 
+  if (internallyScoped && !exactNoReference) {
+    caveats.push("No complete exact semantic no-reference result is available for this declaration; static absence remains medium confidence.");
+  }
+
   if (publicSurface) {
     confidence = "low";
     caveats.push("Public/exported APIs can be consumed by downstream packages, interfaces, reflection, dependency injection, templates, or configuration outside this repository.");
@@ -78,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),
@@ -88,15 +97,18 @@ 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,
     publicApi: publicSurface,
     externallyEnteredFile: externalEntry,
     pathClasses: pathInfo.classes || [],
     matchedPathRule: pathInfo.matchedRule || null,
-    reviewAction: "Confirm with read_source, get_dependents, exact search, framework/config inspection and tests; never auto-delete.",
+    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.",
   };
 }
 
@@ -169,10 +181,11 @@ export function computeDeadCodeReview(graph, sources, options = {}) {
   const minConfidence = Object.hasOwn(CONFIDENCE_RANK, options.minConfidence) ? options.minConfidence : "medium";
   const pathPrefix = normalizedPath(options.path || "").replace(/\/+$/, "");
   const requestedKinds = new Set(Array.isArray(options.kinds) && options.kinds.length ? options.kinds : ["file", "function", "method", "symbol"]);
-  const context = { sources, entrySet, dynamicTargets, frameworkByFile, classify, repoSignals };
+  const exactNoReferenceIds = new Set(graph.precisionNoReferenceSymbols || options.exactNoReferenceIds || []);
+  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));
@@ -226,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/git-ref-graph.js

@@ -7,6 +7,7 @@ import {tmpdir} from 'node:os'
 import {spawnSync} from 'node:child_process'
 import {childProcessEnv} from '../child-env.js'
 import {buildInternalGraph} from '../graph/internal-builder.js'
+import {filterGraphForMode} from '../graph/graph-filter.js'
 
 const SAFE_REF = /^(?!-)[A-Za-z0-9][A-Za-z0-9._\/@{}+~^-]{0,199}$/
 
@@ -68,7 +69,14 @@ export async function withGitRefCheckout(repoRoot, requestedRef, operation) {
     }
 }
 
-export async function buildGraphAtGitRef(repoRoot, requestedRef) {
-    const result = await withGitRefCheckout(repoRoot, requestedRef, async (checkout) => buildInternalGraph(checkout))
+export async function buildGraphAtGitRef(repoRoot, requestedRef, {mode = 'full'} = {}) {
+    const buildMode = ['full', 'no-tests', 'tests-only'].includes(mode) ? mode : 'full'
+    const result = await withGitRefCheckout(repoRoot, requestedRef, async (checkout) => {
+        const fullGraph = await buildInternalGraph(checkout)
+        return {
+            ...filterGraphForMode(fullGraph, buildMode, {repoRoot: checkout}),
+            graphBuildMode: buildMode,
+        }
+    })
     return result.ok ? {...result, graph: result.value} : result
 }