weavatrix 0.1.4 → 0.2.1

package/src/mcp/tools-company.mjs

@@ -0,0 +1,273 @@
+// Cross-repository HTTP contract intelligence. Repository paths are resolved only through the
+// local global registry; callers can select an opaque repository UUID or an unambiguous label but
+// can never pass an arbitrary filesystem path through this tool.
+import {join} from 'node:path'
+import {analyzeHttpContracts} from '../analysis/http-contracts.js'
+import {buildGraphForRepo} from '../build-graph.js'
+import {graphHomeDir} from '../graph/layout.js'
+import {liveRepositoryRecords} from '../graph/repo-registry.js'
+import {loadGraph} from './graph-context.mjs'
+import {toolResult} from './tool-result.mjs'
+
+const selectorText = (value) => String(value ?? '').trim()
+
+function selectRecord(records, selector) {
+    const query = selectorText(selector)
+    if (!query) return {error: 'repository selector is required'}
+    const byId = records.find((record) => record.repositoryId === query)
+    if (byId) return {record: byId}
+    const byLabel = records.filter((record) => String(record.label || '').toLowerCase() === query.toLowerCase())
+    if (byLabel.length === 1) return {record: byLabel[0]}
+    if (byLabel.length > 1) return {
+        error: `repository label "${query}" is ambiguous; use one of these repository IDs`,
+        candidates: byLabel.map((record) => ({repositoryId: record.repositoryId, label: record.label})),
+    }
+    return {error: `repository "${query}" is not present in the live global graph registry`}
+}
+
+function safeAlias(record, records) {
+    const base = String(record.label || 'repo').normalize('NFKC')
+        .replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '').slice(0, 56) || 'repo'
+    const duplicates = records.filter((item) => String(item.label || '').toLowerCase() === String(record.label || '').toLowerCase())
+    return duplicates.length > 1 ? `${base}-${String(record.repositoryId).slice(0, 8)}` : base
+}
+
+function publicRecord(record, alias) {
+    return {repositoryId: record.repositoryId, label: record.label, alias}
+}
+
+function safeRefreshReason(record, error) {
+    let message = String(error instanceof Error ? error.message : error || 'graph refresh failed')
+    for (const path of [record.repoPath, record.graphDir]) {
+        if (!path) continue
+        message = message.split(String(path)).join(record.label || 'repository')
+        message = message.split(String(path).replace(/\\/g, '/')).join(record.label || 'repository')
+    }
+    return message.replace(/[\r\n]+/g, ' ').trim().slice(0, 400) || 'graph refresh failed'
+}
+
+async function reconcileGraph(record, alias, role, graphHome) {
+    let build
+    try {
+        build = await buildGraphForRepo(record.repoPath, {
+            mode: 'full',
+            scope: '',
+            outDir: record.graphDir,
+            graphHome,
+        })
+    } catch (error) {
+        build = {ok: false, error: safeRefreshReason(record, error)}
+    }
+    const refreshKind = build?.refresh?.kind || null
+    const changedFiles = Array.isArray(build?.refresh?.changedFiles) ? build.refresh.changedFiles : []
+    const publicStatus = {
+        role,
+        repository: publicRecord(record, alias),
+        status: build?.ok ? (refreshKind === 'none' ? 'CURRENT' : 'REFRESHED') : 'STALE_FALLBACK',
+        refresh: build?.ok ? {
+            kind: refreshKind || 'full',
+            reason: String(build?.refresh?.reason || 'graph-rebuilt'),
+            changedFileCount: changedFiles.length,
+        } : null,
+    }
+    if (build?.ok) {
+        try {
+            return {record, alias, graph: loadGraph(join(record.graphDir, 'graph.json')), publicStatus}
+        } catch (error) {
+            const reason = `refreshed graph could not be loaded: ${safeRefreshReason(record, error)}`
+            return {record, alias, graph: null, reason, publicStatus: {...publicStatus, status: 'FAILED', reason}}
+        }
+    }
+
+    const reason = `graph refresh failed: ${safeRefreshReason(record, build?.error)}`
+    try {
+        return {
+            record,
+            alias,
+            graph: loadGraph(join(record.graphDir, 'graph.json')),
+            reason: `${reason}; stale registered graph used`,
+            publicStatus: {...publicStatus, reason: `${reason}; stale registered graph used`},
+        }
+    } catch (error) {
+        const loadReason = `${reason}; registered graph could not be loaded: ${safeRefreshReason(record, error)}`
+        return {record, alias, graph: null, reason: loadReason, publicStatus: {...publicStatus, status: 'FAILED', reason: loadReason}}
+    }
+}
+
+function verdictFor(analysis) {
+    const endpointsWithCallers = analysis.endpoints.filter((endpoint) => endpoint.callsites.length > 0)
+    const affectedFiles = new Set()
+    const affectedScreens = new Set()
+    for (const endpoint of endpointsWithCallers) {
+        for (const item of endpoint.affected.files || []) affectedFiles.add(`${item.client}\0${item.file}`)
+        for (const item of endpoint.affected.screens || []) affectedScreens.add(`${item.client}\0${item.file}`)
+    }
+    let code = 'NO_ENDPOINTS_MATCHED', risk = 'unknown'
+    if (analysis.totals.endpoints > 0 && analysis.totals.matches === 0) {
+        code = analysis.totals.methodMismatches > 0 ? 'HTTP_METHOD_MISMATCH' : 'NO_STATIC_CLIENT_CALLERS'
+        risk = analysis.totals.methodMismatches > 0 ? 'high' : 'unknown'
+    } else if (analysis.totals.matches > 0 && analysis.totals.methodMismatches > 0) {
+        code = 'CLIENTS_AT_RISK_WITH_METHOD_MISMATCHES'; risk = 'high'
+    } else if (analysis.totals.matches > 0) {
+        code = 'CLIENTS_AT_RISK'; risk = 'medium'
+    }
+    return {
+        code,
+        risk,
+        endpointsWithCallers: endpointsWithCallers.length,
+        callsites: analysis.totals.matches,
+        affectedFiles: affectedFiles.size,
+        affectedScreens: affectedScreens.size,
+        methodMismatches: analysis.totals.methodMismatches,
+        uncertainCalls: analysis.totals.uncertainCalls,
+    }
+}
+
+function verdictLine(verdict, endpoints) {
+    if (verdict.code === 'NO_ENDPOINTS_MATCHED') {
+        return 'VERDICT NO_ENDPOINTS_MATCHED — no backend endpoint satisfied the requested method/path/change filter.'
+    }
+    if (verdict.code === 'NO_STATIC_CLIENT_CALLERS') {
+        return `VERDICT NO_STATIC_CLIENT_CALLERS — ${endpoints} backend endpoint(s) matched, but no bounded literal/template client call was proven; this is unknown, not proof of no consumers.`
+    }
+    if (verdict.code === 'HTTP_METHOD_MISMATCH') {
+        return `VERDICT HTTP_METHOD_MISMATCH — ${verdict.methodMismatches} client call(s) match the route shape with a different method.`
+    }
+    return `VERDICT ${verdict.code} — ${verdict.callsites} callsite(s) reach ${verdict.endpointsWithCallers} endpoint(s); ${verdict.affectedScreens} screen(s) and ${verdict.affectedFiles} file(s) are in the bounded blast radius.`
+}
+
+export async function tTraceApiContract(_g, args = {}, ctx = {}) {
+    const graphHome = ctx.graphHome || graphHomeDir()
+    const records = liveRepositoryRecords(graphHome)
+    if (!records.length) return toolResult(
+        'VERDICT NOT_CONFIGURED — the global repository registry has no live graphs. Open/build both the backend and client repositories first.',
+        {status: 'NOT_CONFIGURED', availableRepositories: []},
+    )
+
+    const backendSelection = selectRecord(records, args.backend)
+    if (!backendSelection.record) return toolResult(
+        `VERDICT INVALID_REPOSITORY — ${backendSelection.error}.`,
+        {status: 'INVALID_REPOSITORY', role: 'backend', ...backendSelection, availableRepositories: records.map((record) => publicRecord(record, safeAlias(record, records)))},
+    )
+    const rawClients = Array.isArray(args.clients) ? args.clients.slice(0, 20) : []
+    if (!rawClients.length) return toolResult(
+        'VERDICT INVALID_REPOSITORY — at least one client repository ID or label is required.',
+        {status: 'INVALID_REPOSITORY', role: 'clients'},
+    )
+    const clientRecords = []
+    for (const selector of rawClients) {
+        const selected = selectRecord(records, selector)
+        if (!selected.record) return toolResult(
+            `VERDICT INVALID_REPOSITORY — ${selected.error}.`,
+            {status: 'INVALID_REPOSITORY', role: 'client', selector, ...selected},
+        )
+        if (!clientRecords.some((record) => record.repositoryId === selected.record.repositoryId)) clientRecords.push(selected.record)
+    }
+    if (clientRecords.some((record) => record.repositoryId === backendSelection.record.repositoryId)) return toolResult(
+        'VERDICT INVALID_REPOSITORY — backend and client selections must be distinct repositories.',
+        {status: 'INVALID_REPOSITORY', role: 'clients'},
+    )
+
+    const backend = backendSelection.record
+    const backendAlias = safeAlias(backend, records)
+    const clients = clientRecords.map((record) => ({record, alias: safeAlias(record, records)}))
+    const reconciled = []
+    for (const selected of [
+        {record: backend, alias: backendAlias, role: 'backend'},
+        ...clients.map(({record, alias}) => ({record, alias, role: 'client'})),
+    ]) {
+        reconciled.push(await reconcileGraph(selected.record, selected.alias, selected.role, graphHome))
+    }
+    const backendGraph = reconciled[0]
+    const clientGraphs = reconciled.slice(1)
+    const reconciliationReasons = reconciled.filter((item) => item.reason).map((item) => item.reason)
+    const graphReconciliation = reconciled.map((item) => item.publicStatus)
+    if (!backendGraph.graph || clientGraphs.some((item) => !item.graph)) {
+        const reasons = reconciliationReasons.length ? reconciliationReasons : ['one or more selected graphs could not be refreshed and loaded']
+        const completeness = {complete: false, status: 'PARTIAL', reasons}
+        return toolResult(
+            `VERDICT PARTIAL — selected repository graphs could not all be refreshed and loaded.\nCompleteness: partial — ${reasons.join('; ')}.`,
+            {
+                crossRepoHttpContractV: 1,
+                status: 'PARTIAL',
+                repositories: {
+                    backend: publicRecord(backend, backendAlias),
+                    clients: clients.map(({record, alias}) => publicRecord(record, alias)),
+                },
+                graphReconciliation,
+                completeness,
+            },
+            {completeness, warnings: [{code: 'CROSS_REPO_GRAPH_REFRESH_PARTIAL', message: reasons.join('; ')}]},
+        )
+    }
+
+    try {
+        const analysis = analyzeHttpContracts({
+            backend: {id: backendAlias, repoRoot: backend.repoPath, graph: backendGraph.graph},
+            clients: clientGraphs.map((item) => ({id: item.alias, repoRoot: item.record.repoPath, graph: item.graph})),
+            method: args.method,
+            path: args.path,
+            changedFiles: args.changed_files,
+            includeTests: args.include_tests === true,
+            maxImpactDepth: args.max_impact_depth,
+            maxEndpoints: args.max_endpoints,
+            maxMatches: args.max_matches,
+            maxAffectedFiles: args.max_affected_files,
+        })
+        const verdict = verdictFor(analysis)
+        const reasons = [...new Set([...reconciliationReasons, ...(analysis.completeness?.reasons || [])])]
+        const completeness = {
+            complete: reasons.length === 0 && analysis.completeness?.complete === true,
+            status: reasons.length === 0 && analysis.completeness?.complete === true ? 'COMPLETE' : 'PARTIAL',
+            reasons,
+        }
+        const topN = Math.max(1, Math.min(50, Number(args.top_n) || 10))
+        const ranked = [...analysis.endpoints].sort((left, right) =>
+            right.callsites.length - left.callsites.length ||
+            right.affected.files.length - left.affected.files.length ||
+            left.path.localeCompare(right.path))
+        const lines = [
+            verdictLine(verdict, analysis.totals.endpoints),
+            `Scope: ${backend.label} → ${clients.map(({record}) => record.label).join(', ')}; ${analysis.totals.endpoints} endpoint(s), ${analysis.totals.clientCalls} inspected client call(s), ${analysis.totals.uncertainCalls} uncertain.`,
+            ...ranked.slice(0, topN).flatMap((endpoint) => {
+                const location = endpoint.file ? ` (${endpoint.backend}:${endpoint.file}${endpoint.line ? `:${endpoint.line}` : ''})` : ''
+                const callsites = endpoint.callsites.slice(0, 3)
+                    .map((call) => `    caller ${call.clientRepo}:${call.file}:${call.line} (${call.match.confidence}, ${call.match.kind})`)
+                const screens = endpoint.affected.screens.slice(0, 3)
+                    .map((screen) => `    screen ${screen.client}:${screen.file} (distance ${screen.distance})`)
+                return [
+                    `  ${endpoint.method} ${endpoint.path}${location} → ${endpoint.callsites.length} callsite(s), ${endpoint.affected.screens.length} screen(s), ${endpoint.affected.files.length} affected file(s)`,
+                    ...callsites,
+                    ...screens,
+                ]
+            }),
+            completeness.complete
+                ? 'Completeness: complete within the declared repository graphs and static HTTP-call model.'
+                : `Completeness: partial — ${completeness.reasons.join('; ')}.`,
+        ]
+        const result = {
+            crossRepoHttpContractV: 1,
+            verdict,
+            repositories: {
+                backend: publicRecord(backend, backendAlias),
+                clients: clients.map(({record, alias}) => publicRecord(record, alias)),
+            },
+            ...analysis,
+            status: completeness.status,
+            graphReconciliation,
+            completeness,
+        }
+        return toolResult(lines.join('\n'), result, {
+            completeness,
+            warnings: completeness.complete ? [] : [{code: 'CROSS_REPO_ANALYSIS_PARTIAL', message: completeness.reasons.join('; ')}],
+        })
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : 'cross-repository analysis failed'
+        const completeness = {complete: false, status: 'PARTIAL', reasons: [reason]}
+        return toolResult(
+            `VERDICT PARTIAL — ${reason}.`,
+            {status: 'PARTIAL', graphReconciliation, completeness},
+            {completeness, warnings: [{code: 'CROSS_REPO_ANALYSIS_PARTIAL', message: reason}]},
+        )
+    }
+}

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

@@ -1,14 +1,30 @@
 // Connectivity-hub reporting, split from the general graph query tools.
 import {connList} from './graph-context.mjs'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
 
 const isCompileTimeEdge = (edge) => edge?.typeOnly === true || edge?.compileOnly === true
+const NON_PRODUCT_CLASSES = Object.freeze(['test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
+const sourceFileOf = (node) => String(node?.source_file || (node?.file_type === 'code' ? node?.id : '') || '').replace(/\\/g, '/')
 
-export function tGodNodes(g, {top_n = 10} = {}) {
+export function tGodNodes(g, {top_n = 10, include_classified = false} = {}, ctx = {}) {
     const n = Math.max(1, Math.min(100, Number(top_n) || 10))
+    const classifier = createPathClassifier(ctx.repoRoot || null)
+    const classificationByFile = new Map()
+    const isNonProduct = (node) => {
+        if (include_classified === true) return false
+        const file = sourceFileOf(node)
+        if (!file) return false
+        if (!classificationByFile.has(file)) classificationByFile.set(file, classifier.explain(file))
+        const info = classificationByFile.get(file)
+        return info.excluded || hasPathClass(info, ...NON_PRODUCT_CLASSES)
+    }
+    const excludedIds = new Set(g.nodes.filter(isNonProduct).map((node) => String(node.id)))
     const scored = g.nodes
+        .filter((node) => !excludedIds.has(String(node.id)))
         .map((node) => {
-            const rawOuts = g.out.get(String(node.id)) || []
-            const rawIns = g.inn.get(String(node.id)) || []
+            // Coupling from a suppressed artifact must not inflate an otherwise valid product hub.
+            const rawOuts = (g.out.get(String(node.id)) || []).filter((edge) => !excludedIds.has(String(edge.id)))
+            const rawIns = (g.inn.get(String(node.id)) || []).filter((edge) => !excludedIds.has(String(edge.id)))
             const outs = connList(rawOuts)
             const ins = connList(rawIns)
             const ownedMethods = new Set(rawOuts.filter((e) => e.relation === 'method').map((e) => String(e.id)))
@@ -54,5 +70,8 @@ export function tGodNodes(g, {top_n = 10} = {}) {
         ...occurrenceHotspots.map((r) =>
             `  ${r.node.label ?? r.node.id}  (${r.occurrences} occurrences across ${r.deg} unique neighbors; ${r.occurrences - r.deg} repeats)  [${r.node.id}]`
         ),
+        excludedIds.size > 0 && include_classified !== true
+            ? `${excludedIds.size} node(s) classified as tests/e2e/generated/build output/mocks/stories/docs/benchmarks/temp or explicitly excluded were omitted; pass include_classified:true to inspect them.`
+            : null,
     ].filter((line) => line != null).join('\n')
 }

package/src/mcp/tools-graph.mjs

@@ -3,7 +3,7 @@
 // staleness probe in graph-context. Hot-reloadable (re-imported by catalog.mjs on change).
 import {
     isSymbol, degreeOf, labelOf, connList,
-    resolveNodeInfo, resolveNode, ambiguityNote, findSeeds, undirectedNeighbors,
+    resolveNodeInfo, resolveNode, ambiguityNote, findSeeds, resolveSeedFiles, undirectedNeighbors,
     graphStaleness, fileStalenessNote,
 } from './graph-context.mjs'
 
@@ -40,6 +40,7 @@ export function tGraphStats(g, ctx) {
         `- 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.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)`,
         `- Relations: ${fmt(relCount)}`,
         Object.keys(confCount).length ? `- Confidence: ${fmt(confCount)}` : null,
         `- Communities: ${comm.size} (top by size: ${topComm.map(([c, n]) => `#${c}=${n}`).join(', ')})`,
@@ -58,6 +59,8 @@ export function tGetNode(g, {label} = {}, ctx) {
     const drift = ctx ? fileStalenessNote(ctx, n.source_file || (isSymbol(id) ? id.split('#')[0] : id)) : null
     const outs = g.out.get(id) || []
     const ins = g.inn.get(id) || []
+    const semanticOuts = connList(outs)
+    const semanticIns = connList(ins)
     const sample = (list, dir) =>
         list
             .slice(0, 12)
@@ -70,7 +73,7 @@ export function tGetNode(g, {label} = {}, ctx) {
         `- kind: ${isSymbol(id) ? 'symbol' : 'file'}${n.file_type ? ` (${n.file_type})` : ''}`,
         n.source_file ? `- source: ${n.source_file}${n.source_location ? ` ${n.source_location}` : ''}` : null,
         n.community != null ? `- community: ${n.community}` : null,
-        `- degree: ${outs.length + ins.length} (out ${outs.length}, in ${ins.length})`,
+        `- semantic degree: ${semanticOuts.length + semanticIns.length} (out ${semanticOuts.length}, in ${semanticIns.length})${outs.length + ins.length !== semanticOuts.length + semanticIns.length ? `; ${outs.length + ins.length} physical/structural edges retained` : ''}`,
         `Outgoing:\n${sample(outs, 'out')}`,
         `Incoming:\n${sample(ins, 'in')}`,
         drift,
@@ -151,8 +154,14 @@ export function tGetCommunity(g, {community_id} = {}) {
 // A plain BFS/DFS flood dumps every reached node (thousands on a real graph) at near-zero signal.
 // Instead: traverse to record reach + distance-from-seed, then show only the closest, most-connected
 // slice as a coherent subgraph (edges kept only among shown nodes). Honest about what was trimmed.
-export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filter, token_budget = 2000} = {}) {
-    const seeds = findSeeds(g, question, 6)
+export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filter, seed_files, augment_seeds = false, token_budget = 2000} = {}) {
+    const pinned = resolveSeedFiles(g, seed_files)
+    // Exact seed files are a control surface, not a hint: by default they disable fuzzy keyword seeds.
+    // Callers can opt back into augmentation when they explicitly want both behaviors.
+    const automatic = pinned.seeds.length && augment_seeds !== true
+        ? []
+        : findSeeds(g, question, Math.max(0, 8 - pinned.seeds.length))
+    const seeds = [...pinned.seeds, ...automatic.filter((node) => !pinned.seeds.some((seed) => String(seed.id) === String(node.id)))]
     if (!seeds.length) return `No nodes matched "${question}".`
     const maxDepth = Math.max(1, Math.min(6, Number(depth) || 3))
     const ctx = Array.isArray(context_filter) && context_filter.length ? new Set(context_filter.map((c) => String(c).toLowerCase())) : null
@@ -161,7 +170,6 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
     // node budget scales gently with the token budget; edges follow the surviving nodes.
     const nodeBudget = Math.max(20, Math.min(120, Math.round((Number(token_budget) || 2000) / 40)))
     const depthOf = new Map() // id -> shortest distance from any seed
-    const edges = []
     const start = seeds.map((s) => String(s.id))
     if (mode === 'dfs') {
         const stack = start.map((id) => ({id, d: 0}))
@@ -174,7 +182,6 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
             if (d >= maxDepth) continue
             for (const [nid, rel] of undirectedNeighbors(g, id)) {
                 if (!relOk(rel)) continue
-                edges.push([id, rel, nid])
                 if (!seen.has(nid)) stack.push({id: nid, d: d + 1})
             }
         }
@@ -186,7 +193,6 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
             for (const id of frontier)
                 for (const [nid, rel] of undirectedNeighbors(g, id)) {
                     if (!relOk(rel)) continue
-                    edges.push([id, rel, nid])
                     if (!depthOf.has(nid)) {
                         depthOf.set(nid, d + 1)
                         next.push(nid)
@@ -203,24 +209,29 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
     const shownIds = new Set(shown.map((n) => n.id))
     const edgeSeen = new Set()
     const shownEdges = []
-    for (const [s, r, t] of edges) {
-        if (!shownIds.has(s) || !shownIds.has(t)) continue
-        const key = `${s}|${r}|${t}`
-        if (edgeSeen.has(key)) continue
-        edgeSeen.add(key)
-        shownEdges.push([s, r, t])
+    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) || !relOk(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}${ctx ? `, context ${[...ctx].join('/')}` : ''})`,
         `Seeds: ${seeds.map((s) => s.label ?? s.id).join(', ')}`,
+        pinned.missing.length ? `Unresolved pinned seed files: ${pinned.missing.join(', ')}` : null,
         `Reached ${depthOf.size} nodes; showing ${shown.length} closest by proximity + connectivity, ${shownEdges.length} edges among them.`,
         ``,
         `Nodes:`,
     ]
     const nodeLines = shown.map((n) => `  [d${n.d}] ${labelOf(g, n.id)}  (deg ${n.deg})  [${n.id}]`)
     const edgeLines = ['', 'Edges:', ...shownEdges.map(([s, r, t]) => `  ${labelOf(g, s)} --${r || 'rel'}--> ${labelOf(g, t)}`)]
-    let text = [...head, ...nodeLines, ...edgeLines].join('\n')
+    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
 }