weavatrix 0.2.13 → 0.2.14

package/src/mcp/graph/context-seeds.mjs

@@ -0,0 +1,208 @@
+import {createPathClassifier, hasPathClass} from '../../path-classification.js'
+import {degreeOf, isSymbol, uniqueConnCount} from './context-core.mjs'
+
+const QUERY_STOP = new Set('a an and are around architecture best code do does exact explain find focus focused for from how identify in inspect inspection is logic me of or path production project repository request requests rest show symbol symbols the through to trace what where which with'.split(' '))
+const QUERY_INTENTS = [
+    ['bootstrap', ['bootstrap', 'startup', 'entrypoint', 'entry', 'main', 'root', 'app', 'application', 'applications', 'index', 'server', 'cli']],
+    ['tool-execution', ['tool', 'tools', 'tooling', 'mcp', 'execution', 'execute', 'invocation', 'invoke', 'dispatch', 'dispatcher', 'handler', 'catalog', 'registry']],
+    ['auth', ['auth', 'authentication', 'authorization', 'login', 'session', 'authgate']],
+    ['routing', ['routing', 'router', 'routes', 'route', 'navigation']],
+    ['layout', ['layout', 'layouts', 'shell']],
+    ['api', ['api', 'apis', 'endpoint', 'endpoints', 'client']],
+    ['state', ['state', 'store', 'stores', 'reducer', 'context']],
+]
+const INTENT_BY_TERM = new Map(QUERY_INTENTS.filter(([id]) => id !== 'tool-execution')
+    .flatMap(([id, terms]) => terms.map((term) => [term, {id, terms}])))
+const TOOL_EXECUTION_TERMS = QUERY_INTENTS.find(([id]) => id === 'tool-execution')[1]
+const TOOL_EXECUTION_TRIGGERS = new Set(['tool', 'tools', 'tooling', 'mcp'])
+const wordsOf = (value) => String(value ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean)
+const normPath = (value) => String(value ?? '').replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase()
+const NON_PRODUCT_CLASSES = Object.freeze(['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
+const CLASS_QUERY_TERMS = Object.freeze({
+    test: ['test', 'tests', 'testing', 'unit'],
+    e2e: ['e2e', 'playwright', 'cypress'],
+    generated: ['generated', 'autogenerated', 'dist'],
+    mock: ['mock', 'mocks', 'fixture', 'fixtures', 'fake'],
+    story: ['story', 'stories', 'storybook'],
+    docs: ['doc', 'docs', 'documentation', 'readme', 'guide'],
+    benchmark: ['benchmark', 'benchmarks', 'bench'],
+    temp: ['temp', 'temporary', 'tmp'],
+})
+const CODE_FILE_RE = /\.(?:[cm]?[jt]sx?|py|go|java|rs|kt|kts|cs|rb|php)$/i
+const DATA_OR_PROSE_RE = /\.(?:json|ya?ml|toml|ini|md|mdx|rst|adoc|html?|css|scss|less|svg)$/i
+const LANGUAGE_EXTENSIONS = Object.freeze({
+    rust: ['rs'], python: ['py', 'pyi'], typescript: ['ts', 'tsx', 'mts', 'cts'],
+    javascript: ['js', 'jsx', 'mjs', 'cjs'], go: ['go'], java: ['java'], csharp: ['cs'],
+})
+
+function requestedLanguages(query) {
+    const raw = String(query || ''), words = new Set(wordsOf(query)), requested = new Set()
+    if (words.has('rust')) requested.add('rust')
+    if (words.has('python') || words.has('py')) requested.add('python')
+    if (words.has('typescript') || words.has('ts') || /typescript/i.test(raw)) requested.add('typescript')
+    if (words.has('javascript') || words.has('js') || words.has('nodejs') || /javascript|node\.?js/i.test(raw)) requested.add('javascript')
+    if (words.has('golang') || /(?:^|[^A-Za-z])Go(?:[^A-Za-z]|$)/.test(raw)) requested.add('go')
+    if (words.has('java')) requested.add('java')
+    if (words.has('csharp') || words.has('dotnet') || /csharp|(?:^|[^A-Za-z])C#(?:[^A-Za-z]|$)/i.test(raw)) requested.add('csharp')
+    return new Set([...requested].flatMap((language) => LANGUAGE_EXTENSIONS[language]))
+}
+
+const sourceFileOf = (node) => normPath(node?.source_file || String(node?.id ?? '').split('#', 1)[0])
+const matchesLanguage = (node, extensions) => {
+    if (!extensions.size) return true
+    const match = /\.([^.\/]+)$/.exec(sourceFileOf(node))
+    return !!match && extensions.has(match[1].toLowerCase())
+}
+
+export function requestedPathClasses(query) {
+    const words = new Set(wordsOf(query)), requested = new Set()
+    for (const [category, terms] of Object.entries(CLASS_QUERY_TERMS)) if (terms.some((term) => words.has(term))) requested.add(category)
+    if (requested.has('test')) requested.add('e2e')
+    if (requested.has('e2e')) requested.add('test')
+    return requested
+}
+
+function isQueryEligible(node, requestedClasses, classificationCache, classifier) {
+    const source = sourceFileOf(node)
+    if (!source) return true
+    if (!classificationCache.has(source)) classificationCache.set(source, classifier.explain(source, {content: ''}))
+    const info = classificationCache.get(source)
+    const classified = NON_PRODUCT_CLASSES.filter((category) => hasPathClass(info, category))
+    return classified.length === 0 || classified.some((category) => requestedClasses.has(category))
+}
+
+function entrypointSignal(g, node, source, stem) {
+    if (isSymbol(node.id) || !CODE_FILE_RE.test(source)) return 0
+    const depth = source.split('/').length
+    let score = 0
+    if (node.entrypoint === true || node.is_entrypoint === true || node.declared_entry === true) score = 72
+    if (/^bin\//.test(source) || /\/(?:bin|cmd)\//.test(source)) score = Math.max(score, 62)
+    if (depth <= 2 && /^(?:index|main|app|server|cli|bootstrap|entry|run)$/.test(stem)) score = Math.max(score, 60)
+    if (depth <= 2 && /(?:^|[-_.])(?:main|server|cli|bootstrap|entry)(?:$|[-_.])/.test(stem)) score = Math.max(score, 57)
+    if (depth <= 3 && /^(?:main|app|server|cli|bootstrap|entry|run)$/.test(stem)) score = Math.max(score, 52)
+    const incoming = uniqueConnCount(g.inn.get(String(node.id))), outgoing = uniqueConnCount(g.out.get(String(node.id)))
+    if (score && incoming === 0 && outgoing > 0) score += Math.min(7, 2 + outgoing)
+    return score
+}
+
+function toolExecutionSignal(node, source, words, stem) {
+    if (!CODE_FILE_RE.test(source)) return 0
+    let score = 0
+    if (/(^|\/)(?:mcp(?:[-_.][^/]*)?|tools?)(?:\/|[-_.])/.test(source)) score = Math.max(score, 51)
+    if (/^(?:catalog|dispatch(?:er)?|registry)$/.test(stem)) score = Math.max(score, 68)
+    if (/^(?:tool[-_.]?(?:handler|runner|executor)|tools?[-_.])/.test(stem)) score = Math.max(score, 55)
+    if ([...words].some((word) => /^(?:dispatch|dispatcher|toolcall|toolhandler|executetool|invoketool|calltool)$/.test(word))) score = Math.max(score, 64)
+    if (source.includes('/mcp/') || stem.includes('mcp-server')) score = Math.max(score, 48)
+    return score
+}
+
+function queryConcepts(query) {
+    const tokens = wordsOf(query)
+    const toolExecution = tokens.some((token) => TOOL_EXECUTION_TRIGGERS.has(token))
+    const explanatoryWork = tokens.some((token) => token === 'how' || token === 'explain')
+    const seen = new Set(), concepts = []
+    for (const raw of tokens) {
+        if (raw.length < 2 || QUERY_STOP.has(raw)) continue
+        if (explanatoryWork && (raw === 'work' || raw === 'works' || raw === 'working')) continue
+        if (toolExecution && TOOL_EXECUTION_TERMS.includes(raw)) {
+            if (seen.has('tool-execution')) continue
+            const trigger = tokens.find((token) => TOOL_EXECUTION_TRIGGERS.has(token)) || raw
+            seen.add('tool-execution')
+            concepts.push({id: 'tool-execution', raw: trigger, terms: [trigger, ...TOOL_EXECUTION_TERMS.filter((term) => term !== trigger)]})
+            continue
+        }
+        const intent = INTENT_BY_TERM.get(raw), id = intent?.id || raw
+        if (seen.has(id)) continue
+        seen.add(id)
+        concepts.push({id, raw, terms: intent ? [raw, ...intent.terms.filter((term) => term !== raw)] : [raw]})
+    }
+    return concepts
+}
+
+function exactIdentifierSeeds(g, query, limit, {repoRoot = null} = {}) {
+    const identifiers = [...new Set((String(query || '').match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [])
+        .filter((item) => /(?:[a-z0-9][A-Z]|_)/.test(item)).map((item) => item.toLowerCase()))]
+    if (!identifiers.length) return []
+    const requestedClasses = requestedPathClasses(query), languageExtensions = requestedLanguages(query)
+    const classifier = createPathClassifier(repoRoot), classificationCache = new Map(), matches = []
+    for (const identifier of identifiers) {
+        const candidates = g.nodes.filter((node) => String(node.label || '').replace(/\(\)$/, '').toLowerCase() === identifier
+            && matchesLanguage(node, languageExtensions) && isQueryEligible(node, requestedClasses, classificationCache, classifier))
+            .sort((left, right) => degreeOf(g, right.id) - degreeOf(g, left.id) || String(left.id).localeCompare(String(right.id)))
+        for (const node of candidates) {
+            if (!matches.some((existing) => String(existing.id) === String(node.id))) matches.push(node)
+            if (matches.length >= limit) return matches
+        }
+    }
+    return matches
+}
+
+function conceptScore(g, node, concept, queryContext) {
+    const id = normPath(node.id), label = String(node.label ?? '').toLowerCase(), source = sourceFileOf(node)
+    const stem = (label.split('/').pop() || '').replace(/\.[^.]+$/, '')
+    const words = new Set(wordsOf(`${node.id} ${node.label ?? ''} ${node.source_file ?? ''}`))
+    const segments = new Set(source.split('/').flatMap((part) => wordsOf(part.replace(/\.[^.]+$/, ''))))
+    let match = 0
+    concept.terms.forEach((term, index) => {
+        const primary = index === 0
+        if (label === term || stem === term) match = Math.max(match, primary ? 60 : 42)
+        else if (segments.has(term)) match = Math.max(match, primary ? 48 : 36)
+        else if (words.has(term)) match = Math.max(match, primary ? 36 : 25)
+        else if (term.length >= 4 && term !== 'tool' && term !== 'tools' && (id.includes(term) || label.includes(term))) match = Math.max(match, primary ? 12 : 7)
+    })
+    const extension = (/\.([^.\/]+)$/.exec(source) || [])[1] || ''
+    const languageConcept = {rust: ['rs'], python: ['py', 'pyi'], py: ['py', 'pyi'], typescript: ['ts', 'tsx', 'mts', 'cts'], ts: ['ts', 'tsx', 'mts', 'cts'], javascript: ['js', 'jsx', 'mjs', 'cjs'], js: ['js', 'jsx', 'mjs', 'cjs'], nodejs: ['js', 'jsx', 'mjs', 'cjs'], golang: ['go'], go: ['go'], java: ['java'], csharp: ['cs'], dotnet: ['cs']}[concept.raw]
+    if (languageConcept?.includes(extension) && queryContext.languageExtensions.has(extension)) match = Math.max(match, 58)
+    const fileNode = !isSymbol(node.id), depth = source ? source.split('/').length : 9
+    if (concept.id === 'bootstrap') match = Math.max(match, entrypointSignal(g, node, source, stem))
+    if (concept.id === 'tool-execution') match = Math.max(match, toolExecutionSignal(node, source, words, stem))
+    if (!match) return 0
+    let score = match + (fileNode ? 7 : 0) + Math.max(0, 4 - depth) + Math.min(2, degreeOf(g, node.id) / 40)
+    if ((concept.id === 'bootstrap' || concept.id === 'tool-execution') && DATA_OR_PROSE_RE.test(source)) score -= 34
+    if ((concept.id === 'bootstrap' || concept.id === 'tool-execution') && !fileNode) score -= 18
+    if (queryContext.runtimeIntent && !queryContext.maintenanceIntent && /^(?:scripts?|tools?\/scripts?)\//.test(source)) score -= 32
+    if (queryContext.runtimeIntent && /^(?:site|website|public|static|assets)\//.test(source)) score -= 28
+    return Math.max(0, score)
+}
+
+export function findSeeds(g, query, limit = 8, {repoRoot = null} = {}) {
+    const exact = exactIdentifierSeeds(g, query, limit, {repoRoot})
+    if (exact.length) return exact
+    const concepts = queryConcepts(query)
+    if (!concepts.length || limit <= 0) return []
+    const requestedClasses = requestedPathClasses(query), languageExtensions = requestedLanguages(query)
+    const queryContext = {runtimeIntent: concepts.some((concept) => concept.id === 'bootstrap' || concept.id === 'tool-execution'), maintenanceIntent: wordsOf(query).some((word) => ['script', 'scripts', 'build', 'release', 'publish', 'packaging'].includes(word)), languageExtensions}
+    const classifier = createPathClassifier(repoRoot), classificationCache = new Map()
+    const rows = g.nodes.filter((node) => matchesLanguage(node, languageExtensions) && isQueryEligible(node, requestedClasses, classificationCache, classifier)).map((node) => {
+        const scores = concepts.map((concept) => conceptScore(g, node, concept, queryContext))
+        return {node, scores, total: Math.max(...scores) + scores.reduce((sum, score) => sum + score, 0) / 10}
+    })
+    const chosen = [], used = new Set()
+    for (let index = 0; index < concepts.length && chosen.length < limit; index++) {
+        const best = rows.filter((row) => !used.has(String(row.node.id)) && row.scores[index] > 0)
+            .sort((a, b) => b.scores[index] - a.scores[index] || String(a.node.id).localeCompare(String(b.node.id)))[0]
+        if (best) { chosen.push(best.node); used.add(String(best.node.id)) }
+    }
+    rows.filter((row) => row.total > 0 && !used.has(String(row.node.id)))
+        .sort((a, b) => b.total - a.total || String(a.node.id).localeCompare(String(b.node.id)))
+        .slice(0, Math.max(0, limit - chosen.length)).forEach((row) => chosen.push(row.node))
+    return chosen
+}
+
+export function resolveSeedFiles(g, requested, limit = 12) {
+    const files = Array.isArray(requested) ? requested.slice(0, limit) : [], seeds = [], missing = []
+    for (const raw of files) {
+        const wanted = normPath(raw)
+        const node = g.nodes.find((candidate) => !isSymbol(candidate.id) && (normPath(candidate.id) === wanted || normPath(candidate.source_file) === wanted))
+        if (!node) missing.push(String(raw))
+        else if (!seeds.some((seed) => String(seed.id) === String(node.id))) seeds.push(node)
+    }
+    return {seeds, missing}
+}
+
+export function undirectedNeighbors(g, id) {
+    const seen = new Map()
+    for (const e of g.out.get(id) || []) if (e.barrelProxy !== true) seen.set(e.id, e.relation)
+    for (const e of g.inn.get(id) || []) if (e.barrelProxy !== true && !seen.has(e.id)) seen.set(e.id, e.relation)
+    return seen
+}

package/src/mcp/graph/context-state.mjs

@@ -0,0 +1,86 @@
+import {readFileSync, statSync} from 'node:fs'
+import {join} from 'node:path'
+import {spawnSync} from 'node:child_process'
+import {childProcessEnv} from '../../child-env.js'
+import {resolveRepoPath} from '../../repo-path.js'
+import {mergePrecisionOverlay, precisionSemanticInputsMatch, readPrecisionOverlay} from '../../precision/lsp-overlay.js'
+
+let stalenessCache = {key: '', checkedAt: 0, info: null}
+
+export function graphStaleness(ctx) {
+    const now = Date.now()
+    if (stalenessCache.info && stalenessCache.key === ctx.graphPath && now - stalenessCache.checkedAt < 60_000) return stalenessCache.info
+    const info = {builtAt: null, headAt: null, stale: false, behind: null}
+    try { info.builtAt = statSync(ctx.graphPath).mtime } catch { /* no graph file */ }
+    if (ctx.repoRoot && info.builtAt) {
+        try {
+            const head = spawnSync('git', ['-C', ctx.repoRoot, 'log', '-1', '--format=%cI'], {encoding: 'utf8', timeout: 4000, env: childProcessEnv()})
+            const iso = (head.stdout || '').trim()
+            if (head.status === 0 && iso) {
+                info.headAt = new Date(iso)
+                if (info.headAt > info.builtAt) {
+                    info.stale = true
+                    const count = spawnSync('git', ['-C', ctx.repoRoot, 'rev-list', '--count', `--since=${info.builtAt.toISOString()}`, 'HEAD'], {encoding: 'utf8', timeout: 4000, env: childProcessEnv()})
+                    if (count.status === 0) info.behind = Number(count.stdout.trim()) || null
+                }
+            }
+        } catch { /* git unavailable */ }
+        try {
+            const status = spawnSync('git', ['-C', ctx.repoRoot, 'status', '--porcelain'], {encoding: 'utf8', timeout: 4000, env: childProcessEnv()})
+            if (status.status === 0) {
+                let newer = 0
+                for (const line of String(status.stdout || '').split(/\r?\n/).filter(Boolean).slice(0, 200)) {
+                    const path = line.slice(3).trim().replace(/^"|"$/g, '')
+                    try { if (statSync(join(ctx.repoRoot, path)).mtime > info.builtAt) newer++ } catch { newer++ }
+                }
+                info.dirtyNewer = newer
+                if (newer > 0) info.stale = true
+            }
+        } catch { /* git unavailable */ }
+    }
+    stalenessCache = {key: ctx.graphPath, checkedAt: now, info}
+    return info
+}
+
+export const resetStalenessCache = () => { stalenessCache = {key: '', checkedAt: 0, info: null} }
+
+export function stalenessLine(ctx) {
+    const state = graphStaleness(ctx)
+    if (!state.stale) return null
+    const bits = []
+    if (state.headAt && state.headAt > state.builtAt) bits.push(`${state.behind != null ? `${state.behind} commit${state.behind === 1 ? '' : 's'}` : 'commits'} newer than the graph`)
+    if (state.dirtyNewer) bits.push(`${state.dirtyNewer} uncommitted file(s) edited after the build`)
+    return `Warning: graph may be stale — the repo has ${bits.join(' and ')} (built ${state.builtAt.toISOString()}). Line numbers may have drifted; call rebuild_graph.`
+}
+
+export function fileStalenessNote(ctx, sourceFile) {
+    if (!ctx?.repoRoot || !sourceFile) return null
+    const state = graphStaleness(ctx)
+    if (!state.builtAt) return null
+    try {
+        const resolved = resolveRepoPath(ctx.repoRoot, String(sourceFile))
+        if (resolved.ok && statSync(resolved.path).mtime > state.builtAt) {
+            return `Note: ${sourceFile} changed after the graph was built — line numbers above may have drifted (rebuild_graph refreshes them).`
+        }
+    } catch { /* missing file */ }
+    return null
+}
+
+let rawGraphCache = {path: '', mtimeMs: 0, data: null}
+
+export function rawGraph(ctx) {
+    const mtimeMs = statSync(ctx.graphPath).mtimeMs
+    if (!rawGraphCache.data || rawGraphCache.path !== ctx.graphPath || rawGraphCache.mtimeMs !== mtimeMs) {
+        rawGraphCache = {path: ctx.graphPath, mtimeMs, data: JSON.parse(readFileSync(ctx.graphPath, 'utf8'))}
+    }
+    return rawGraphCache.data
+}
+
+export function effectiveRawGraph(ctx) {
+    const raw = rawGraph(ctx)
+    const overlay = readPrecisionOverlay(ctx.graphPath, raw)
+    const safeOverlay = ctx?.repoRoot && typeof overlay?.semanticInputFingerprint === 'string'
+        && !precisionSemanticInputsMatch(overlay, ctx.repoRoot, raw)
+        ? null : overlay
+    return mergePrecisionOverlay(raw, safeOverlay)
+}

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

@@ -0,0 +1,143 @@
+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')
+}