@grafema/mcp 0.2.11 → 0.3.0-beta

package/dist/handlers/dataflow-handlers.js

@@ -1,10 +1,14 @@
 /**
  * MCP Dataflow Handlers
+ *
+ * Delegates BFS tracing to @grafema/util's shared traceDataflow module.
  */
 import { ensureAnalyzed } from '../analysis.js';
 import { getProjectPath } from '../state.js';
 import { serializeBigInt, textResult, errorResult, } from '../utils.js';
-// === TRACE HANDLERS ===
+import { isGrafemaUri, toCompactSemanticId } from '@grafema/util';
+import { traceDataflow, renderTraceNarrative, } from '@grafema/util';
+// === TRACE ALIAS (unchanged) ===
 export async function handleTraceAlias(args) {
     const db = await ensureAnalyzed();
     const { variableName, file } = args;
@@ -37,6 +41,15 @@ export async function handleTraceAlias(args) {
             break;
         }
         visited.add(current.id);
+        // Resolve REFERENCE → declaration transparently (don't add to chain)
+        if (current.type === 'REFERENCE') {
+            const resolveEdges = await db.getOutgoingEdges(current.id, ['READS_FROM']);
+            if (resolveEdges.length > 0) {
+                current = await db.getNode(resolveEdges[0].dst);
+                continue;
+            }
+            break;
+        }
         chain.push({
             type: current.type,
             name: current.name,
@@ -50,57 +63,59 @@ export async function handleTraceAlias(args) {
     }
     return textResult(`Alias chain for "${variableName}" (${chain.length} steps):\n\n${JSON.stringify(serializeBigInt(chain), null, 2)}`);
 }
+// === TRACE DATAFLOW ===
 export async function handleTraceDataFlow(args) {
     const db = await ensureAnalyzed();
-    const { source, direction = 'forward', max_depth = 10 } = args;
+    const { source, file, direction = 'forward', max_depth = 10, limit = 50, detail } = args;
     // Find source node
-    let sourceNode = null;
-    // Try to find by ID first
-    sourceNode = await db.getNode(source);
-    // If not found, search by name
+    let sourceNode = await db.getNode(source);
     if (!sourceNode) {
+        // Search by name, preferring nodes that match the file filter
+        let fallbackNode = null;
         for await (const node of db.queryNodes({ name: source })) {
+            if (file && !node.file?.includes(file)) {
+                // Keep first match as fallback in case no file-matching node is found
+                if (!fallbackNode)
+                    fallbackNode = node;
+                continue;
+            }
             sourceNode = node;
             break;
         }
-    }
-    if (!sourceNode) {
-        return errorResult(`Source "${source}" not found`);
-    }
-    const visited = new Set();
-    const paths = [];
-    async function trace(nodeId, depth, path) {
-        if (depth > max_depth || visited.has(nodeId))
-            return;
-        visited.add(nodeId);
-        const newPath = [...path, nodeId];
-        if (direction === 'forward' || direction === 'both') {
-            const outEdges = await db.getOutgoingEdges(nodeId, [
-                'ASSIGNED_FROM',
-                'DERIVES_FROM',
-                'PASSES_ARGUMENT',
-            ]);
-            for (const edge of outEdges) {
-                await trace(edge.dst, depth + 1, newPath);
-            }
-        }
-        if (direction === 'backward' || direction === 'both') {
-            const inEdges = await db.getIncomingEdges(nodeId, [
-                'ASSIGNED_FROM',
-                'DERIVES_FROM',
-                'PASSES_ARGUMENT',
-            ]);
-            for (const edge of inEdges) {
-                await trace(edge.src, depth + 1, newPath);
+        // Also try PARAMETER type nodes (often the real entry point for dataflow)
+        if (!sourceNode) {
+            for await (const node of db.queryNodes({ type: 'PARAMETER', name: source })) {
+                if (file && !node.file?.includes(file)) {
+                    if (!fallbackNode)
+                        fallbackNode = node;
+                    continue;
+                }
+                sourceNode = node;
+                break;
             }
         }
-        if (depth > 0) {
-            paths.push(newPath);
+        // Use fallback (first name match regardless of file) if no file-specific match
+        if (!sourceNode && fallbackNode) {
+            sourceNode = fallbackNode;
         }
     }
-    await trace(sourceNode.id, 0, []);
-    return textResult(`Data flow from "${source}" (${paths.length} paths):\n\n${JSON.stringify(paths, null, 2)}`);
+    if (!sourceNode) {
+        const displaySource = isGrafemaUri(source) ? toCompactSemanticId(source) : source;
+        return errorResult(`Source "${displaySource}" not found`);
+    }
+    // Cast db to DataflowBackend — runtime types are compatible
+    const dfDb = db;
+    const traceResults = await traceDataflow(dfDb, sourceNode.id, {
+        direction: direction,
+        maxDepth: max_depth,
+        limit,
+    });
+    const sourceName = sourceNode.name || source;
+    return textResult(renderTraceNarrative(traceResults, sourceName, {
+        detail: detail || 'normal',
+    }));
 }
+// === CHECK INVARIANT (unchanged) ===
 export async function handleCheckInvariant(args) {
     const db = await ensureAnalyzed();
     const { rule, name: description } = args;
@@ -109,28 +124,35 @@ export async function handleCheckInvariant(args) {
     }
     try {
         const checkFn = db.checkGuarantee;
-        const violations = await checkFn(rule);
+        const violations = await checkFn.call(db, rule);
         const total = violations.length;
         if (total === 0) {
-            return textResult(`✅ Invariant holds: ${description || 'No violations found'}`);
+            return textResult(`Invariant holds: ${description || 'No violations found'}`);
         }
         const enrichedViolations = [];
         for (const v of violations.slice(0, 20)) {
-            const nodeId = v.bindings?.find((b) => b.name === 'X')?.value;
-            if (nodeId) {
-                const node = await db.getNode(nodeId);
+            const xBinding = v.bindings?.find((b) => b.name === 'X');
+            if (xBinding) {
+                const node = await db.getNode(xBinding.value);
                 if (node) {
                     enrichedViolations.push({
-                        id: nodeId,
+                        id: xBinding.value,
                         type: node.type,
                         name: node.name,
                         file: node.file,
                         line: node.line,
                     });
                 }
+                else {
+                    const bindingsMap = {};
+                    for (const b of v.bindings) {
+                        bindingsMap[b.name] = b.value;
+                    }
+                    enrichedViolations.push(bindingsMap);
+                }
             }
         }
-        return textResult(`❌ ${total} violation(s) found:\n\n${JSON.stringify(serializeBigInt(enrichedViolations), null, 2)}${total > 20 ? `\n\n... and ${total - 20} more` : ''}`);
+        return textResult(`${total} violation(s) found:\n\n${JSON.stringify(serializeBigInt(enrichedViolations), null, 2)}${total > 20 ? `\n\n... and ${total - 20} more` : ''}`);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/handlers/dataflow-handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataflow-handlers.js","sourceRoot":"","sources":["../../src/handlers/dataflow-handlers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataflow-handlers.js","sourceRoot":"","sources":["../../src/handlers/dataflow-handlers.ts"],"names":[],"mappings":"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"}

package/dist/handlers/documentation-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documentation-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAyE5F"}
+{"version":3,"file":"documentation-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+H5F"}

package/dist/handlers/documentation-handlers.js

@@ -1,7 +1,7 @@
 /**
  * MCP Documentation Handlers
  */
-import { getOnboardingInstruction } from '@grafema/core';
+import { getOnboardingInstruction } from '@grafema/util';
 import { textResult, } from '../utils.js';
 // === DOCUMENTATION ===
 export async function handleGetDocumentation(args) {
@@ -31,7 +31,7 @@ Grafema is a static code analyzer that builds a graph of your codebase.
 violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
 
 ## Available Predicates
-- node(Id, Type) - match nodes
+- type(Id, Type) - match nodes (alias: node)
 - edge(Src, Dst, Type) - match edges
 - attr(Id, Name, Value) - match attributes
 - \\+ - negation (not)
@@ -71,6 +71,60 @@ Use check_guarantees to verify all guarantees.
 ## Example
 Name: no-eval
 Rule: violation(X) :- node(X, "CALL"), attr(X, "name", "eval").
+`,
+        notation: `
+# Grafema DSL — Compact Visual Notation
+
+Grafema DSL renders graph structure as compact, readable notation.
+Output-only — Datalog remains the query language.
+
+## Archetypes & Operators
+
+| Archetype  | Op    | Meaning                   | Example edge types                    |
+|------------|-------|---------------------------|---------------------------------------|
+| contains   | (nest)| structural containment    | CONTAINS, HAS_MEMBER, DECLARES        |
+| depends    | o-    | dependency / import       | DEPENDS_ON, IMPORTS_FROM, USES        |
+| flow_out   | >     | outward call / data flow  | CALLS, ROUTES_TO, PASSES_ARGUMENT     |
+| flow_in    | <     | inward data / type flow   | READS_FROM, ASSIGNED_FROM, EXTENDS    |
+| write      | =>    | persistent side effect    | WRITES_TO, LOGS_TO                    |
+| exception  | >x    | error / rejection         | THROWS, REJECTS, CATCHES_FROM         |
+| publishes  | ~>>   | event / message           | EMITS_EVENT, PUBLISHES_TO, EXPOSED_VIA|
+| gates      | ?|    | conditional guard         | HAS_CONDITION, HAS_CASE               |
+| governs    | |=    | governance / invariant    | GOVERNS, VIOLATES, MONITORED_BY       |
+
+## LOD Levels (depth)
+
+- **depth=0**: Node names only — minimal overview
+- **depth=1** (default): Node + edges — shows all relationships with operators
+- **depth=2**: Node + edges + nested children, **folded** — repetitive siblings compressed into exemplar + summary. Ideal for large modules (e.g., 36 handler imports → 1 exemplar + fold summary)
+- **depth=3**: Node + edges + nested children, **exact** — every node expanded individually, no folding. Use when you need the precise bijective DSL output
+
+## Perspective Presets
+
+| Preset   | Archetypes shown              | Use case                  |
+|----------|-------------------------------|---------------------------|
+| security | write, exception              | Audit side effects & errors|
+| data     | flow_out, flow_in, write      | Trace data movement       |
+| errors   | exception                     | Error handling review      |
+| api      | flow_out, publishes, depends  | API surface analysis       |
+| events   | publishes                     | Event flow mapping         |
+
+## Special Modifiers
+
+- \`??\` — uncertain/dynamic (unresolved call, dynamic import)
+- \`[]\` — inside loop (edge occurs within iteration)
+
+## Budget
+
+Default budget: 7 items per group. When exceeded, remaining items are
+summarized as \`+N more\`. Override with budget parameter.
+
+## Usage
+
+**MCP:** \`describe(target="src/app.ts->FUNCTION->main", depth=1, perspective="security")\`
+**CLI:** \`grafema describe "src/app.ts->FUNCTION->main" -d 1 --perspective security\`
+
+Target resolution order: semantic ID → file path (MODULE) → node name.
 `,
     };
     const content = docs[topic] || docs.overview;

package/dist/handlers/documentation-handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"documentation-handlers.js","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,UAAU,GACX,MAAM,aAAa,CAAC;AAMrB,wBAAwB;AAExB,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAA0B;IACrE,MAAM,EAAE,KAAK,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IAEpC,MAAM,IAAI,GAA2B;QACnC,UAAU,EAAE,wBAAwB,EAAE;QACtC,QAAQ,EAAE;;;;;;;;;;;;;;;CAeb;QACG,OAAO,EAAE;;;;;;;;;;;;;;;;;;CAkBZ;QACG,KAAK,EAAE;;;;;;;;;;;;;CAaV;QACG,UAAU,EAAE;;;;;;;;;;;;;;CAcf;KACE,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC;IAC7C,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"documentation-handlers.js","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,UAAU,GACX,MAAM,aAAa,CAAC;AAMrB,wBAAwB;AAExB,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAA0B;IACrE,MAAM,EAAE,KAAK,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IAEpC,MAAM,IAAI,GAA2B;QACnC,UAAU,EAAE,wBAAwB,EAAE;QACtC,QAAQ,EAAE;;;;;;;;;;;;;;;CAeb;QACG,OAAO,EAAE;;;;;;;;;;;;;;;;;;CAkBZ;QACG,KAAK,EAAE;;;;;;;;;;;;;CAaV;QACG,UAAU,EAAE;;;;;;;;;;;;;;CAcf;QACG,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDb;KACE,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC;IAC7C,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/dist/handlers/graph-handlers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Graph traversal handlers: get_node, get_neighbors, traverse_graph
+ * REG-521: Add raw graph traversal primitives to MCP
+ */
+import type { ToolResult, GetNodeArgs, GetNeighborsArgs, TraverseGraphArgs } from '../types.js';
+import type { EdgeType, EdgeRecord } from '@grafema/types';
+/**
+ * Minimal backend interface for graph-handler logic functions.
+ * Allows testing with mock backends without importing full GraphBackend.
+ */
+interface GraphBackendLike {
+    getNode(id: string): Promise<Record<string, unknown> | null>;
+    getOutgoingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+    getIncomingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+}
+export declare function getNodeLogic(db: GraphBackendLike, args: GetNodeArgs): Promise<ToolResult>;
+export declare function getNeighborsLogic(db: GraphBackendLike, args: GetNeighborsArgs): Promise<ToolResult>;
+export declare function traverseGraphLogic(db: GraphBackendLike, args: TraverseGraphArgs): Promise<ToolResult>;
+export declare function handleGetNode(args: GetNodeArgs): Promise<ToolResult>;
+export declare function handleGetNeighbors(args: GetNeighborsArgs): Promise<ToolResult>;
+export declare function handleTraverseGraph(args: TraverseGraphArgs): Promise<ToolResult>;
+export {};
+//# sourceMappingURL=graph-handlers.d.ts.map

package/dist/handlers/graph-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/graph-handlers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAK3D;;;GAGG;AACH,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7D,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACvF,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CACxF;AA4BD,wBAAsB,YAAY,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAkB/F;AAED,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkCzG;AAED,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwE3G;AAoBD,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAG1E;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAGpF;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAGtF"}

package/dist/handlers/graph-handlers.js

@@ -0,0 +1,155 @@
+/**
+ * Graph traversal handlers: get_node, get_neighbors, traverse_graph
+ * REG-521: Add raw graph traversal primitives to MCP
+ */
+import { ensureAnalyzed } from '../analysis.js';
+import { textResult, errorResult } from '../utils.js';
+import { isGrafemaUri, toCompactSemanticId } from '@grafema/util';
+const MAX_TRAVERSAL_RESULTS = 10_000;
+const MAX_DEPTH = 20;
+// === Shared helpers ===
+async function groupEdgesByType(edges, db, getNodeId) {
+    const grouped = {};
+    for (const edge of edges) {
+        const type = edge.type;
+        if (!grouped[type])
+            grouped[type] = [];
+        const nodeId = getNodeId(edge);
+        const node = await db.getNode(nodeId);
+        grouped[type].push({
+            id: nodeId,
+            ...(node ? { type: node.type, name: node.name, file: node.file, line: node.line } : { type: 'UNKNOWN' }),
+            ...(edge.metadata ? { edgeMetadata: edge.metadata } : {}),
+        });
+    }
+    return grouped;
+}
+// === Logic functions (testable, accept backend directly) ===
+export async function getNodeLogic(db, args) {
+    const { semanticId } = args;
+    if (!semanticId || semanticId.trim() === '') {
+        return errorResult('semanticId must be a non-empty string');
+    }
+    // Accept both grafema:// URI and compact format
+    // If URI is passed, convert to compact for error messages
+    const displayId = isGrafemaUri(semanticId) ? toCompactSemanticId(semanticId) : semanticId;
+    const node = await db.getNode(semanticId);
+    if (!node) {
+        return errorResult(`Node not found: "${displayId}". Use find_nodes to search by type, name, or file.`);
+    }
+    return textResult(JSON.stringify(node, null, 2));
+}
+export async function getNeighborsLogic(db, args) {
+    const { semanticId, direction = 'both', edgeTypes } = args;
+    if (!semanticId || semanticId.trim() === '') {
+        return errorResult('semanticId must be a non-empty string');
+    }
+    if (edgeTypes !== undefined && edgeTypes.length === 0) {
+        return errorResult('edgeTypes must not be an empty array. Omit edgeTypes to get all edge types.');
+    }
+    // Accept both grafema:// URI and compact format
+    const displayId = isGrafemaUri(semanticId) ? toCompactSemanticId(semanticId) : semanticId;
+    const node = await db.getNode(semanticId);
+    if (!node) {
+        return errorResult(`Node not found: "${displayId}". Use find_nodes to search by type, name, or file.`);
+    }
+    const edgeFilter = edgeTypes ?? null;
+    const result = {};
+    if (direction === 'outgoing' || direction === 'both') {
+        const edges = await db.getOutgoingEdges(semanticId, edgeFilter);
+        result.outgoing = await groupEdgesByType(edges, db, (e) => e.dst);
+    }
+    if (direction === 'incoming' || direction === 'both') {
+        const edges = await db.getIncomingEdges(semanticId, edgeFilter);
+        result.incoming = await groupEdgesByType(edges, db, (e) => e.src);
+    }
+    return textResult(JSON.stringify(result, null, 2));
+}
+export async function traverseGraphLogic(db, args) {
+    const { startNodeIds, edgeTypes, maxDepth = 5, direction = 'outgoing' } = args;
+    // Validate inputs
+    if (!startNodeIds || startNodeIds.length === 0) {
+        return errorResult('startNodeIds must not be empty');
+    }
+    if (!edgeTypes || edgeTypes.length === 0) {
+        return errorResult('edgeTypes must not be empty. Use get_schema(type="edges") to see available types.');
+    }
+    if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+        return errorResult('maxDepth must be a non-negative integer');
+    }
+    if (maxDepth > MAX_DEPTH) {
+        return errorResult(`maxDepth must be <= ${MAX_DEPTH} to prevent performance issues`);
+    }
+    // Deduplicate start nodes
+    const uniqueStartIds = [...new Set(startNodeIds)];
+    // Verify start nodes exist
+    for (const id of uniqueStartIds) {
+        const node = await db.getNode(id);
+        if (!node) {
+            // Accept both grafema:// URI and compact format for display
+            const displayId = isGrafemaUri(id) ? toCompactSemanticId(id) : id;
+            return errorResult(`Start node not found: "${displayId}". Use find_nodes to search by type, name, or file.`);
+        }
+    }
+    const edgeFilter = edgeTypes;
+    // Manual BFS (works for both directions, provides depth info)
+    const visited = new Set(uniqueStartIds);
+    const queue = uniqueStartIds.map(id => ({ id, depth: 0 }));
+    const results = uniqueStartIds.map(id => ({ id, depth: 0 }));
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.depth >= maxDepth)
+            continue;
+        const edges = direction === 'outgoing'
+            ? await db.getOutgoingEdges(current.id, edgeFilter)
+            : await db.getIncomingEdges(current.id, edgeFilter);
+        for (const edge of edges) {
+            const neighborId = direction === 'outgoing' ? edge.dst : edge.src;
+            if (!visited.has(neighborId)) {
+                visited.add(neighborId);
+                const nextDepth = current.depth + 1;
+                queue.push({ id: neighborId, depth: nextDepth });
+                results.push({ id: neighborId, depth: nextDepth });
+                if (results.length >= MAX_TRAVERSAL_RESULTS) {
+                    const nodes = await enrichResults(db, results);
+                    return textResult(JSON.stringify({
+                        count: nodes.length,
+                        truncated: true,
+                        message: `Traversal hit limit of ${MAX_TRAVERSAL_RESULTS} nodes. Use more specific edge types or lower maxDepth.`,
+                        nodes,
+                    }, null, 2));
+                }
+            }
+        }
+    }
+    const nodes = await enrichResults(db, results);
+    return textResult(JSON.stringify({
+        count: nodes.length,
+        truncated: false,
+        nodes,
+    }, null, 2));
+}
+async function enrichResults(db, results) {
+    return Promise.all(results.map(async ({ id, depth }) => {
+        const node = await db.getNode(id);
+        return {
+            id,
+            depth,
+            ...(node ? { type: node.type, name: node.name, file: node.file, line: node.line } : { type: 'UNKNOWN' }),
+        };
+    }));
+}
+// === Public handlers (call ensureAnalyzed, used by MCP routing) ===
+export async function handleGetNode(args) {
+    const db = await ensureAnalyzed();
+    return getNodeLogic(db, args);
+}
+export async function handleGetNeighbors(args) {
+    const db = await ensureAnalyzed();
+    return getNeighborsLogic(db, args);
+}
+export async function handleTraverseGraph(args) {
+    const db = await ensureAnalyzed();
+    return traverseGraphLogic(db, args);
+}
+//# sourceMappingURL=graph-handlers.js.map

package/dist/handlers/graph-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-handlers.js","sourceRoot":"","sources":["../../src/handlers/graph-handlers.ts"],"names":[],"mappings":"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"}

package/dist/handlers/graphql-handlers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * GraphQL query handler — execute GraphQL queries against the code graph.
+ *
+ * Uses @grafema/api's schema and resolvers in-process via graphql-yoga.
+ * No HTTP server needed — yoga.fetch() accepts synthetic Request objects.
+ */
+import type { ToolResult, GraphQLQueryArgs } from '../types.js';
+export declare function handleGraphQLQuery(args: GraphQLQueryArgs): Promise<ToolResult>;
+//# sourceMappingURL=graphql-handlers.d.ts.map

package/dist/handlers/graphql-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/graphql-handlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAsBhE,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAsCpF"}

package/dist/handlers/graphql-handlers.js

@@ -0,0 +1,57 @@
+/**
+ * GraphQL query handler — execute GraphQL queries against the code graph.
+ *
+ * Uses @grafema/api's schema and resolvers in-process via graphql-yoga.
+ * No HTTP server needed — yoga.fetch() accepts synthetic Request objects.
+ */
+import { ensureAnalyzed } from '../analysis.js';
+import { textResult, errorResult } from '../utils.js';
+let yogaInstance = null;
+let yogaBackend = null;
+/**
+ * Get or create the yoga instance.
+ * Recreated if the backend changes (e.g., after re-analysis).
+ */
+async function getYoga(backend) {
+    if (yogaInstance && yogaBackend === backend) {
+        return yogaInstance;
+    }
+    // Dynamic import to avoid loading graphql-yoga unless needed
+    const { createGraphQLServer } = await import('@grafema/api');
+    yogaInstance = createGraphQLServer({ backend });
+    yogaBackend = backend;
+    return yogaInstance;
+}
+export async function handleGraphQLQuery(args) {
+    const { query, variables, operationName } = args;
+    if (!query || query.trim() === '') {
+        return errorResult('query must be a non-empty GraphQL query string');
+    }
+    const db = await ensureAnalyzed();
+    const yoga = await getYoga(db);
+    // Build the GraphQL request body
+    const body = { query };
+    if (variables)
+        body.variables = variables;
+    if (operationName)
+        body.operationName = operationName;
+    // Execute via yoga.fetch() — no HTTP server needed
+    const response = await yoga.fetch('http://localhost/graphql', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const result = await response.json();
+    // Format output
+    if (result.errors && result.errors.length > 0) {
+        const errorMessages = result.errors.map((e) => e.message).join('\n');
+        if (result.data) {
+            // Partial success — return data with errors noted
+            return textResult(`GraphQL partial result (with errors):\n${errorMessages}\n\n` +
+                JSON.stringify(result.data, null, 2));
+        }
+        return errorResult(`GraphQL errors:\n${errorMessages}`);
+    }
+    return textResult(JSON.stringify(result.data, null, 2));
+}
+//# sourceMappingURL=graphql-handlers.js.map

package/dist/handlers/graphql-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-handlers.js","sourceRoot":"","sources":["../../src/handlers/graphql-handlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAItD,IAAI,YAAY,GAAQ,IAAI,CAAC;AAC7B,IAAI,WAAW,GAA6B,IAAI,CAAC;AAEjD;;;GAGG;AACH,KAAK,UAAU,OAAO,CAAC,OAA0B;IAC/C,IAAI,YAAY,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QAC5C,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,6DAA6D;IAC7D,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;IAC7D,YAAY,GAAG,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAChD,WAAW,GAAG,OAAO,CAAC;IACtB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAsB;IAC7D,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAEjD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAClC,OAAO,WAAW,CAAC,gDAAgD,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAuB,CAAC,CAAC;IAEpD,iCAAiC;IACjC,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,CAAC;IAChD,IAAI,SAAS;QAAE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1C,IAAI,aAAa;QAAE,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IAEtD,mDAAmD;IACnD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,0BAA0B,EAAE;QAC5D,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAErC,gBAAgB;IAChB,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1E,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,kDAAkD;YAClD,OAAO,UAAU,CACf,0CAA0C,aAAa,MAAM;gBAC7D,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CACrC,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC,oBAAoB,aAAa,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/handlers/guarantee-handlers.js

@@ -3,7 +3,7 @@
  */
 import { getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI } from '../state.js';
 import { textResult, errorResult, } from '../utils.js';
-import { isGuaranteeType } from '@grafema/core';
+import { isGuaranteeType } from '@grafema/util';
 // === GUARANTEE HANDLERS ===
 /**
  * Create a new guarantee (Datalog-based or contract-based)

package/dist/handlers/guard-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/guard-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAEf,MAAM,aAAa,CAAC;AAIrB;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAyEhF"}
+{"version":3,"file":"guard-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/guard-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAEf,MAAM,aAAa,CAAC;AAIrB;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA4EhF"}

package/dist/handlers/guard-handlers.js

@@ -3,6 +3,7 @@
  */
 import { getOrCreateBackend } from '../state.js';
 import { serializeBigInt, textResult, errorResult, } from '../utils.js';
+import { isGrafemaUri, toCompactSemanticId } from '@grafema/util';
 // === FIND GUARDS (REG-274) ===
 /**
  * Find conditional guards protecting a node.
@@ -15,10 +16,12 @@ import { serializeBigInt, textResult, errorResult, } from '../utils.js';
 export async function handleFindGuards(args) {
     const db = await getOrCreateBackend();
     const { nodeId } = args;
+    // Accept both grafema:// URI and compact format
+    const displayId = isGrafemaUri(nodeId) ? toCompactSemanticId(nodeId) : nodeId;
     // Verify target node exists
     const targetNode = await db.getNode(nodeId);
     if (!targetNode) {
-        return errorResult(`Node not found: ${nodeId}`);
+        return errorResult(`Node not found: ${displayId}`);
     }
     const guards = [];
     const visited = new Set();
@@ -60,7 +63,7 @@ export async function handleFindGuards(args) {
         currentId = parentId;
     }
     if (guards.length === 0) {
-        return textResult(`No guards found for node: ${nodeId}\n` +
+        return textResult(`No guards found for node: ${displayId}\n` +
             `The node is not protected by any conditional scope (if/else/switch/etc.).`);
     }
     const summary = guards.map((g, i) => {
@@ -68,7 +71,7 @@ export async function handleFindGuards(args) {
         return `${indent}${i + 1}. ${g.scopeType} at ${g.file}:${g.line}` +
             (g.condition ? `\n${indent}   condition: ${g.condition}` : '');
     }).join('\n');
-    return textResult(`Found ${guards.length} guard(s) for node: ${nodeId}\n` +
+    return textResult(`Found ${guards.length} guard(s) for node: ${displayId}\n` +
         `(inner to outer order)\n\n` +
         summary +
         `\n\n` +