weavatrix 0.2.4 → 0.2.5

package/src/mcp/sync-payload.mjs

@@ -95,7 +95,8 @@ const COMPLEXITY_NUMBERS = [
     'startLine', 'endLine', 'loc', 'params', 'objectFields', 'branches', 'cyclomatic',
     'loops', 'maxLoopDepth', 'returns', 'awaits', 'callCount', 'externalCalls',
     'asyncBoundaries', 'allocations', 'objectLiterals', 'spreadCopies', 'sorts',
-    'linearOps', 'timeRank', 'timeScore', 'memoryRank', 'memoryScore',
+    'linearOps', 'allocationsInLoops', 'copiesInLoops', 'linearOpsInLoops',
+    'sortsInLoops', 'recursionInLoops', 'timeRank', 'timeScore', 'memoryRank', 'memoryScore',
 ];
 
 function sanitizeComplexity(value) {

package/src/mcp/tools-actions.mjs

@@ -91,7 +91,7 @@ export async function tOpenRepo(g, args, ctx) {
             savedPrecision = ['lsp', 'off'].includes(saved.graphPrecisionMode) ? saved.graphPrecisionMode : defaultPrecisionMode()
             schemaUpgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 2
                 || !Number.isInteger(saved.edgeProvenanceV) || saved.edgeProvenanceV < 1
-                || !Number.isInteger(saved.extractorSchemaV) || saved.extractorSchemaV < 3
+                || !Number.isInteger(saved.extractorSchemaV) || saved.extractorSchemaV < 4
             if (savedPrecision === 'lsp') {
                 const overlay = readPrecisionOverlay(graphPath, saved)
                 precisionUpgrade = !overlay || (typeof overlay.semanticInputFingerprint === 'string'

package/src/mcp/tools-health.mjs

@@ -11,6 +11,7 @@ import {summarizeCommunities, aggregateGraph} from '../analysis/graph-analysis.j
 import {detectEndpoints} from '../analysis/endpoints.js'
 import {computeStaticTestReachability} from '../analysis/static-test-reachability.js'
 import {computeDeadCodeReview} from '../analysis/dead-code-review.js'
+import {computeHotPathReview} from '../analysis/hot-path-review.js'
 import {collectNonRuntimeRoots, collectPackageScopes, collectSourceTexts, readRepoJson} from '../analysis/internal-audit.collect.js'
 import {entryFiles} from '../analysis/internal-audit.reach.js'
 import {buildInternalGraph} from '../graph/internal-builder.js'
@@ -53,7 +54,7 @@ function groupClones(data, {simMin, tokMin, mode, skipTests, includeClassified})
 export function tFindDuplicates(g, args, ctx) {
     if (!ctx.repoRoot) return 'Duplicate scan needs the repo root (not provided to this server).'
     const simMin = Math.min(100, Math.max(50, Number(args.min_similarity) || 80))
-    const tokMin = Math.min(400, Math.max(30, Number(args.min_tokens) || 50))
+    const tokMin = Math.min(400, Math.max(12, Number(args.min_tokens) || 50))
     const mode = args.mode === 'strict' ? 'strict' : 'renamed'
     const skipTests = args.include_tests ? false : true
     const includeClassified = args.include_classified === true || args.include_non_product === true
@@ -61,7 +62,7 @@ export function tFindDuplicates(g, args, ctx) {
     // semantic mode: same-name symbols across files, ranked by size — LOW similarity is the signal
     // (same name, drifted behavior). Token-clone pairing is skipped entirely.
     if (args.mode === 'semantic') {
-        const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {nameTwins: true})
+        const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {nameTwins: true, minTokens: tokMin})
         const frags = data.frags
         const candidates = []
         for (const twin of data.nameTwins || []) {
@@ -96,13 +97,14 @@ export function tFindDuplicates(g, args, ctx) {
         })
         return `Found ${candidates.length} actionable same-name pair(s) across files (semantic mode; one closest clone and/or farthest collision per name). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nThese are review candidates, not automatic refactors. Use read_source on both sites before changing code.`
     }
-    const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {includeStrings})
+    const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {includeStrings, minTokens: tokMin})
     const groups = groupClones(data, {simMin, tokMin, mode, skipTests, includeClassified})
+    const smallPolicy = tokMin < 30 ? ' Small fragments below 30 tokens require at least 95% similarity and two shared bounded fingerprints.' : ''
     const suppressed = data.frags.filter((fragment) => !fragmentEligible(fragment, {tokMin, skipTests, includeClassified})).length
     const suppressionNote = suppressed && !includeClassified
         ? ` ${suppressed} fragment(s) classified as tests/e2e/generated/mock/story/docs/benchmark/temp or matched by .weavatrix.json exclude were suppressed; pass include_classified:true (and include_tests:true for tests) to inspect them explicitly.`
         : ''
-    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${suppressionNote}`
+    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${smallPolicy}${suppressionNote}`
     const top = groups.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
     const lines = top.map((grp, k) => {
         const isStr = grp.members.some((f) => f.kind === 'string')
@@ -110,7 +112,7 @@ export function tFindDuplicates(g, args, ctx) {
         const sites = grp.members.slice(0, 8).map((f) => `     ${f.file}:${f.start}-${f.end}`)
         return [head, ...sites].join('\n')
     })
-    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${suppressionNote}`
+    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${smallPolicy}${suppressionNote}`
 }
 
 // Focused dead-code review queue. Unlike the broad run_audit surface, this includes functions and
@@ -227,10 +229,12 @@ const formatOrdinaryAudit = (audit, args, findings = audit.findings, heading = n
     const summary = summarizeFindings(findings)
     const sev = summary.bySeverity
     const bycat = summary.byCategory
+    const deps = audit.dependencyReport || {}
     return [
         heading,
         `Internal audit of ${audit.repo} (${audit.scanned.files} files, ${audit.scanned.symbols} symbols, ${audit.scanned.externalImports} external imports; malware scan: ${audit.scanned.malwareScanMode}).`,
         ...auditConventionLines(audit),
+        `Dependency manifests: ${deps.status || 'UNKNOWN'} — checked ${deps.declared ?? audit.scanned.manifestDeps ?? 0} declared package(s) against ${deps.importRecords ?? audit.scanned.externalImports ?? 0} external import record(s); unused ${deps.unused ?? 'unknown'}, missing ${deps.missing ?? 'unknown'}, duplicate declarations ${deps.duplicateDeclarations ?? 'unknown'}.`,
         `Scoped severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Scoped categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
         `Repository-level ${auditChecksLine(audit)}`,
         '',
@@ -418,11 +422,13 @@ export async function tRunAudit(g, args, ctx) {
     const shown = filtered.slice(0, max)
     const sev = audit.summary.bySeverity
     const bycat = audit.summary.byCategory
+    const deps = audit.dependencyReport || {}
     const check = (name, state) => `${name} ${state?.status || 'ERROR'}${state?.detail ? ` — ${state.detail}` : ''}`
     return [
         `Internal audit of ${audit.repo} (${audit.scanned.files} files, ${audit.scanned.symbols} symbols, ${audit.scanned.externalImports} external imports; malware scan: ${audit.scanned.malwareScanMode}).`,
         `Severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
         `Structure: ${audit.structureReport?.runtimeCycles ?? audit.structureReport?.cycles ?? 0} runtime cycle(s), ${audit.structureReport?.compileTimeCouplings ?? audit.structureReport?.typeCouplings ?? 0} compile-time coupling group(s), ${audit.structureReport?.orphans ?? 0} orphan(s); import edges: ${audit.structureReport?.runtimeImportEdges ?? audit.structureReport?.importEdges ?? 0} runtime + ${audit.structureReport?.typeOnlyImportEdges ?? 0} type-only + ${audit.structureReport?.compileOnlyImportEdges ?? 0} compile-only. Dead: ${audit.deadReport.deadFiles} file(s), ${audit.deadReport.unusedExports} unused export(s).`,
+        `Dependency manifests: ${deps.status || 'UNKNOWN'} — checked ${deps.declared ?? audit.scanned.manifestDeps ?? 0} declared package(s) against ${deps.importRecords ?? audit.scanned.externalImports ?? 0} external import record(s); unused ${deps.unused ?? 'unknown'}, missing ${deps.missing ?? 'unknown'}, duplicate declarations ${deps.duplicateDeclarations ?? 'unknown'}.`,
         ...auditConventionLines(audit),
         `Checks: ${check('OSV', audit.checks?.osv)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`,
         ``,
@@ -509,6 +515,61 @@ export function tModuleMap(g, args, ctx) {
     ].filter((line) => line != null).join('\n')
 }
 
+// Parser-backed local cost review. This keeps syntax, graph coupling and measured/static test
+// evidence as separate fields so callers cannot mistake a ranking heuristic for profiler output.
+export function tHotPathReview(g, args, ctx) {
+    const review = computeHotPathReview(rawGraph(ctx), {
+        repoRoot: ctx?.repoRoot || null,
+        path: args.path,
+        includeTests: args.include_tests === true,
+        includeClassified: args.include_classified === true,
+        topN: args.top_n,
+        cyclomaticThreshold: args.cyclomatic_threshold,
+        callThreshold: args.call_threshold,
+        loopDepthThreshold: args.loop_depth_threshold,
+        timeRankThreshold: args.time_rank_threshold,
+        minScore: args.min_score,
+    })
+    if (!review.ok) return toolResult(`Hot-path review refused: ${review.error}.`, review)
+    const pct = (value) => typeof value === 'number' ? `${Math.round(value * 100)}%` : String(value || 'NOT_AVAILABLE')
+    const coverageLine = review.coverage.actualCoverage === 'AVAILABLE'
+        ? `Measured coverage: ${review.coverage.measuredFiles} file(s) from ${review.coverage.sources.join(', ') || 'coverage report'}.`
+        : review.coverage.staticReachability
+            ? `actualCoverage: NOT_AVAILABLE; static test reachability ${review.coverage.staticReachability.reachableFiles}/${review.coverage.staticReachability.productFiles} product file(s).`
+            : 'actualCoverage: NOT_AVAILABLE; no measured or static test evidence was available.'
+    const text = [
+        `Local hot-path review: ${review.candidateSymbols} candidate(s) from ${review.analyzedSymbols} analyzed symbol(s); showing ${review.hotspots.length}.`,
+        `Thresholds: time rank >=${review.thresholds.timeRank}, cyclomatic >=${review.thresholds.cyclomatic}, calls >=${review.thresholds.calls}, loop depth >=${review.thresholds.loopDepth}, score >=${review.thresholds.minScore}.`,
+        coverageLine,
+        'Local syntax cost and graph coupling are separate. Scores are review priority, not measured runtime.',
+        '',
+        ...(review.hotspots.length ? review.hotspots.flatMap((item, index) => {
+            const tests = item.testEvidence.actualCoverage === 'NOT_AVAILABLE'
+                ? item.testEvidence.staticReachable ? `static-test d${item.testEvidence.distance}` : 'no-static-test-path'
+                : `coverage ${pct(item.testEvidence.actualCoverage)}`
+            const pointer = `${item.file}${item.startLine ? `:${item.startLine}${item.endLine > item.startLine ? `-${item.endLine}` : ''}` : ''}`
+            const evidence = item.sourceEvidence.length
+                ? `\n       evidence: ${item.sourceEvidence.map((entry) => `${entry.kind}@L${entry.line || '?'}${entry.detail ? ` (${entry.detail})` : ''}`).join('; ')}`
+                : ''
+            return [
+                `  ${String(index + 1).padStart(2)}. score ${String(item.score).padStart(5)}  syntax ${String(item.localSyntax.score).padStart(5)}  graph ${String(item.graphRisk.score).padStart(5)}  ${item.confidence}`,
+                `      ${item.label}  (${pointer}; fan-in ${item.graphRisk.fanIn}, fan-out ${item.graphRisk.fanOut}; ${tests})`,
+                `       ${item.reasons.slice(0, 5).join('; ')}${evidence}`,
+            ]
+        }) : ['  (none at the selected thresholds)']),
+        review.bounds.truncated ? `... +${review.bounds.totalCandidates - review.bounds.returned} more (raise top_n, min_score, or narrow path).` : null,
+        '',
+        'Caveat: no interprocedural Big-O, recursion-bound, CFG, dead-store or taint-flow claim is made.',
+    ].filter((line) => line != null).join('\n')
+    return toolResult(text, review, {
+        completeness: {
+            symbols: 'COMPLETE_FOR_INDEXED_GRAPH',
+            output: review.bounds.truncated ? 'BOUNDED' : 'COMPLETE',
+            coverage: review.coverage.actualCoverage,
+        },
+    })
+}
+
 // Coverage × graph: map an EXISTING coverage report (istanbul/lcov/coverage.py/Go — read offline,
 // tests are never executed here) onto files and symbols, then rank refactor risk as
 // connectivity × uncovered share. Pairs with get_dependents: many dependents + low coverage ⇒ write

package/src/mcp/tools-impact.mjs

@@ -59,7 +59,7 @@ const impactKind = (entry) => {
 // Transitive blast-radius: who is affected if this node changes. Walks REVERSE dependency edges
 // (calls/imports/inherits — not structural `contains`) out to `depth`. For a symbol, also seeds its
 // containing file, because importers depend on the file rather than the individual symbol.
-export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
+export function tGetDependents(g, {label, depth = 3, max_nodes = 40, include_container_importers = false} = {}) {
     const info = resolveNodeInfo(g, label)
     const n = info.node
     if (!n) return `No node found matching "${label}".`
@@ -69,7 +69,7 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
     const id = String(n.id)
     const seeds = new Set([id])
     let containingFile = null
-    if (isSymbol(id)) {
+    if (include_container_importers === true && isSymbol(id)) {
         const container = (g.inn.get(id) || []).find((e) => e.relation === 'contains')
         if (container) {
             containingFile = String(container.id)
@@ -88,7 +88,7 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
     return [
         note,
         `Dependents of ${n.label ?? id} (reverse calls/imports/inherits, depth ≤${maxDepth}): ${ranked.length} found (${runtimeCount} runtime, ${compileCount} compile-time-only), showing ${shown.length} by proximity + connectivity.`,
-        containingFile ? `Includes importers of its containing file ${labelOf(g, containingFile)}.` : null,
+        containingFile ? `Includes importers of its containing file ${labelOf(g, containingFile)} by explicit request.` : null,
         ...shown.map((r) => `  [d${r.d} ${impactKind(r.entry)}] ${r.entry.relation || 'rel'} [${r.entry.provenance || 'UNKNOWN'}]  ${labelOf(g, r.id)}  (deg ${r.deg})  [${r.id}]`),
     ].filter(Boolean).join('\n')
 }

package/src/mcp/tools-source.mjs

@@ -0,0 +1,237 @@
+import {readFileSync, statSync} from 'node:fs'
+import {resolveRepoPath} from '../repo-path.js'
+import {isStructuralRelation} from '../graph/relations.js'
+import {querySymbolPrecision} from '../precision/symbol-query.js'
+import {toolResult} from './tool-result.mjs'
+import {degreeOf, isSymbol, labelOf, resolveNodeInfo} from './graph-context.mjs'
+
+const MAX_EXCERPT_CHARS = 4_000
+const MAX_LOCATION_SAMPLES = 5
+const MAX_GRAPH_OCCURRENCES = 100
+
+const boundedInteger = (value, fallback, minimum, maximum) => {
+    const number = Number(value)
+    return Math.max(minimum, Math.min(maximum, Number.isFinite(number) ? Math.floor(number) : fallback))
+}
+
+const sourceLine = (node) => {
+    const match = /L(\d+)/.exec(String(node?.source_location || ''))
+    return match ? Number(match[1]) : 1
+}
+
+function candidateNodes(g, query, limit = 20) {
+    const text = String(query || '').trim().toLowerCase()
+    if (!text) return []
+    const exact = g.byLabel.get(text)
+    const nodes = exact?.length ? exact : g.nodes.filter((node) =>
+        String(node.id).toLowerCase().includes(text) || String(node.label || '').toLowerCase().includes(text))
+    return nodes.slice(0, limit).map((node) => ({id: String(node.id), label: String(node.label || node.id), file: node.source_file || null}))
+}
+
+function excerpt(repoRoot, file, focusLine, contextLines) {
+    const resolved = resolveRepoPath(repoRoot, file)
+    if (!resolved.ok) return null
+    let size
+    try { size = statSync(resolved.path).size } catch { return null }
+    if (size > 2 * 1024 * 1024) return null
+    let lines
+    try { lines = readFileSync(resolved.path, 'utf8').split(/\r?\n/) } catch { return null }
+    const focus = Math.max(1, Math.min(lines.length, Number(focusLine) || 1))
+    const startLine = Math.max(1, focus - contextLines)
+    const endLine = Math.min(lines.length, focus + contextLines)
+    const rawText = lines.slice(startLine - 1, endLine).join('\n')
+    return {
+        file,
+        focusLine: focus,
+        startLine,
+        endLine,
+        text: rawText.length > MAX_EXCERPT_CHARS ? `${rawText.slice(0, MAX_EXCERPT_CHARS)}\n… [excerpt truncated]` : rawText,
+        truncated: rawText.length > MAX_EXCERPT_CHARS,
+    }
+}
+
+function reverseImpact(g, targetId, depth = 3, cap = 40) {
+    const seen = new Map([[targetId, 0]])
+    const queue = [targetId]
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const current = queue[cursor]
+        const currentDepth = seen.get(current)
+        if (currentDepth >= depth) continue
+        for (const edge of g.inn.get(current) || []) {
+            if (isStructuralRelation(edge.relation) || edge.barrelProxy === true) continue
+            const id = String(edge.id)
+            if (seen.has(id)) continue
+            seen.set(id, currentDepth + 1)
+            queue.push(id)
+        }
+    }
+    return [...seen.entries()]
+        .filter(([id]) => id !== targetId)
+        .map(([id, distance]) => ({id, label: labelOf(g, id), distance, degree: degreeOf(g, id)}))
+        .sort((left, right) => left.distance - right.distance || right.degree - left.degree)
+        .slice(0, cap)
+}
+
+function graphOccurrences(g, targetId) {
+    const all = (g.inn.get(targetId) || [])
+        .filter((edge) => !isStructuralRelation(edge.relation) && edge.barrelProxy !== true)
+        .map((edge) => ({
+            source: String(edge.id),
+            label: labelOf(g, edge.id),
+            relation: edge.relation || 'references',
+            provenance: edge.provenance || 'UNKNOWN',
+            ...(Number.isInteger(edge.line) ? {line: edge.line} : {}),
+            ...(edge.typeOnly === true ? {typeOnly: true} : {}),
+            ...(edge.compileOnly === true ? {compileOnly: true} : {}),
+        }))
+    return {total: all.length, shown: all.slice(0, MAX_GRAPH_OCCURRENCES)}
+}
+
+function groupLocations(g, locations, cap) {
+    const groups = new Map()
+    for (const location of locations) {
+        const source = String(location.source || location.file || '')
+        if (!source) continue
+        const node = g.byId.get(source)
+        const file = String(location.file || node?.source_file || (isSymbol(source) ? source.split('#')[0] : source))
+        let group = groups.get(source)
+        if (!group) {
+            group = {id: source, label: String(node?.label || source), file, count: 0, classifications: {}, locations: []}
+            groups.set(source, group)
+        }
+        group.count++
+        const classification = String(location.classification || 'unknown')
+        group.classifications[classification] = (group.classifications[classification] || 0) + 1
+        if (group.locations.length < MAX_LOCATION_SAMPLES) group.locations.push({
+          line: location.line,
+          character: location.character,
+          ...(Number.isInteger(location.endLine) ? {endLine: location.endLine} : {}),
+          ...(Number.isInteger(location.endCharacter) ? {endCharacter: location.endCharacter} : {}),
+          classification,
+        })
+    }
+    const all = [...groups.values()].sort((left, right) => right.count - left.count || left.file.localeCompare(right.file) || left.id.localeCompare(right.id))
+    return {all, shown: all.slice(0, cap)}
+}
+
+function textFor(result) {
+    if (result.status === 'NOT_FOUND') return `No symbol found matching "${result.query}".`
+    if (result.status === 'AMBIGUOUS') return [
+        `Symbol "${result.query}" is ambiguous (${result.candidates.length} candidate(s) shown). Supply an exact node ID:`,
+        ...result.candidates.map((candidate) => `  ${candidate.label}  [${candidate.id}]`),
+    ].join('\n')
+    const definition = result.definition
+    const lines = [
+        `Symbol inspection: ${definition.label}  [${definition.id}]`,
+        `Definition: ${definition.file}:${definition.line}`,
+        `Evidence: ${result.evidence.state}${result.evidence.cached ? ' (cache hit)' : ''}; ${result.exact.occurrences} exact reference occurrence(s) in ${result.exact.files} file(s) / ${result.exact.containers} container(s).`,
+        `Graph: ${result.graph.occurrenceTotal} direct occurrence edge(s) (${result.graph.occurrences.length} shown); ${result.graph.impact.length} dependent(s) shown.`,
+    ]
+    if (result.evidence.reason) lines.push(`Completeness: ${result.evidence.reason}`)
+    if (result.exact.zeroReferences) lines.push('Exact result: zero non-declaration references in the completely covered project universe.')
+    if (result.exact.groups.length) {
+        lines.push('Reference containers:')
+        for (const group of result.exact.groups) lines.push(`  ${group.count} site(s)  ${group.label}  [${group.id}]`)
+    }
+    if (result.source.definition) {
+        const source = result.source.definition
+        lines.push('', `Definition source (${source.file}:${source.startLine}-${source.endLine}):`, source.text)
+    }
+    for (const source of result.source.callers) {
+        lines.push('', `Caller source (${source.file}:${source.startLine}-${source.endLine}, focus ${source.focusLine}):`, source.text)
+    }
+    return lines.join('\n')
+}
+
+export async function tInspectSymbol(g, args = {}, ctx = {}) {
+    const query = String(args.label || '').trim()
+    const info = resolveNodeInfo(g, query)
+    if (!info.node) return toolResult(textFor({status: 'NOT_FOUND', query}), {status: 'NOT_FOUND', query})
+    if (info.matches > 1 && !g.byId.has(query)) {
+        const result = {status: 'AMBIGUOUS', query, candidates: candidateNodes(g, query)}
+        return toolResult(textFor(result), result, {completeness: {status: 'blocked', reason: 'ambiguous symbol'}})
+    }
+    const node = info.node
+    const targetId = String(node.id)
+    if (!isSymbol(targetId)) {
+        const result = {status: 'UNSUPPORTED', query, candidates: [{id: targetId, label: node.label || targetId, file: node.source_file || targetId}]}
+        return toolResult('inspect_symbol requires a symbol node, not a file node.', result)
+    }
+    const maxReferences = boundedInteger(args.max_references, 1_000, 1, 5_000)
+    const maxContainers = boundedInteger(args.max_containers, 15, 1, 50)
+    const contextLines = boundedInteger(args.context_lines, 8, 0, 40)
+    const timeoutMs = boundedInteger(args.timeout_ms, 30_000, 1_000, 60_000)
+    const precision = ['auto', 'graph', 'lsp'].includes(args.precision) ? args.precision : 'auto'
+    const shouldQuery = precision === 'lsp' || (precision === 'auto' && g.graphPrecisionMode !== 'off')
+    let overlay = null
+    let cached = false
+    let elapsedMs = 0
+    let queryError = null
+    if (shouldQuery) {
+        try {
+            const queryResult = await querySymbolPrecision({repoRoot: ctx.repoRoot, graphPath: ctx.graphPath, targetId, maxReferences, timeoutMs})
+            overlay = queryResult.overlay
+            cached = queryResult.cached
+            elapsedMs = queryResult.elapsedMs
+        } catch (error) {
+            queryError = error?.message || 'exact symbol query failed'
+        }
+    }
+    const locations = Array.isArray(overlay?.locations) ? overlay.locations : []
+    const grouped = groupLocations(g, locations, maxContainers)
+    const files = new Set(locations.map((location) => String(location.file || '')).filter(Boolean))
+    let state = 'GRAPH_ONLY'
+    if (overlay?.state === 'COMPLETE') state = 'EXACT'
+    else if (overlay?.state === 'PARTIAL') state = 'PARTIAL'
+    else if (overlay?.state === 'OFF') state = 'OFF'
+    else if (shouldQuery) state = 'UNAVAILABLE'
+    const reason = queryError || overlay?.reason || (shouldQuery ? null : 'semantic precision was not requested')
+    const graphRefs = graphOccurrences(g, targetId)
+    const impact = reverseImpact(g, targetId)
+    const definition = {
+        id: targetId,
+        label: String(node.label || targetId),
+        kind: String(node.symbol_kind || 'symbol'),
+        file: String(node.source_file || targetId.split('#')[0]),
+        line: sourceLine(node),
+        ...(node.source_range ? {range: node.source_range} : {}),
+        ...(node.complexity ? {complexity: node.complexity} : {}),
+    }
+    const definitionSource = excerpt(ctx.repoRoot, definition.file, definition.line, contextLines)
+    const callerSources = grouped.shown.slice(0, 5).map((group) => excerpt(ctx.repoRoot, group.file, group.locations[0]?.line || 1, contextLines)).filter(Boolean)
+    const result = {
+        status: 'OK',
+        definition,
+        evidence: {state, cached, elapsedMs, reason, provider: overlay?.engines?.[0]?.provider || null},
+        exact: {
+            occurrences: locations.length,
+            occurrencesWithDefinition: locations.length + 1,
+            files: files.size,
+            containers: grouped.all.length,
+            groups: grouped.shown,
+            zeroReferences: overlay?.noReferenceSymbols?.includes(targetId) === true,
+            capped: overlay?.coverage?.truncated === true || grouped.all.length > grouped.shown.length,
+        },
+        graph: {
+            occurrences: graphRefs.shown,
+            occurrenceTotal: graphRefs.total,
+            occurrencesCapped: graphRefs.total > graphRefs.shown.length,
+            impact,
+        },
+        source: {definition: definitionSource, callers: callerSources},
+    }
+    const warnings = state === 'PARTIAL' || state === 'UNAVAILABLE'
+        ? [{code: 'SYMBOL_PRECISION_INCOMPLETE', message: reason || `semantic precision is ${state.toLowerCase()}`}]
+        : []
+    return toolResult(textFor(result), result, {
+        warnings,
+        completeness: {
+            status: state === 'EXACT' && !result.exact.capped ? 'complete' : state.toLowerCase(),
+            referenceLimit: maxReferences,
+            containerLimit: maxContainers,
+            returnedContainers: grouped.shown.length,
+            locationSamplesPerContainer: MAX_LOCATION_SAMPLES,
+            graphOccurrenceLimit: MAX_GRAPH_OCCURRENCES,
+        },
+    })
+}

package/src/precision/lsp-client.js

@@ -425,7 +425,7 @@ export class StdioLspClient {
         await this.writeMessage({jsonrpc: JSON_RPC_VERSION, method, params})
     }
 
-    async initialize({capabilities = {}, initializationOptions, clientInfo = {name: 'weavatrix', version: '0.2.4'}} = {}) {
+    async initialize({capabilities = {}, initializationOptions, clientInfo = {name: 'weavatrix', version: '0.2.5'}} = {}) {
         if (this.state !== 'running') throw new Error(`LSP initialize is invalid in state=${this.state}`)
         const result = await this.request('initialize', {
             processId: process.pid,

package/src/precision/lsp-overlay.js

@@ -274,8 +274,16 @@ function sourceAt(index, file, position) {
   return index.files.has(file) ? file : null;
 }
 
-function eligibleTargets(graph, limit) {
+function eligibleTargets(graph, limit, requestedIds = null) {
   const byId = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
+  if (Array.isArray(requestedIds) && requestedIds.length) {
+    const ids = [...new Set(requestedIds.map(String))];
+    const targets = ids
+      .map((id) => byId.get(id))
+      .filter((node) => node?.selection_start && JS_TS_FILE.test(String(node.source_file || "")))
+      .slice(0, limit);
+    return {targets, total: ids.length, orphanIds: new Set()};
+  }
   const ranked = new Map();
   const inbound = new Set();
   for (const link of graph.links || []) {
@@ -456,6 +464,7 @@ export async function buildLspPrecisionOverlay({
   maxReferences = Number(process.env.WEAVATRIX_PRECISION_MAX_REFERENCES) || 2_048,
   maxLinks = Number(process.env.WEAVATRIX_PRECISION_MAX_LINKS) || 2_048,
   timeoutMs = Number(process.env.WEAVATRIX_PRECISION_TIMEOUT_MS) || 45_000,
+  targetIds,
   clientFactory,
 } = {}) {
   if (!graph || !repoRoot) throw new Error("precision overlay requires repoRoot and graph");
@@ -501,7 +510,7 @@ export async function buildLspPrecisionOverlay({
       && precisionOverlayMatches(cached, graph, {request})
       && cached.semanticInputFingerprint === semanticInputs.fingerprint) return cached;
   }
-  const eligible = eligibleTargets(graph, boundedMax);
+  const eligible = eligibleTargets(graph, boundedMax, targetIds);
   const targets = eligible.targets;
   if (!targets.length) {
     const overlay = baseOverlay(graph, "COMPLETE", {
@@ -525,6 +534,8 @@ export async function buildLspPrecisionOverlay({
   let truncated = eligible.total > boundedMax;
   const noReferenceSymbols = [];
   const referenceEvidence = [];
+  const exactLocations = [];
+  const collectLocations = Array.isArray(targetIds) && targetIds.length > 0;
   const opened = new Set();
   const openedTexts = new Map();
   const classificationTexts = new Map();
@@ -708,7 +719,6 @@ export async function buildLspPrecisionOverlay({
         const start = locationStart(location);
         if (!file || !start || !Number.isInteger(start.line) || !Number.isInteger(start.character)) continue;
         const source = sourceAt(index, file, start);
-        if (!source || source === String(target.id)) continue;
         const targetId = String(target.id);
         const exactLine = start.line + 1;
         const exactCharacter = start.character;
@@ -727,6 +737,20 @@ export async function buildLspPrecisionOverlay({
           : classifyTypeScriptReferenceUsage(file, sourceText, start);
         if (usage === "unknown" && moduleDependency?.typeOnly === true) usage = "type";
         if (usage === "unknown" && moduleDependency?.compileOnly === true) usage = "compile";
+        if (collectLocations) exactLocations.push({
+          file,
+          source: source || file,
+          target: targetId,
+          line: exactLine,
+          character: exactCharacter,
+          ...(Number.isInteger(location?.range?.end?.line) ? {endLine: location.range.end.line + 1} : {}),
+          ...(Number.isInteger(location?.range?.end?.character) ? {endCharacter: location.range.end.character} : {}),
+          classification: usage,
+        });
+        if (!source || source === targetId) {
+          if (usage === "unknown") unclassifiedReferences++;
+          continue;
+        }
         if (usage === "unknown") {
           const evidenceKey = `${source}\0${targetId}\0${line}\0${exactCharacter}`;
           if (!evidenceSeen.has(evidenceKey)) {
@@ -798,6 +822,7 @@ export async function buildLspPrecisionOverlay({
       coverage: coverage(),
       links,
       referenceEvidence,
+      ...(collectLocations ? {locations: exactLocations} : {}),
       noReferenceSymbols,
       ...(errors ? {reason: `${errors} semantic request(s) failed or were refused`}
         : truncated ? {reason: "semantic precision stopped at a configured safety limit"}

package/src/precision/symbol-query.js

@@ -0,0 +1,137 @@
+import {existsSync, readFileSync, statSync} from 'node:fs'
+import {dirname, resolve} from 'node:path'
+import {atomicWriteFileSync, withFileLock} from '../graph/file-lock.js'
+import {
+    buildLspPrecisionOverlay,
+    precisionOverlayMatches,
+    precisionSemanticInputsMatch,
+} from './lsp-overlay.js'
+
+export const SYMBOL_PRECISION_CACHE_V = 1
+export const SYMBOL_PRECISION_CACHE_FILE = 'precision-symbols.json'
+
+const MAX_CACHE_ENTRIES = 32
+const MAX_CACHE_BYTES = 8 * 1024 * 1024
+const MAX_CACHE_READ_BYTES = 16 * 1024 * 1024
+const inFlight = new Map()
+
+const boundedInteger = (value, fallback, minimum, maximum) => {
+    const number = Number(value)
+    return Math.max(minimum, Math.min(maximum, Number.isFinite(number) ? Math.floor(number) : fallback))
+}
+
+export function symbolPrecisionCachePath(graphPath) {
+    return resolve(dirname(graphPath), SYMBOL_PRECISION_CACHE_FILE)
+}
+
+function loadRawGraph(graphPath) {
+    const graph = JSON.parse(readFileSync(graphPath, 'utf8'))
+    if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.links)) {
+        throw new Error('the active graph is not a valid Weavatrix graph')
+    }
+    return graph
+}
+
+function emptyCache() {
+    return {symbolPrecisionCacheV: SYMBOL_PRECISION_CACHE_V, entries: []}
+}
+
+function readCache(path) {
+    if (!existsSync(path)) return emptyCache()
+    try {
+        if (statSync(path).size > MAX_CACHE_READ_BYTES) return emptyCache()
+        const value = JSON.parse(readFileSync(path, 'utf8'))
+        if (Number(value?.symbolPrecisionCacheV) !== SYMBOL_PRECISION_CACHE_V || !Array.isArray(value.entries)) return emptyCache()
+        return {symbolPrecisionCacheV: SYMBOL_PRECISION_CACHE_V, entries: value.entries.slice(0, MAX_CACHE_ENTRIES)}
+    } catch {
+        return emptyCache()
+    }
+}
+
+function writeBoundedCache(path, entries) {
+    const kept = entries
+        .filter((entry) => entry && typeof entry === 'object')
+        .sort((left, right) => Number(right.usedAt) - Number(left.usedAt))
+        .slice(0, MAX_CACHE_ENTRIES)
+    let body
+    do {
+        body = JSON.stringify({symbolPrecisionCacheV: SYMBOL_PRECISION_CACHE_V, entries: kept})
+        if (Buffer.byteLength(body) <= MAX_CACHE_BYTES || !kept.length) break
+        kept.pop()
+    } while (true)
+    atomicWriteFileSync(path, body, 'utf8')
+}
+
+function cacheMatch(entry, {targetId, graph, repoRoot, request}) {
+    if (String(entry?.targetId || '') !== targetId || !entry.overlay) return false
+    if (!precisionOverlayMatches(entry.overlay, graph, {request})) return false
+    return precisionSemanticInputsMatch(entry.overlay, repoRoot, graph)
+}
+
+async function storeEntry(path, entry) {
+    await withFileLock(`${path}.lock`, async () => {
+        const current = readCache(path)
+        const entries = current.entries.filter((item) => String(item?.targetId || '') !== entry.targetId)
+        entries.unshift(entry)
+        writeBoundedCache(path, entries)
+    })
+}
+
+function cacheable(overlay) {
+    if (overlay?.state === 'COMPLETE') return true
+    return overlay?.state === 'PARTIAL'
+        && overlay?.reason === 'semantic precision stopped at a configured safety limit'
+}
+
+export async function querySymbolPrecision({
+    repoRoot,
+    graphPath,
+    targetId,
+    maxReferences = 1_000,
+    timeoutMs = 30_000,
+    clientFactory,
+} = {}) {
+    if (!repoRoot || !graphPath || !targetId) throw new Error('symbol precision requires repoRoot, graphPath, and targetId')
+    const boundedReferences = boundedInteger(maxReferences, 1_000, 1, 5_000)
+    const boundedTimeout = boundedInteger(timeoutMs, 30_000, 1_000, 60_000)
+    const request = {maxSymbols: 1, maxReferences: boundedReferences, maxLinks: boundedReferences}
+    const rawGraph = loadRawGraph(graphPath)
+    const graph = rawGraph.graphPrecisionMode === 'off' ? {...rawGraph, graphPrecisionMode: 'lsp'} : rawGraph
+    const target = graph.nodes.find((node) => String(node?.id || '') === String(targetId))
+    if (!target) throw new Error('the selected symbol is not present in the active raw graph')
+    if (!target.selection_start || !/\.(?:[cm]?[jt]sx?)$/i.test(String(target.source_file || ''))) {
+        throw new Error('exact symbol precision currently supports JavaScript and TypeScript symbols with source selections')
+    }
+
+    const id = String(targetId)
+    const cachePath = symbolPrecisionCachePath(graphPath)
+    const startedAt = Date.now()
+    const cached = readCache(cachePath).entries.find((entry) => cacheMatch(entry, {targetId: id, graph, repoRoot, request}))
+    if (cached) return {overlay: cached.overlay, cached: true, elapsedMs: Date.now() - startedAt, cachePath}
+
+    const flightKey = `${graphPath}\0${graph.graphRevision || ''}\0${id}\0${boundedReferences}`
+    if (inFlight.has(flightKey)) return inFlight.get(flightKey)
+    const operation = (async () => {
+        const overlay = await buildLspPrecisionOverlay({
+            repoRoot,
+            graph,
+            mode: 'lsp',
+            maxSymbols: 1,
+            maxReferences: boundedReferences,
+            maxLinks: boundedReferences,
+            timeoutMs: boundedTimeout,
+            targetIds: [id],
+            clientFactory,
+        })
+        if (cacheable(overlay)) {
+            await storeEntry(cachePath, {targetId: id, usedAt: Date.now(), overlay})
+        }
+        return {overlay, cached: false, elapsedMs: Date.now() - startedAt, cachePath}
+    })()
+    inFlight.set(flightKey, operation)
+    try {
+        return await operation
+    } finally {
+        inFlight.delete(flightKey)
+    }
+}