weavatrix 0.3.13 → 1.0.0

package/src/mcp/graph/tools-core.mjs

@@ -1,143 +0,0 @@
-import {
-    isSymbol, degreeOf, labelOf, connList, resolveNodeInfo, ambiguityNote,
-    graphStaleness, fileStalenessNote,
-} from '../graph-context.mjs'
-import {summarizeEdgeProvenance} from '../../graph/edge-provenance.js'
-
-const compileKind = (edge) => edge?.typeOnly === true ? 'type-only' : edge?.compileOnly === true ? 'compile-only' : null
-
-export function tGraphStats(g, ctx) {
-    const files = g.nodes.filter((node) => !isSymbol(node.id)).length
-    const symbols = g.nodes.length - files
-    const relCount = {}
-    const confCount = {}
-    let typeOnlyEdges = 0
-    let compileOnlyEdges = 0
-    for (const edge of g.links) {
-        relCount[edge.relation ?? '?'] = (relCount[edge.relation ?? '?'] || 0) + 1
-        if (edge.confidence != null) confCount[edge.confidence] = (confCount[edge.confidence] || 0) + 1
-        if (edge.typeOnly === true) typeOnlyEdges++
-        if (edge.compileOnly === true) compileOnlyEdges++
-    }
-    const communities = new Map()
-    for (const node of g.nodes) {
-        const community = node.community ?? 'none'
-        communities.set(community, (communities.get(community) || 0) + 1)
-    }
-    const topCommunities = [...communities.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8)
-    const formatCounts = (counts) => Object.entries(counts)
-        .sort((a, b) => b[1] - a[1])
-        .map(([key, value]) => `${key}: ${value}`)
-        .join(', ')
-    const freshness = ctx ? graphStaleness(ctx) : null
-    const provenance = summarizeEdgeProvenance(g.links)
-    const precision = g.precision || {state: 'UNAVAILABLE', verifiedEdges: 0, candidates: 0, queried: 0, reason: 'no revision-matched precision overlay'}
-    return [
-        'Graph summary',
-        ctx?.runtime ? `- Weavatrix runtime: v${ctx.runtime.version}; disk v${ctx.runtime.diskVersion || 'unavailable'}; stale ${ctx.runtime.staleRuntime ? 'YES' : 'no'}; profile ${ctx.runtime.profile}; ${ctx.runtime.toolCount} registered tools; capabilities: ${ctx.runtime.capabilities.join(',') || '(none)'}` : null,
-        ctx?.repoRoot ? `- Repo: ${ctx.repoRoot}` : null,
-        ctx?.graphPath ? `- Graph: ${ctx.graphPath}` : null,
-        `- Build mode: ${g.graphBuildMode || 'full'}`,
-        `- Nodes: ${g.nodes.length} (${files} files, ${symbols} symbols)`,
-        `- Edges: ${g.links.length}`,
-        g.edgeTypesV ? `- Typed-edge metadata: v${g.edgeTypesV} (${typeOnlyEdges} type-only, ${compileOnlyEdges} compile-only edges)` : '- Typed-edge metadata: unavailable (rebuild_graph required)',
-        g.edgeProvenanceV ? `- Edge provenance: v${g.edgeProvenanceV} (${formatCounts(provenance.counts)}; ${provenance.complete ? 'complete' : `${provenance.counts.UNKNOWN} unclassified`})` : '- Edge provenance: unavailable (rebuild_graph required)',
-        `- Semantic precision: ${precision.state}${precision.provider ? ` via ${precision.provider}${precision.providerVersion ? ` ${precision.providerVersion}` : ''}${precision.typescriptVersion ? ` (TypeScript ${precision.typescriptVersion})` : ''}` : ''}; ${precision.verifiedEdges || 0} EXACT_LSP edge(s), ${precision.queried || 0}/${precision.candidates || 0} bounded target(s) queried${precision.truncated ? ' (partial/truncated)' : ''}${precision.reason ? `; ${precision.reason}` : ''}`,
-        g.barrelResolutionV ? `- Barrel resolution: v${g.barrelResolutionV} (semantic tools look through JS/TS re-export facades)` : '- Barrel resolution: unavailable (rebuild_graph required for JS/TS barrel transparency)',
-        g.reExportOccurrencesV ? `- Re-export occurrences: v${g.reExportOccurrencesV} (${g.reExportOccurrences.length} exact site(s))` : '- Re-export occurrences: unavailable (rebuild_graph required)',
-        g.symbolSpacesV ? `- TypeScript symbol spaces: v${g.symbolSpacesV} (type/value identities separated)` : '- TypeScript symbol spaces: unavailable (rebuild_graph required)',
-        `- Relations: ${formatCounts(relCount)}`,
-        Object.keys(confCount).length ? `- Legacy confidence: ${formatCounts(confCount)}` : null,
-        `- Communities: ${communities.size} (top by size: ${topCommunities.map(([community, count]) => `#${community}=${count}`).join(', ')})`,
-        freshness?.builtAt ? `- Built: ${freshness.builtAt.toISOString()}${freshness.headAt ? ` (repo HEAD committed ${freshness.headAt.toISOString()})` : ''}` : null,
-    ].filter(Boolean).join('\n')
-}
-
-export function tGetNode(g, {label} = {}, ctx) {
-    const info = resolveNodeInfo(g, label)
-    const node = info.node
-    if (!node) return `No node found matching "${label}".`
-    const note = ambiguityNote(label, info)
-    const id = String(node.id)
-    const drift = ctx ? fileStalenessNote(ctx, node.source_file || (isSymbol(id) ? id.split('#')[0] : id)) : null
-    const outgoing = g.out.get(id) || []
-    const incoming = g.inn.get(id) || []
-    const semanticOutgoing = connList(outgoing)
-    const semanticIncoming = connList(incoming)
-    const sample = (edges, direction) => edges.slice(0, 12)
-        .map((edge) => `  ${direction === 'out' ? '→' : '←'} ${compileKind(edge) ? `${compileKind(edge)} ` : ''}${edge.relation || 'rel'} [${edge.provenance || 'UNKNOWN'}]  ${labelOf(g, edge.id)}  [${edge.id}]`)
-        .join('\n') || '  (none)'
-    return [
-        note,
-        `Node: ${node.label ?? id}`,
-        `- id: ${id}`,
-        `- kind: ${isSymbol(id) ? 'symbol' : 'file'}${node.file_type ? ` (${node.file_type})` : ''}`,
-        node.source_file ? `- source: ${node.source_file}${node.source_location ? ` ${node.source_location}` : ''}` : null,
-        node.community != null ? `- community: ${node.community}` : null,
-        `- semantic degree: ${semanticOutgoing.length + semanticIncoming.length} (out ${semanticOutgoing.length}, in ${semanticIncoming.length})${outgoing.length + incoming.length !== semanticOutgoing.length + semanticIncoming.length ? `; ${outgoing.length + incoming.length} physical/structural edges retained` : ''}`,
-        `Outgoing:\n${sample(outgoing, 'out')}`,
-        `Incoming:\n${sample(incoming, 'in')}`,
-        drift,
-    ].filter(Boolean).join('\n')
-}
-
-function dedupeEdges(edges) {
-    const grouped = new Map()
-    for (const edge of edges) {
-        const key = `${edge.relation || 'rel'}|${compileKind(edge) || 'runtime'}|${edge.id}`
-        const current = grouped.get(key)
-        if (current) {
-            current.count += 1
-            current.provenance.add(edge.provenance || 'UNKNOWN')
-        } else grouped.set(key, {
-            id: edge.id, relation: edge.relation, typeOnly: edge.typeOnly === true,
-            compileOnly: edge.compileOnly === true, provenance: new Set([edge.provenance || 'UNKNOWN']), count: 1,
-        })
-    }
-    return [...grouped.values()]
-}
-
-export function tGetNeighbors(g, {label, relation_filter} = {}, ctx) {
-    const info = resolveNodeInfo(g, label)
-    const node = info.node
-    if (!node) return `No node found matching "${label}".`
-    const note = ambiguityNote(label, info)
-    const id = String(node.id)
-    const drift = ctx ? fileStalenessNote(ctx, node.source_file || (isSymbol(id) ? id.split('#')[0] : id)) : null
-    const filter = relation_filter ? String(relation_filter).toLowerCase() : null
-    const matches = (edge) => !filter || String(edge.relation ?? '').toLowerCase() === filter
-    const outgoingRaw = (g.out.get(id) || []).filter(matches)
-    const incomingRaw = (g.inn.get(id) || []).filter(matches)
-    const outgoing = dedupeEdges(outgoingRaw)
-    const incoming = dedupeEdges(incomingRaw)
-    const line = (edge, direction) => `  ${direction === 'out' ? '→' : '←'} ${compileKind(edge) ? `${compileKind(edge)} ` : ''}${edge.relation || 'rel'} [${[...edge.provenance].sort().join('+')}]  ${labelOf(g, edge.id)}  [${edge.id}]${edge.count > 1 ? `  (${edge.count} sites)` : ''}`
-    return [
-        note,
-        `Neighbors of ${node.label ?? id}${filter ? ` (relation=${filter})` : ''}: ${outgoing.length + incoming.length} unique (${outgoingRaw.length + incomingRaw.length} edges)`,
-        `Outgoing (${outgoing.length}):`,
-        ...outgoing.slice(0, 60).map((edge) => line(edge, 'out')),
-        `Incoming (${incoming.length}):`,
-        ...incoming.slice(0, 60).map((edge) => line(edge, 'in')),
-        drift,
-    ].filter(Boolean).join('\n')
-}
-
-export function tGetCommunity(g, {community_id} = {}) {
-    const groups = new Map()
-    for (const node of g.nodes) {
-        if (node.community == null) continue
-        if (!groups.has(node.community)) groups.set(node.community, [])
-        groups.get(node.community).push(node)
-    }
-    const ranked = [...groups.entries()].sort((a, b) => b[1].length - a[1].length)
-    const index = Number(community_id)
-    if (!Number.isInteger(index) || index < 0 || index >= ranked.length) return `Invalid community_id ${community_id}. Valid range 0..${ranked.length - 1} (0 = largest).`
-    const [rawId, members] = ranked[index]
-    const files = members.filter((member) => !isSymbol(member.id))
-    return [
-        `Community #${index} (raw id ${rawId}) — ${members.length} nodes, ${files.length} files:`,
-        ...members.slice().sort((a, b) => degreeOf(g, b.id) - degreeOf(g, a.id)).slice(0, 80)
-            .map((member) => `  ${member.label ?? member.id}  [${member.id}]`),
-        members.length > 80 ? `  … +${members.length - 80} more` : null,
-    ].filter(Boolean).join('\n')
-}

package/src/mcp/graph/tools-query.mjs

@@ -1,276 +0,0 @@
-import {
-    isSymbol, degreeOf, labelOf, resolveNode, findSeeds, resolveSeedFiles,
-    requestedPathClasses,
-} from '../graph-context.mjs'
-import {createPathClassifier, hasPathClass} from '../../path-classification.js'
-
-const QUERY_NON_PRODUCT = Object.freeze(['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
-const LOW_SIGNAL_SYMBOL_RE = /^(?:const(?:ant)?|variable|property|field|enum_member)$/i
-const AMBIGUOUS_FILE_BASENAME_RE = /^(mod|lib|main)\.rs$|^index\.[a-z0-9]+$|^__init__\.py$/
-const querySourceFile = (node) => String(node?.source_file || String(node?.id || '').split('#', 1)[0]).replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase()
-const queryWords = (value) => new Set(String(value || '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean))
-const exactSymbolName = (node) => {
-    const match = String(node?.id || '').match(/#([^@]+)@/)
-    return match ? match[1] : String(node?.label || '').replace(/\(\)$/, '')
-}
-
-function resolveExactSeedSymbols(g, requested, limit = 12) {
-    const values = Array.isArray(requested) ? requested.slice(0, limit) : []
-    const seeds = []
-    const missing = []
-    const ambiguous = []
-    for (const raw of values) {
-        const wanted = String(raw || '').trim()
-        if (!wanted) continue
-        let matches = []
-        const byId = g.byId.get(wanted)
-        if (byId && isSymbol(byId.id)) matches = [byId]
-        else matches = g.nodes.filter((node) => isSymbol(node.id)
-            && (String(node.label || '') === wanted || exactSymbolName(node) === wanted))
-        if (matches.length === 1) {
-            if (!seeds.some((seed) => String(seed.id) === String(matches[0].id))) seeds.push(matches[0])
-        } else if (matches.length > 1) ambiguous.push(`${wanted} (${matches.length} exact matches; pass a symbol id)`)
-        else missing.push(wanted)
-    }
-    return {seeds, missing, ambiguous}
-}
-
-// Edge/hop lines print bare labels without the [id] suffix node lines carry, so repeated or
-// conventionally-generic file basenames (mod.rs, index.ts, __init__.py) become indistinguishable —
-// widen those, scoped to the shown ids, to the last two path segments.
-const makeEdgeLabel = (g, shownIds) => {
-    const counts = new Map()
-    for (const id of shownIds) {
-        const label = labelOf(g, id)
-        counts.set(label, (counts.get(label) || 0) + 1)
-    }
-    return (id) => {
-        const label = labelOf(g, id)
-        const isFile = String(id).includes('/') && !String(id).includes('#')
-        if (isFile && ((counts.get(label) || 0) > 1 || AMBIGUOUS_FILE_BASENAME_RE.test(label))) return String(id).split('/').slice(-2).join('/')
-        return label
-    }
-}
-
-// shortest_path is intentionally a connectivity query, so it may walk an edge in either
-// direction. Keep the stored direction on every hop so the rendered path never turns a reverse
-// traversal into a false caller/importer direction.
-const connectivityNeighbors = (g, id) => {
-    const seen = new Map()
-    for (const edge of g.out.get(id) || []) {
-        if (edge.barrelProxy !== true) seen.set(String(edge.id), {relation: edge.relation, direction: 'forward'})
-    }
-    for (const edge of g.inn.get(id) || []) {
-        if (edge.barrelProxy !== true && !seen.has(String(edge.id))) {
-            seen.set(String(edge.id), {relation: edge.relation, direction: 'backward'})
-        }
-    }
-    return seen
-}
-
-const relationSet = (relationFilter, legacyFilter) => {
-    const raw = relationFilter ?? legacyFilter
-    const values = Array.isArray(raw) ? raw : (raw == null ? [] : String(raw).split(','))
-    const normalized = values.map((value) => String(value).trim().toLowerCase()).filter(Boolean)
-    return normalized.length ? new Set(normalized) : null
-}
-
-export function tQueryGraph(g, {
-    question, mode = 'bfs', depth = 3, context_filter, relation_filter, seed_files, seed_symbols, augment_seeds = false,
-    flow_direction = 'both', include_classified = false, include_low_signal = false, token_budget = 2000,
-} = {}, toolCtx = {}) {
-    const pinned = resolveSeedFiles(g, seed_files)
-    const exactSymbols = resolveExactSeedSymbols(g, seed_symbols)
-    const pinnedSeeds = [...pinned.seeds, ...exactSymbols.seeds.filter((node) => !pinned.seeds.some((seed) => String(seed.id) === String(node.id)))]
-    const automatic = pinnedSeeds.length && augment_seeds !== true
-        ? []
-        : findSeeds(g, question, Math.max(0, 6 - pinnedSeeds.length), {repoRoot: toolCtx.repoRoot || null})
-    const seeds = [...pinnedSeeds, ...automatic.filter((node) => !pinnedSeeds.some((seed) => String(seed.id) === String(node.id)))]
-    if (!seeds.length) {
-        const details = [
-            pinned.missing.length ? `Unresolved seed files: ${pinned.missing.join(', ')}` : null,
-            exactSymbols.missing.length ? `Unresolved exact symbols: ${exactSymbols.missing.join(', ')}` : null,
-            exactSymbols.ambiguous.length ? `Ambiguous exact symbols: ${exactSymbols.ambiguous.join(', ')}` : null,
-        ].filter(Boolean)
-        return [`No nodes matched "${question || ''}".`, ...details].join('\n')
-    }
-
-    const maxDepth = Math.max(1, Math.min(6, Number(depth) || 3))
-    const relations = relationSet(relation_filter, context_filter)
-    const relationAllowed = (relation) => !relations || relations.has(String(relation ?? '').toLowerCase())
-    const direction = ['forward', 'backward', 'both'].includes(String(flow_direction).toLowerCase())
-        ? String(flow_direction).toLowerCase() : 'both'
-    const neighbors = (id) => {
-        const found = new Map()
-        const add = (edges) => {
-            for (const edge of edges || []) {
-                const neighbor = String(edge.id)
-                if (edge.barrelProxy === true || !relationAllowed(edge.relation) || found.has(neighbor)) continue
-                found.set(neighbor, edge.relation)
-            }
-        }
-        if (direction !== 'backward') add(g.out.get(id))
-        if (direction !== 'forward') add(g.inn.get(id))
-        return found
-    }
-
-    const requestedClasses = requestedPathClasses(question)
-    const classifier = createPathClassifier(toolCtx.repoRoot || null)
-    const classificationCache = new Map()
-    const pinnedFiles = new Set(pinnedSeeds.map(querySourceFile))
-    const classifiedSuppressed = new Set()
-    const pathPolicy = (id) => {
-        const node = g.byId.get(String(id))
-        const file = querySourceFile(node)
-        if (!file || pinnedFiles.has(file) || include_classified === true) return {ok: true}
-        // Extractor-proven test symbols (Rust #[cfg(test)]) live in production files; suppress them
-        // under the same policy as path-classified tests unless the question asks about tests.
-        if (node?.test_surface === true && !requestedClasses.has('test')) {
-            classifiedSuppressed.add(String(id))
-            return {ok: false, bucket: 'classified'}
-        }
-        if (!classificationCache.has(file)) classificationCache.set(file, classifier.explain(file, {content: ''}))
-        const info = classificationCache.get(file)
-        const classes = QUERY_NON_PRODUCT.filter((name) => hasPathClass(info, name))
-        if (!classes.length && !info?.excluded) return {ok: true}
-        if (classes.some((name) => requestedClasses.has(name))) return {ok: true}
-        classifiedSuppressed.add(String(id))
-        return {ok: false, bucket: 'classified'}
-    }
-
-    const questionTerms = queryWords(question)
-    const start = seeds.map((seed) => String(seed.id))
-    const isLowSignal = (id) => {
-        if (include_low_signal === true || start.includes(String(id))) return false
-        const node = g.byId.get(String(id))
-        if (!node || !isSymbol(node.id) || !LOW_SIGNAL_SYMBOL_RE.test(String(node.symbol_kind || ''))) return false
-        const labelTerms = queryWords(node.label || String(node.id || '').split('#').pop() || '')
-        if ([...questionTerms].some((term) => labelTerms.has(term))) return false
-        return degreeOf(g, id) === 0
-    }
-    const charBudget = Math.max(400, (Number(token_budget) || 2000) * 4)
-    const nodeBudget = Math.max(20, Math.min(120, Math.round((Number(token_budget) || 2000) / 40)))
-    const depthOf = new Map()
-
-    if (mode === 'dfs') {
-        const stack = start.map((id) => ({id, depth: 0}))
-        const seen = new Set()
-        while (stack.length) {
-            const {id, depth: currentDepth} = stack.pop()
-            if (!depthOf.has(id) || currentDepth < depthOf.get(id)) depthOf.set(id, currentDepth)
-            if (seen.has(id)) continue
-            seen.add(id)
-            if (currentDepth >= maxDepth) continue
-            for (const [neighbor, relation] of neighbors(id)) {
-                if (!relationAllowed(relation) || !pathPolicy(neighbor).ok) continue
-                if (!seen.has(neighbor)) stack.push({id: neighbor, depth: currentDepth + 1})
-            }
-        }
-    } else {
-        let frontier = start.slice()
-        start.forEach((id) => depthOf.set(id, 0))
-        for (let currentDepth = 0; currentDepth < maxDepth && frontier.length; currentDepth++) {
-            const next = []
-            for (const id of frontier) {
-                for (const [neighbor, relation] of neighbors(id)) {
-                    if (!relationAllowed(relation) || !pathPolicy(neighbor).ok) continue
-                    if (!depthOf.has(neighbor)) {
-                        depthOf.set(neighbor, currentDepth + 1)
-                        next.push(neighbor)
-                    }
-                }
-            }
-            frontier = next
-        }
-    }
-
-    const reachedBeforeSignalFilter = depthOf.size
-    const lowSignalSuppressed = [...depthOf.keys()].filter(isLowSignal).length
-    const ranked = [...depthOf.entries()]
-        .filter(([id]) => !isLowSignal(id))
-        .map(([id, distance]) => ({id, distance, degree: degreeOf(g, id)}))
-        .sort((a, b) => a.distance - b.distance || b.degree - a.degree)
-    const shown = ranked.slice(0, nodeBudget)
-    const shownIds = new Set(shown.map((node) => node.id))
-    const edgeSeen = new Set()
-    const shownEdges = []
-    for (const source of shownIds) {
-        for (const edge of g.out.get(source) || []) {
-            const target = String(edge.id)
-            if (edge.barrelProxy === true || !shownIds.has(target) || !relationAllowed(edge.relation)) continue
-            const key = `${source}|${edge.relation}|${target}`
-            if (edgeSeen.has(key)) continue
-            edgeSeen.add(key)
-            shownEdges.push([source, edge.relation, target])
-            if (shownEdges.length >= 160) break
-        }
-        if (shownEdges.length >= 160) break
-    }
-    const head = [
-        `Query: "${question || ''}" (${mode}, depth ${maxDepth}, flow ${direction}${relations ? `, relations ${[...relations].join('/')}` : ''})`,
-        `Seeds: ${seeds.map((seed) => seed.label ?? seed.id).join(', ')}`,
-        pinned.missing.length ? `Unresolved pinned seed files: ${pinned.missing.join(', ')}` : null,
-        exactSymbols.missing.length ? `Unresolved exact seed symbols: ${exactSymbols.missing.join(', ')}` : null,
-        exactSymbols.ambiguous.length ? `Ambiguous exact seed symbols: ${exactSymbols.ambiguous.join(', ')}` : null,
-        `Reached ${reachedBeforeSignalFilter} policy-eligible nodes; showing ${shown.length} closest by proximity + connectivity, ${shownEdges.length} edges among them.`,
-        classifiedSuppressed.size ? `Suppressed ${classifiedSuppressed.size} classified/non-product traversal node(s); ask for that class or pass include_classified:true.` : null,
-        lowSignalSuppressed ? `Suppressed ${lowSignalSuppressed} unreferenced constant/field node(s) with no query-term match; pass include_low_signal:true to inspect them.` : null,
-        include_classified === true ? 'Path policy: classified/non-product traversal explicitly enabled.' : `Path policy: production-first${requestedClasses.size ? `; explicit question classes enabled: ${[...requestedClasses].join(', ')}` : ''}.`,
-        '',
-        'Nodes:',
-    ]
-    const nodeLines = shown.map((node) => `  [d${node.distance}] ${labelOf(g, node.id)}  (deg ${node.degree})  [${node.id}]`)
-    const edgeLabel = makeEdgeLabel(g, shownIds)
-    const edgeLines = ['', 'Edges:', ...shownEdges.map(([source, relation, target]) => `  ${edgeLabel(source)} --${relation || 'rel'}--> ${edgeLabel(target)}`)]
-    let text = [...head.filter(Boolean), ...nodeLines, ...edgeLines].join('\n')
-    if (text.length > charBudget) text = text.slice(0, charBudget) + `\n... (truncated to ~${token_budget} tokens)`
-    return text
-}
-
-export function tShortestPath(g, {source, target, max_hops = 8} = {}) {
-    const sourceNode = resolveNode(g, source)
-    const targetNode = resolveNode(g, target)
-    if (!sourceNode) return `Source "${source}" not found.`
-    if (!targetNode) return `Target "${target}" not found.`
-    const sourceId = String(sourceNode.id)
-    const targetId = String(targetNode.id)
-    if (sourceId === targetId) return `Source and target are the same node: ${sourceNode.label ?? sourceId}.`
-    const limit = Math.max(1, Math.min(20, Number(max_hops) || 8))
-    const previous = new Map([[sourceId, null]])
-    const edgeTo = new Map()
-    let frontier = [sourceId]
-    let hops = 0
-    let found = false
-    while (frontier.length && hops < limit && !found) {
-        const next = []
-        for (const id of frontier) {
-            for (const [neighbor, edge] of connectivityNeighbors(g, id)) {
-                if (previous.has(neighbor)) continue
-                previous.set(neighbor, id)
-                edgeTo.set(neighbor, edge)
-                if (neighbor === targetId) { found = true; break }
-                next.push(neighbor)
-            }
-            if (found) break
-        }
-        frontier = next
-        hops++
-    }
-    if (!previous.has(targetId)) return `No path found between "${sourceNode.label ?? sourceId}" and "${targetNode.label ?? targetId}" within ${limit} hops.`
-    const path = []
-    for (let current = targetId; current != null; current = previous.get(current)) path.unshift(current)
-    const edgeLabel = makeEdgeLabel(g, path)
-    const hopCount = path.length - 1
-    const lines = path.map((id, index) => {
-        if (index === 0) return `  ${edgeLabel(id)}`
-        const edge = edgeTo.get(id) || {}
-        return edge.direction === 'backward'
-            ? `  <--${edge.relation || 'rel'}-- ${edgeLabel(id)}`
-            : `  --${edge.relation || 'rel'}--> ${edgeLabel(id)}`
-    })
-    return [
-        `Shortest path (${hopCount} ${hopCount === 1 ? 'hop' : 'hops'}; undirected connectivity) from ${edgeLabel(sourceId)} to ${edgeLabel(targetId)}`,
-        'Edge arrows preserve stored graph direction; traversal may move with or against them.',
-        ...lines,
-    ].join('\n')
-}

package/src/mcp/graph-context.mjs

@@ -1,5 +0,0 @@
-// Stable public facade for graph loading, query seeding and graph state helpers.
-export * from './graph/context-core.mjs'
-export * from './graph/context-seeds.mjs'
-export * from './graph/context-state.mjs'
-export {prevGraphPathFor, edgeEndpoint, fileOfId, diffGraphs, formatGraphDiff} from './graph-diff.mjs'

package/src/mcp/graph-diff.mjs

@@ -1,218 +0,0 @@
-// Structural graph delta helpers split from graph-context so the process-lifetime graph indexes stay small.
-import {buildFileImportGraph, findSccs} from '../analysis/dep-rules.js'
-import {folderModuleOf} from '../analysis/graph-analysis.aggregate.js'
-import {isStructuralRelation} from '../graph/relations.js'
-import {fileOfId} from '../graph/node-id.js'
-
-// ---- graph diff ----------------------------------------------------------------------------------
-// One previous state is enough (4-13 MB per repo — cheap): rebuild_graph snapshots the outgoing
-// graph.json as graph.prev.json and reports the structural delta inline, at the exact moment the fix
-// is being verified. graph_diff re-queries the same pair later. Raw node/edge dumps would be noise —
-// the signal is aggregated: module-dependency drift, cycle count changes, newly orphaned symbols.
-export const prevGraphPathFor = (graphPath) => String(graphPath).replace(/\.json$/, '.prev.json')
-export const edgeEndpoint = (v) => String(v && typeof v === 'object' ? v.id : v)
-export {fileOfId}
-const folderOfFile = folderModuleOf
-
-const terminalLineSuffix = (id) => {
-    const raw = String(id)
-    return raw.includes('#') ? raw.replace(/@\d+$/, '') : raw
-}
-
-const sourceLine = (node) => {
-    const explicit = String(node?.source_location || '').match(/^L(\d+)/i)
-    if (explicit) return Number(explicit[1])
-    const suffix = String(node?.id || '').match(/@(\d+)$/)
-    return suffix ? Number(suffix[1]) : Number.MAX_SAFE_INTEGER
-}
-
-// Node ids retain source lines for precise read_source jumps, but location is not identity. This
-// comparison-only index keeps file/name/kind/export/signature shape stable across line shifts and
-// uses an ordinal only for true same-name overloads. Raw ids remain the user-facing evidence.
-function stableNodeIndex(graph) {
-    const groups = new Map()
-    for (const node of graph.nodes || []) {
-        const raw = String(node?.id ?? '')
-        if (!raw) continue
-        const stem = terminalLineSuffix(raw)
-        const params = Number.isInteger(node?.complexity?.params) ? node.complexity.params : ''
-        const signature = [stem, node?.symbol_kind || '', node?.symbol_space || '', node?.exported === true ? 'exported' : '', params].join('\u0000')
-        if (!groups.has(signature)) groups.set(signature, [])
-        groups.get(signature).push(node)
-    }
-    const byRaw = new Map()
-    const rawByStable = new Map()
-    for (const [signature, nodes] of groups) {
-        nodes.sort((a, b) => sourceLine(a) - sourceLine(b) || String(a.id).localeCompare(String(b.id)))
-        nodes.forEach((node, ordinal) => {
-            const stable = `${signature}\u0000${ordinal}`
-            const raw = String(node.id)
-            byRaw.set(raw, stable)
-            rawByStable.set(stable, raw)
-        })
-    }
-    return {byRaw, rawByStable, keys: new Set(rawByStable.keys())}
-}
-
-// Works on anything with {nodes, links}: the raw graph.json shape and the loadGraph struct alike.
-export function diffGraphs(oldG, newG) {
-    const oldEdgeTypesV = Number(oldG.edgeTypesV) || 0
-    const newEdgeTypesV = Number(newG.edgeTypesV) || 0
-    const oldBarrelResolutionV = Number(oldG.barrelResolutionV) || 0
-    const newBarrelResolutionV = Number(newG.barrelResolutionV) || 0
-    const oldExtractorSchemaV = Number(oldG.extractorSchemaV) || 0
-    const newExtractorSchemaV = Number(newG.extractorSchemaV) || 0
-    const schemaChanges = [
-        oldEdgeTypesV !== newEdgeTypesV ? `edges v${oldEdgeTypesV}→v${newEdgeTypesV}` : null,
-        oldBarrelResolutionV !== newBarrelResolutionV ? `barrels v${oldBarrelResolutionV}→v${newBarrelResolutionV}` : null,
-        oldExtractorSchemaV !== newExtractorSchemaV ? `extractor v${oldExtractorSchemaV}→v${newExtractorSchemaV}` : null,
-    ].filter(Boolean)
-    const schemaMigration = schemaChanges.length > 0
-    const oldNodeIndex = stableNodeIndex(oldG)
-    const newNodeIndex = stableNodeIndex(newG)
-
-    const edgeClass = (l) => l.typeOnly === true ? 'type' : l.compileOnly === true ? 'compile' : 'runtime'
-    const stableEndpoint = (index, value) => {
-        const raw = edgeEndpoint(value)
-        return index.byRaw.get(raw) || raw
-    }
-    const edgeKey = (l, index) => `${stableEndpoint(index, l.source)}|${l.relation || ''}|${schemaMigration ? 'untyped' : edgeClass(l)}|${stableEndpoint(index, l.target)}`
-    const edgeSet = (graph, index) => new Set((graph.links || []).map((l) => edgeKey(l, index)))
-    const oldEdges = edgeSet(oldG, oldNodeIndex)
-    const newEdges = edgeSet(newG, newNodeIndex)
-
-    const moduleEdges = (graph, classification) => {
-        const set = new Set()
-        for (const l of graph.links || []) {
-            if (isStructuralRelation(l.relation) || l.barrelProxy === true) continue
-            if (edgeClass(l) !== classification) continue
-            const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
-            const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
-            if (a !== b) set.add(`${a} → ${b}`)
-        }
-        return set
-    }
-    // A parser/schema upgrade can discover edges that the old graph could not represent (Rust use/mod in
-    // edgeTypesV2). Do not call that architecture drift: establish a fresh classification baseline.
-    const oldMods = schemaMigration ? new Set() : moduleEdges(oldG, 'runtime')
-    const newMods = schemaMigration ? new Set() : moduleEdges(newG, 'runtime')
-    const oldTypeMods = schemaMigration ? new Set() : moduleEdges(oldG, 'type')
-    const newTypeMods = schemaMigration ? new Set() : moduleEdges(newG, 'type')
-    const oldCompileMods = schemaMigration ? new Set() : moduleEdges(oldG, 'compile')
-    const newCompileMods = schemaMigration ? new Set() : moduleEdges(newG, 'compile')
-
-    const incoming = (graph, index) => {
-        const m = new Map()
-        for (const l of graph.links || []) {
-            if (isStructuralRelation(l.relation) || l.barrelProxy === true) continue
-            const t = stableEndpoint(index, l.target)
-            m.set(t, (m.get(t) || 0) + 1)
-        }
-        return m
-    }
-    const oldIn = incoming(oldG, oldNodeIndex)
-    const newIn = incoming(newG, newNodeIndex)
-
-    const cycles = (graph, includeTypeOnly) => {
-        try {
-            const sccs = findSccs(buildFileImportGraph(graph, {includeTypeOnly}).adj)
-                .map((members) => members.map(String).sort())
-                .sort((a, b) => b.length - a.length || a.join('\n').localeCompare(b.join('\n')))
-            return {
-                count: sccs.length,
-                largest: sccs[0]?.length || 0,
-                groups: sccs,
-            }
-        } catch {
-            return null
-        }
-    }
-    const cycleDelta = (before, after) => {
-        if (!before || !after) return null
-        const key = (group) => group.join('|')
-        const beforeKeys = new Set(before.groups.map(key))
-        const afterKeys = new Set(after.groups.map(key))
-        const overlap = (a, b) => {
-            const bSet = new Set(b)
-            return a.reduce((n, member) => n + (bSet.has(member) ? 1 : 0), 0)
-        }
-        const unmatchedBefore = before.groups.filter((group) => !afterKeys.has(key(group)))
-        const unmatchedAfter = after.groups.filter((group) => !beforeKeys.has(key(group)))
-        const changed = unmatchedAfter.filter((group) => unmatchedBefore.some((old) => overlap(group, old) >= 2))
-        const introduced = unmatchedAfter.filter((group) => !unmatchedBefore.some((old) => overlap(group, old) >= 2))
-        const resolved = unmatchedBefore.filter((group) => !unmatchedAfter.some((next) => overlap(group, next) >= 2))
-        return {
-            before: before.count,
-            after: after.count,
-            largestBefore: before.largest,
-            largestAfter: after.largest,
-            introduced: introduced.map(key),
-            resolved: resolved.map(key),
-            membershipChanged: changed.length,
-        }
-    }
-
-    return {
-        schemaMigration: schemaMigration ? {from: oldEdgeTypesV, to: newEdgeTypesV, changes: schemaChanges} : null,
-        nodes: {
-            added: [...newNodeIndex.keys].filter((key) => !oldNodeIndex.keys.has(key)).map((key) => newNodeIndex.rawByStable.get(key)),
-            removed: [...oldNodeIndex.keys].filter((key) => !newNodeIndex.keys.has(key)).map((key) => oldNodeIndex.rawByStable.get(key))
-        },
-        edges: {
-            added: [...newEdges].filter((k) => !oldEdges.has(k)).length,
-            removed: [...oldEdges].filter((k) => !newEdges.has(k)).length
-        },
-        moduleEdges: {
-            added: [...newMods].filter((k) => !oldMods.has(k)),
-            removed: [...oldMods].filter((k) => !newMods.has(k)),
-            typeAdded: [...newTypeMods].filter((k) => !oldTypeMods.has(k)),
-            typeRemoved: [...oldTypeMods].filter((k) => !newTypeMods.has(k)),
-            compileAdded: [...newCompileMods].filter((k) => !oldCompileMods.has(k)),
-            compileRemoved: [...oldCompileMods].filter((k) => !newCompileMods.has(k)),
-        },
-        // survived the rebuild but lost every caller/importer — likely made dead by the change
-        orphaned: [...oldIn.keys()]
-            .filter((key) => newNodeIndex.keys.has(key) && !newIn.has(key))
-            .map((key) => newNodeIndex.rawByStable.get(key) || oldNodeIndex.rawByStable.get(key)),
-        cycles: {
-            runtime: schemaMigration ? null : cycleDelta(cycles(oldG, false), cycles(newG, false)),
-            // Backward-compatible field name: since edgeTypesV 2 this includes typeOnly and compileOnly.
-            typeInclusive: schemaMigration ? null : cycleDelta(cycles(oldG, true), cycles(newG, true)),
-        }
-    }
-}
-
-export function formatGraphDiff(d) {
-    if (!d.nodes.added.length && !d.nodes.removed.length && !d.edges.added && !d.edges.removed) {
-        return d.schemaMigration
-            ? `Graph extractor/schema upgraded (${d.schemaMigration.changes.join(', ')}); compile-time baseline established. Runtime/compile-time cycle and module classifications are intentionally not compared on this rebuild.`
-            : 'No structural change between the two graph states.'
-    }
-    const cap = (list, n) => list.slice(0, n).map((x) => `  ${x}`).concat(list.length > n ? [`  … +${list.length - n} more`] : [])
-    const lines = [`Structural delta: nodes +${d.nodes.added.length}/−${d.nodes.removed.length}, edges +${d.edges.added}/−${d.edges.removed}.`]
-    if (d.schemaMigration) lines.push(`Graph extractor/schema upgraded (${d.schemaMigration.changes.join(', ')}); runtime/compile-time cycle and module classifications are intentionally not compared until the next rebuild.`)
-    const runtime = d.cycles?.runtime
-    if (runtime && (runtime.before !== runtime.after || runtime.largestBefore !== runtime.largestAfter || runtime.introduced.length || runtime.resolved.length || runtime.membershipChanged)) {
-        const changes = []
-        if (runtime.introduced.length) changes.push(`${runtime.introduced.length} genuinely new runtime SCC(s) — review`)
-        if (runtime.resolved.length) changes.push(`${runtime.resolved.length} runtime SCC(s) resolved`)
-        if (runtime.membershipChanged) changes.push(`${runtime.membershipChanged} SCC membership change(s)`)
-        const verdict = changes.length ? `; ${changes.join('; ')}` : ''
-        lines.push(`Runtime import cycles: count ${runtime.before} → ${runtime.after}, largest SCC ${runtime.largestBefore} → ${runtime.largestAfter}${verdict}.`)
-    }
-    const all = d.cycles?.typeInclusive
-    if (all && (all.before !== all.after || all.largestBefore !== all.largestAfter) &&
-        (!runtime || all.before !== runtime.before || all.after !== runtime.after || all.largestBefore !== runtime.largestBefore || all.largestAfter !== runtime.largestAfter)) {
-        lines.push(`Compile-time-inclusive dependency SCCs: count ${all.before} → ${all.after}, largest ${all.largestBefore} → ${all.largestAfter} (compile-time coupling, not necessarily a runtime cycle).`)
-    }
-    if (d.moduleEdges.added.length) lines.push('NEW module dependencies (architecture drift — review):', ...cap(d.moduleEdges.added, 12))
-    if (d.moduleEdges.removed.length) lines.push('Removed module dependencies (decoupling confirmed):', ...cap(d.moduleEdges.removed, 12))
-    if (d.moduleEdges.typeAdded.length) lines.push('New type-only module dependencies (compile-time coupling):', ...cap(d.moduleEdges.typeAdded, 12))
-    if (d.moduleEdges.typeRemoved.length) lines.push('Removed type-only module dependencies:', ...cap(d.moduleEdges.typeRemoved, 12))
-    if (d.moduleEdges.compileAdded.length) lines.push('New compile-only module dependencies (compile-time coupling):', ...cap(d.moduleEdges.compileAdded, 12))
-    if (d.moduleEdges.compileRemoved.length) lines.push('Removed compile-only module dependencies:', ...cap(d.moduleEdges.compileRemoved, 12))
-    if (d.orphaned.length) lines.push('Symbols that lost their last caller/importer (now dead?):', ...cap(d.orphaned, 10))
-    if (d.nodes.added.length) lines.push('Added nodes:', ...cap(d.nodes.added, 12))
-    if (d.nodes.removed.length) lines.push('Removed nodes:', ...cap(d.nodes.removed, 12))
-    return lines.join('\n')
-}