@reactgraph/cli 0.1.1

package/src/mcp/formatter.ts

@@ -0,0 +1,757 @@
+import { ReactGraph } from '../graph/graph.js';
+import { getSubgraph } from '../graph/traverse.js';
+import type { GraphNode, GraphEdge, NodeKind } from '../graph/schema.js';
+
+/**
+ * Generate the full project map — token-optimized structured text.
+ */
+export function formatMap(graph: ReactGraph, maxComponents: number = 30): string {
+  const stats = graph.stats();
+  const lines: string[] = [];
+
+  const routeCount = stats.Route ?? 0;
+  const storeCount = stats.Store ?? 0;
+  const endpointCount = stats.ApiEndpoint ?? 0;
+
+  // Header
+  lines.push(`# REACTGRAPH MAP | ${stats.Component ?? 0} components, ${stats.Hook ?? 0} hooks, ${storeCount} stores, ${routeCount} routes`);
+  lines.push(`# Indexed: ${new Date().toISOString()} | ${stats.files} files`);
+  lines.push('');
+
+  // Routes section
+  const routes = graph.getNodesByKind('Route');
+  const endpoints = graph.getNodesByKind('ApiEndpoint');
+  if (routes.length > 0 || endpoints.length > 0) {
+    lines.push('## ROUTES');
+    for (const route of routes) {
+      const rendersEdges = graph.getEdgesFrom(route.id, ['renders']);
+      const component = rendersEdges.length > 0 ? resolveNodeName(graph, rendersEdges[0]!.target) : '';
+      const role = route.meta.role ? ` [${route.meta.role}]` : '';
+      lines.push(`${route.name.padEnd(25)} → ${component}${role}  [${route.file}]`);
+    }
+    for (const ep of endpoints) {
+      lines.push(`${ep.name.padEnd(25)} [${ep.file}]`);
+    }
+    lines.push('');
+  }
+
+  // Components section
+  const components = graph.getNodesByKind('Component')
+    .map(c => ({ node: c, conn: graph.connectivity(c.id) }))
+    .sort((a, b) => b.conn - a.conn)
+    .slice(0, maxComponents);
+
+  if (components.length > 0) {
+    lines.push(`## COMPONENTS (top ${Math.min(maxComponents, components.length)} by connectivity)`);
+
+    for (const { node } of components) {
+      lines.push(`${node.name}  [${node.file}:${node.line}]`);
+
+      // What it renders
+      const rendersEdges = graph.getEdgesFrom(node.id, ['renders']);
+      if (rendersEdges.length > 0) {
+        const rendered = rendersEdges
+          .map(e => resolveNodeName(graph, e.target))
+          .filter(Boolean);
+        lines.push(`  renders: ${rendered.join(', ')}`);
+      }
+
+      // Hooks used
+      const hookEdges = graph.getEdgesFrom(node.id, ['uses_hook']);
+      if (hookEdges.length > 0) {
+        const hooks = hookEdges
+          .map(e => (e.meta.hookName as string) ?? resolveNodeName(graph, e.target))
+          .filter(h => !h.startsWith('builtin:'));
+        if (hooks.length > 0) {
+          lines.push(`  hooks: ${hooks.join(', ')}`);
+        }
+      }
+
+      // Context
+      const provides = graph.getEdgesFrom(node.id, ['provides']);
+      const consumes = graph.getEdgesFrom(node.id, ['consumes']);
+      if (provides.length > 0 || consumes.length > 0) {
+        const parts: string[] = [];
+        for (const e of provides) parts.push(`${resolveNodeName(graph, e.target)}(provides)`);
+        for (const e of consumes) parts.push(`${resolveNodeName(graph, e.target)}(read)`);
+        lines.push(`  context: ${parts.join(', ')}`);
+      }
+
+      // Store reads/writes
+      const reads = graph.getEdgesFrom(node.id, ['reads_store']);
+      const writes = graph.getEdgesFrom(node.id, ['writes_store']);
+      if (reads.length > 0 || writes.length > 0) {
+        const parts: string[] = [];
+        const seen = new Set<string>();
+        for (const e of reads) {
+          const name = resolveNodeName(graph, e.target);
+          if (!seen.has(name)) { parts.push(`${name}(read)`); seen.add(name); }
+        }
+        for (const e of writes) {
+          const name = resolveNodeName(graph, e.target);
+          if (!seen.has(name)) { parts.push(`${name}(write)`); seen.add(name); }
+          else {
+            // Upgrade to read/write
+            const idx = parts.findIndex(p => p.startsWith(name));
+            if (idx >= 0) parts[idx] = `${name}(read/write)`;
+          }
+        }
+        lines.push(`  state: ${parts.join(', ')}`);
+      }
+
+      // API calls
+      const fetches = graph.getEdgesFrom(node.id, ['fetches']);
+      if (fetches.length > 0) {
+        const apis = fetches.map(e => `${e.meta.method} ${e.meta.url}`);
+        lines.push(`  fetches: ${apis.join(', ')}`);
+      }
+
+      // Props
+      if (node.props && node.props.length > 0) {
+        lines.push(`  props: ${node.props.join(', ')}`);
+      } else if (node.exportType === 'default') {
+        lines.push(`  props: none (page component)`);
+      }
+
+      lines.push('');
+    }
+  }
+
+  // Hooks section
+  const hooks = graph.getNodesByKind('Hook');
+  if (hooks.length > 0) {
+    lines.push('## HOOKS');
+    for (const hook of hooks) {
+      lines.push(`${hook.name}  [${hook.file}:${hook.line}]`);
+
+      if (hook.returns) lines.push(`  returns: ${hook.returns}`);
+
+      // Store reads/writes
+      const reads = graph.getEdgesFrom(hook.id, ['reads_store']);
+      const writes = graph.getEdgesFrom(hook.id, ['writes_store']);
+      if (reads.length > 0 || writes.length > 0) {
+        const parts: string[] = [];
+        for (const e of reads) parts.push(`${resolveNodeName(graph, e.target)}(read)`);
+        for (const e of writes) parts.push(`${resolveNodeName(graph, e.target)}(write)`);
+        lines.push(`  state: ${parts.join(', ')}`);
+      }
+
+      // API calls
+      const fetches = graph.getEdgesFrom(hook.id, ['fetches']);
+      if (fetches.length > 0) {
+        const apis = fetches.map(e => `${e.meta.method} ${e.meta.url}`);
+        lines.push(`  fetches: ${apis.join(', ')}`);
+      }
+
+      // Who uses this hook
+      const usedBy = graph.getEdgesTo(hook.id, ['uses_hook']);
+      if (usedBy.length > 0) {
+        const users = usedBy.map(e => resolveNodeName(graph, e.source)).filter(Boolean);
+        const display = users.length > 5
+          ? `${users.slice(0, 5).join(', ')} (${users.length} total)`
+          : users.join(', ');
+        lines.push(`  used-by: ${display}`);
+      }
+
+      // Hook deps
+      const deps = graph.getEdgesFrom(hook.id, ['uses_hook']);
+      const customDeps = deps.filter(e => !e.target.startsWith('builtin:'));
+      if (customDeps.length > 0) {
+        const depNames = customDeps
+          .map(e => (e.meta.hookName as string) ?? resolveNodeName(graph, e.target))
+          .filter(Boolean);
+        lines.push(`  deps: ${depNames.join(', ')}`);
+      }
+
+      lines.push('');
+    }
+  }
+
+  // State stores section
+  const stores = graph.getNodesByKind('Store');
+  if (stores.length > 0) {
+    lines.push('## STATE STORES');
+    for (const store of stores) {
+      const lib = store.meta.library ? `[${store.meta.library}]` : '';
+      lines.push(`${store.name}  ${lib} [${store.file}]`);
+
+      const shape = store.meta.shape as string[] | undefined;
+      if (shape && shape.length > 0) {
+        lines.push(`  shape: { ${shape.join(', ')} }`);
+      }
+
+      const writers = graph.getEdgesTo(store.id, ['writes_store']);
+      if (writers.length > 0) {
+        lines.push(`  writers: ${writers.map(e => resolveNodeName(graph, e.source)).join(', ')}`);
+      }
+
+      const readers = graph.getEdgesTo(store.id, ['reads_store']);
+      if (readers.length > 0) {
+        lines.push(`  readers: ${readers.map(e => resolveNodeName(graph, e.source)).join(', ')}`);
+      }
+
+      lines.push('');
+    }
+  }
+
+  // Context providers section
+  const contexts = graph.getNodesByKind('Context');
+  if (contexts.length > 0) {
+    lines.push('## CONTEXT PROVIDERS');
+    for (const ctx of contexts) {
+      const providers = graph.getEdgesTo(ctx.id, ['provides']);
+      const providedAt = providers.length > 0
+        ? ` provided-at: ${providers.map(e => resolveNodeName(graph, e.source)).join(', ')}`
+        : '';
+      lines.push(`${ctx.name}  [${ctx.file}]${providedAt}`);
+
+      const consumers = graph.getEdgesTo(ctx.id, ['consumes']);
+      if (consumers.length > 0) {
+        const names = consumers.map(e => resolveNodeName(graph, e.source));
+        const display = names.length > 5
+          ? `${names.slice(0, 5).join(', ')} (${names.length} total)`
+          : names.join(', ');
+        lines.push(`  consumers: ${display}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Shared modules
+  const modules = graph.getNodesByKind('Module');
+  const highFanOut = modules
+    .map(m => ({ node: m, importers: graph.getEdgesTo(m.id, ['imports']).length }))
+    .filter(m => m.importers >= 5)
+    .sort((a, b) => b.importers - a.importers);
+
+  if (highFanOut.length > 0) {
+    lines.push('## SHARED MODULES (high fan-out)');
+    for (const { node, importers } of highFanOut) {
+      lines.push(`${node.name}  [${node.file}] → ${importers} importers`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a subgraph around a specific node — tree-style rendering.
+ */
+export function formatSubgraph(graph: ReactGraph, target: string, depth: number = 2): string {
+  const node = graph.findNode(target) ?? graph.getNode(target);
+  if (!node) return `Node not found: ${target}`;
+
+  const sub = getSubgraph(graph, node.id, depth);
+  if (!sub) return `Could not build subgraph for: ${target}`;
+
+  const lines: string[] = [];
+  lines.push(`${node.name} [${node.file}:${node.line}]`);
+
+  const outgoing = graph.getEdgesFrom(node.id);
+  const byKind = groupBy(outgoing, e => e.kind);
+
+  for (const [kind, edges] of byKind) {
+    for (const edge of edges) {
+      const targetNode = graph.getNode(edge.target);
+      const targetName = targetNode ? `${targetNode.name} [${targetNode.file}]` : edge.target;
+      const metaStr = formatEdgeMeta(edge);
+      lines.push(`  ├─ ${kind} → ${targetName}${metaStr}`);
+
+      if (targetNode && depth > 1) {
+        const deeper = graph.getEdgesFrom(targetNode.id);
+        for (const d of deeper.slice(0, 5)) {
+          const dTarget = graph.getNode(d.target);
+          const dName = dTarget ? dTarget.name : d.target;
+          lines.push(`  │   └─ ${d.kind} → ${dName}`);
+        }
+        if (deeper.length > 5) {
+          lines.push(`  │   └─ ... (${deeper.length - 5} more)`);
+        }
+      }
+    }
+  }
+
+  const incoming = graph.getEdgesTo(node.id);
+  if (incoming.length > 0) {
+    lines.push(`  used-by (${incoming.length}):`);
+    const grouped = groupBy(incoming, e => e.kind);
+    for (const [kind, edges] of grouped) {
+      for (const edge of edges.slice(0, 10)) {
+        const sourceNode = graph.getNode(edge.source);
+        const sourceName = sourceNode ? `${sourceNode.name} [${sourceNode.file}]` : edge.source;
+        lines.push(`  │ ← ${kind} ← ${sourceName}`);
+      }
+      if (edges.length > 10) {
+        lines.push(`  │ ... (${edges.length - 10} more)`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format everything about a specific file.
+ */
+export function formatFileContext(graph: ReactGraph, filePath: string): string {
+  const nodes = graph.getNodesByFile(filePath);
+  if (nodes.length === 0) return `No nodes found for file: ${filePath}`;
+
+  const lines: string[] = [];
+  lines.push(`FILE: ${filePath}`);
+
+  // Exports
+  const exports = nodes.filter(n => n.exportType !== 'none');
+  if (exports.length > 0) {
+    lines.push(`EXPORTS: ${exports.map(n => `${n.name} (${n.exportType})`).join(', ')}`);
+  }
+
+  // Imports
+  const moduleNode = nodes.find(n => n.kind === 'Module');
+  if (moduleNode) {
+    const importEdges = graph.getEdgesFrom(moduleNode.id, ['imports']);
+    if (importEdges.length > 0) {
+      lines.push('IMPORTS:');
+      for (const edge of importEdges) {
+        const names = (edge.meta.names as string[]) ?? [];
+        lines.push(`  ${names.join(', ')} ← ${edge.target}`);
+      }
+    }
+  }
+
+  // Components
+  for (const comp of nodes.filter(n => n.kind === 'Component')) {
+    lines.push('');
+    lines.push(`COMPONENT: ${comp.name} (line ${comp.line})`);
+
+    const renders = graph.getEdgesFrom(comp.id, ['renders']);
+    if (renders.length > 0) {
+      lines.push(`  RENDERS: ${renders.map(e => resolveNodeName(graph, e.target)).join(', ')}`);
+    }
+
+    const hookEdges = graph.getEdgesFrom(comp.id, ['uses_hook']);
+    const customHooks = hookEdges.filter(e => !e.target.startsWith('builtin:'));
+    if (customHooks.length > 0) {
+      const hookDetails = customHooks.map(e => {
+        const name = (e.meta.hookName as string) ?? resolveNodeName(graph, e.target);
+        const destructured = e.meta.destructured as string[] | undefined;
+        return destructured ? `${name} → { ${destructured.join(', ')} }` : name;
+      });
+      lines.push(`  HOOKS: ${hookDetails.join(', ')}`);
+    }
+
+    const provides = graph.getEdgesFrom(comp.id, ['provides']);
+    const consumes = graph.getEdgesFrom(comp.id, ['consumes']);
+    if (provides.length > 0 || consumes.length > 0) {
+      const parts: string[] = [];
+      for (const e of provides) parts.push(`${resolveNodeName(graph, e.target)}(provides)`);
+      for (const e of consumes) parts.push(`${resolveNodeName(graph, e.target)}(read)`);
+      lines.push(`  CONTEXT: ${parts.join(', ')}`);
+    }
+
+    const storeReads = graph.getEdgesFrom(comp.id, ['reads_store']);
+    const storeWrites = graph.getEdgesFrom(comp.id, ['writes_store']);
+    if (storeReads.length > 0 || storeWrites.length > 0) {
+      const parts: string[] = [];
+      for (const e of storeReads) parts.push(`${resolveNodeName(graph, e.target)}(read)`);
+      for (const e of storeWrites) parts.push(`${resolveNodeName(graph, e.target)}(write)`);
+      lines.push(`  STATE: ${parts.join(', ')}`);
+    }
+
+    if (comp.props && comp.props.length > 0) {
+      lines.push(`  PROPS: ${comp.props.join(', ')}`);
+    }
+
+    const renderedBy = graph.getEdgesTo(comp.id, ['renders']);
+    if (renderedBy.length > 0) {
+      lines.push(`  RENDERED BY: ${renderedBy.map(e => resolveNodeName(graph, e.source)).join(', ')}`);
+    }
+  }
+
+  // Hooks
+  for (const hook of nodes.filter(n => n.kind === 'Hook')) {
+    lines.push('');
+    lines.push(`HOOK: ${hook.name} (line ${hook.line})`);
+    if (hook.returns) lines.push(`  RETURNS: ${hook.returns}`);
+
+    const usedBy = graph.getEdgesTo(hook.id, ['uses_hook']);
+    if (usedBy.length > 0) {
+      lines.push(`  USED BY: ${usedBy.map(e => resolveNodeName(graph, e.source)).join(', ')}`);
+    }
+
+    const effects = hook.meta.effects as any[] | undefined;
+    if (effects?.length) {
+      for (const eff of effects) {
+        const depsStr = Array.isArray(eff.deps) ? `[${eff.deps.join(', ')}]` : eff.deps;
+        lines.push(`  EFFECT: ${eff.type} deps=${depsStr}${eff.hasCleanup ? ' +cleanup' : ''}`);
+      }
+    }
+  }
+
+  // Stores
+  for (const store of nodes.filter(n => n.kind === 'Store')) {
+    lines.push('');
+    lines.push(`STORE: ${store.name} [${store.meta.library}]`);
+    const shape = store.meta.shape as string[] | undefined;
+    if (shape?.length) lines.push(`  SHAPE: { ${shape.join(', ')} }`);
+  }
+
+  // Contexts
+  for (const ctx of nodes.filter(n => n.kind === 'Context')) {
+    lines.push('');
+    lines.push(`CONTEXT: ${ctx.name}`);
+  }
+
+  // Routes
+  for (const route of nodes.filter(n => n.kind === 'Route')) {
+    lines.push('');
+    lines.push(`ROUTE: ${route.name}`);
+  }
+
+  // API Endpoints
+  for (const ep of nodes.filter(n => n.kind === 'ApiEndpoint')) {
+    lines.push('');
+    lines.push(`ENDPOINT: ${ep.name}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Trace the data flow path from node A to node B.
+ */
+export function formatTraceFlow(graph: ReactGraph, from: string, to: string): string {
+  const fromNode = graph.findNode(from) ?? graph.getNode(from);
+  const toNode = graph.findNode(to) ?? graph.getNode(to);
+
+  if (!fromNode) return `Source not found: ${from}`;
+  if (!toNode) return `Target not found: ${to}`;
+
+  // BFS to find shortest path
+  const path = findPath(graph, fromNode.id, toNode.id);
+  if (!path) return `No path found from ${fromNode.name} to ${toNode.name}`;
+
+  const lines: string[] = [];
+  lines.push(`${fromNode.name} → ${toNode.name}`);
+  lines.push('');
+
+  for (let i = 0; i < path.length; i++) {
+    const step = path[i]!;
+    const node = graph.getNode(step.nodeId);
+    const indent = '  '.repeat(i);
+    const arrow = i === 0 ? '' : `└─ ${step.edgeKind} → `;
+    const name = node ? `${node.name} [${node.file}]` : step.nodeId;
+    lines.push(`${indent}${arrow}${name}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Show impact analysis — what breaks if target changes.
+ */
+export function formatImpact(graph: ReactGraph, target: string): string {
+  const node = graph.findNode(target) ?? graph.getNode(target);
+  if (!node) return `Node not found: ${target}`;
+
+  const lines: string[] = [];
+  lines.push(`IMPACT ANALYSIS: ${node.name} [${node.file}]`);
+  lines.push('');
+
+  // Direct dependents (things that import/use this node)
+  const directEdges = graph.getEdgesTo(node.id);
+  const directByKind = groupBy(directEdges, e => e.kind);
+
+  if (directEdges.length > 0) {
+    lines.push(`DIRECT (${directEdges.length} dependents):`);
+    for (const [kind, edges] of directByKind) {
+      for (const edge of edges) {
+        const source = graph.getNode(edge.source);
+        const name = source ? `${source.name} [${source.file}]` : edge.source;
+        lines.push(`  ${kind} ← ${name}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Indirect: if this is a hook, find all components that use it,
+  // then find what renders those components
+  if (node.kind === 'Hook') {
+    const users = graph.getEdgesTo(node.id, ['uses_hook']);
+    const indirect = new Set<string>();
+
+    for (const edge of users) {
+      const userNode = graph.getNode(edge.source);
+      if (!userNode) continue;
+
+      // Who renders this component?
+      const renderers = graph.getEdgesTo(userNode.id, ['renders']);
+      for (const r of renderers) {
+        indirect.add(r.source);
+      }
+    }
+
+    if (indirect.size > 0) {
+      lines.push(`INDIRECT (via components using ${node.name}):`);
+      for (const id of indirect) {
+        const n = graph.getNode(id);
+        lines.push(`  ${n ? `${n.name} [${n.file}]` : id}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // If this is a store, find all readers and writers
+  if (node.kind === 'Store') {
+    const readers = graph.getEdgesTo(node.id, ['reads_store']);
+    const writers = graph.getEdgesTo(node.id, ['writes_store']);
+
+    if (readers.length > 0) {
+      lines.push('READERS (will see changed state shape):');
+      for (const e of readers) {
+        const n = graph.getNode(e.source);
+        lines.push(`  ${n ? `${n.name} [${n.file}]` : e.source}`);
+      }
+      lines.push('');
+    }
+    if (writers.length > 0) {
+      lines.push('WRITERS (may need signature update):');
+      for (const e of writers) {
+        const n = graph.getNode(e.source);
+        lines.push(`  ${n ? `${n.name} [${n.file}]` : e.source}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Safe to change analysis
+  if (node.kind === 'Component') {
+    const renders = graph.getEdgesFrom(node.id, ['renders']);
+    const renderedBy = graph.getEdgesTo(node.id, ['renders']);
+    lines.push('SAFE TO CHANGE:');
+    lines.push('  Internal implementation (same props + same renders = no breakage)');
+    if (node.props && node.props.length > 0) {
+      lines.push(`RISKY:`);
+      lines.push(`  Props shape — ${renderedBy.length} parents pass: ${node.props.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Query the graph with filters.
+ */
+export function formatFindNodes(graph: ReactGraph, filters: Record<string, unknown>): string {
+  // If query is provided, find a node by name and show it + all connections.
+  // This is the most common usage: "find_nodes({ query: 'useUIStore' })"
+  if (filters.query) {
+    return formatNodeQuery(graph, filters.query as string);
+  }
+
+  let results = graph.getAllNodes();
+  let hasFilter = false;
+
+  // Filter by kind
+  if (filters.kind) {
+    hasFilter = true;
+    const kind = filters.kind as string;
+    results = results.filter(n => n.kind === kind);
+  }
+
+  // Filter by name (substring match)
+  if (filters.name) {
+    hasFilter = true;
+    const name = (filters.name as string).toLowerCase();
+    results = results.filter(n => n.name.toLowerCase().includes(name));
+  }
+
+  // Filter by hook usage
+  if (filters.using_hook) {
+    hasFilter = true;
+    const hookName = filters.using_hook as string;
+    results = results.filter(n => {
+      const hookEdges = graph.getEdgesFrom(n.id, ['uses_hook']);
+      return hookEdges.some(e => {
+        const target = graph.getNode(e.target);
+        return target?.name === hookName || (e.meta.hookName as string) === hookName;
+      });
+    });
+  }
+
+  // Filter by fetches (components/hooks that make API calls)
+  if (filters.fetches) {
+    hasFilter = true;
+    results = results.filter(n => {
+      return graph.getEdgesFrom(n.id, ['fetches']).length > 0;
+    });
+  }
+
+  // Filter orphans (components rendered by nothing)
+  if (filters.orphan) {
+    hasFilter = true;
+    results = results.filter(n => {
+      if (n.kind !== 'Component') return false;
+      const renderedBy = graph.getEdgesTo(n.id, ['renders']);
+      return renderedBy.length === 0;
+    });
+  }
+
+  // Filter by store usage
+  if (filters.using_store) {
+    hasFilter = true;
+    const storeName = filters.using_store as string;
+    results = results.filter(n => {
+      const reads = graph.getEdgesFrom(n.id, ['reads_store']);
+      const writes = graph.getEdgesFrom(n.id, ['writes_store']);
+      return [...reads, ...writes].some(e => {
+        const target = graph.getNode(e.target);
+        return target?.name === storeName;
+      });
+    });
+  }
+
+  // Safety: if no recognized filter was applied, don't dump the entire graph
+  if (!hasFilter) {
+    return 'No filters provided. Use: query, name, kind, using_hook, using_store, fetches, or orphan.';
+  }
+
+  if (results.length === 0) return 'No matching nodes found.';
+
+  const lines: string[] = [];
+  lines.push(`Found ${results.length} nodes:`);
+  for (const node of results) {
+    lines.push(`  ${node.name} [${node.kind}] [${node.file}:${node.line}]`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Smart query: find a node by name and return it + all connected nodes,
+ * grouped by relationship type. This is what Claude actually needs when
+ * asking "who uses useUIStore?"
+ */
+function formatNodeQuery(graph: ReactGraph, query: string): string {
+  const node = graph.findNode(query) ?? graph.getNode(query);
+  if (!node) {
+    // Try substring match
+    const all = graph.getAllNodes();
+    const matches = all.filter(n => n.name.toLowerCase().includes(query.toLowerCase()));
+    if (matches.length === 0) return `No nodes matching "${query}".`;
+    if (matches.length > 20) {
+      return `${matches.length} nodes match "${query}". Be more specific, or use kind filter.\n` +
+        matches.slice(0, 20).map(n => `  ${n.name} [${n.kind}] [${n.file}]`).join('\n');
+    }
+    const lines = [`Found ${matches.length} nodes matching "${query}":`];
+    for (const m of matches) lines.push(`  ${m.name} [${m.kind}] [${m.file}:${m.line}]`);
+    return lines.join('\n');
+  }
+
+  const lines: string[] = [];
+  lines.push(`${node.name} [${node.kind}] [${node.file}:${node.line}]`);
+  lines.push('');
+
+  // Outgoing connections
+  const outgoing = graph.getEdgesFrom(node.id);
+  if (outgoing.length > 0) {
+    const byKind = groupBy(outgoing, e => e.kind);
+    for (const [kind, edges] of byKind) {
+      const targets = edges.map(e => {
+        const t = graph.getNode(e.target);
+        const meta = formatEdgeMeta(e);
+        return t ? `${t.name} [${t.file}]${meta}` : `${e.target}${meta}`;
+      });
+      lines.push(`${kind} → ${targets.join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  // Incoming connections (who depends on this node)
+  const incoming = graph.getEdgesTo(node.id);
+  if (incoming.length > 0) {
+    const byKind = groupBy(incoming, e => e.kind);
+    for (const [kind, edges] of byKind) {
+      const sources = edges.map(e => {
+        const s = graph.getNode(e.source);
+        return s ? `${s.name} [${s.file}]` : e.source;
+      });
+      lines.push(`${kind} ← ${sources.join(', ')}`);
+    }
+  }
+
+  if (outgoing.length === 0 && incoming.length === 0) {
+    lines.push('No connections found (isolated node).');
+  }
+
+  return lines.join('\n');
+}
+
+// ---- Path finding ----
+
+interface PathStep {
+  nodeId: string;
+  edgeKind: string;
+}
+
+function findPath(graph: ReactGraph, fromId: string, toId: string): PathStep[] | null {
+  const visited = new Set<string>();
+  const queue: { nodeId: string; path: PathStep[] }[] = [
+    { nodeId: fromId, path: [{ nodeId: fromId, edgeKind: '' }] },
+  ];
+
+  while (queue.length > 0) {
+    const { nodeId, path } = queue.shift()!;
+
+    if (nodeId === toId) return path;
+    if (visited.has(nodeId)) continue;
+    visited.add(nodeId);
+
+    // Follow outgoing edges
+    for (const edge of graph.getEdgesFrom(nodeId)) {
+      if (!visited.has(edge.target)) {
+        queue.push({
+          nodeId: edge.target,
+          path: [...path, { nodeId: edge.target, edgeKind: edge.kind }],
+        });
+      }
+    }
+  }
+
+  return null;
+}
+
+// ---- Helpers ----
+
+function resolveNodeName(graph: ReactGraph, id: string): string {
+  const node = graph.getNode(id);
+  if (node) return node.name;
+  if (id.startsWith('builtin:')) return id.slice(8);
+  if (id.startsWith('external:')) return id.slice(9);
+  if (id.startsWith('unresolved:')) return id.slice(11);
+  if (id.startsWith('endpoint:')) return id.slice(9);
+  const colonIdx = id.lastIndexOf(':');
+  if (colonIdx > 0) return id.slice(colonIdx + 1);
+  return id;
+}
+
+function formatEdgeMeta(edge: GraphEdge): string {
+  const parts: string[] = [];
+  if (edge.meta.prop) parts.push(`prop=${edge.meta.prop}`);
+  if (edge.meta.hookName) parts.push(edge.meta.hookName as string);
+  if (edge.meta.method && edge.meta.url) parts.push(`${edge.meta.method} ${edge.meta.url}`);
+  if (edge.meta.library) parts.push(edge.meta.library as string);
+  if (parts.length === 0) return '';
+  return ` (${parts.join(', ')})`;
+}
+
+function groupBy<T>(items: T[], keyFn: (item: T) => string): Map<string, T[]> {
+  const map = new Map<string, T[]>();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!map.has(key)) map.set(key, []);
+    map.get(key)!.push(item);
+  }
+  return map;
+}