weavatrix 0.2.4 → 0.2.6

package/src/mcp/tools-source.mjs

@@ -0,0 +1,238 @@
+import {readFileSync, statSync} from 'node:fs'
+import {boundedInteger} from '../bounds.js'
+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 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,
+        ...(node.symbol_space ? {space: node.symbol_space} : {}),
+    }))
+}
+
+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'),
+        space: String(node.symbol_space || 'value'),
+        exported: node.exported === true,
+        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.6'}} = {}) {
         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

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { boundedInteger } from "../bounds.js";
 import { atomicWriteFileSync } from "../graph/file-lock.js";
 import { edgeProvenance } from "../graph/edge-provenance.js";
 import { isStructuralRelation } from "../graph/relations.js";
@@ -274,8 +275,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 || []) {
@@ -442,11 +451,6 @@ function publicSemanticSafetyReason(reason) {
     : "TypeScript project configuration could not be verified safely";
 }
 
-function boundedInteger(value, fallback, minimum, maximum) {
-  const number = Number(value);
-  return Math.max(minimum, Math.min(maximum, Number.isFinite(number) ? Math.floor(number) : fallback));
-}
-
 export async function buildLspPrecisionOverlay({
   repoRoot,
   graph,
@@ -456,6 +460,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 +506,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 +530,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 +715,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 +733,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 +818,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,133 @@
+import {existsSync, readFileSync, statSync} from 'node:fs'
+import {dirname, resolve} from 'node:path'
+import {boundedInteger} from '../bounds.js'
+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()
+
+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)
+    }
+}