@reactgraph/cli 0.1.1

package/src/mcp/server.ts

@@ -0,0 +1,59 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { loadGraph } from '../graph/serialize.js';
+import { TOOL_DEFINITIONS, handleToolCall } from './tools.js';
+
+export async function startServer(projectDir: string, liveGraph?: import('../graph/graph.js').ReactGraph): Promise<void> {
+  const graph = liveGraph ?? await loadGraph(projectDir);
+
+  if (!graph) {
+    console.error(
+      'No graph found. Run "reactgraph index" first to build the project graph.'
+    );
+    process.exit(1);
+  }
+
+  const server = new Server(
+    {
+      name: 'reactgraph',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOL_DEFINITIONS.map(t => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    })),
+  }));
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = handleToolCall(graph, name, (args ?? {}) as Record<string, unknown>);
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: result,
+        },
+      ],
+    };
+  });
+
+  // Start with stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools.ts

@@ -0,0 +1,154 @@
+import type { ReactGraph } from '../graph/graph.js';
+import { formatMap, formatSubgraph, formatFileContext, formatTraceFlow, formatImpact, formatFindNodes } from './formatter.js';
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export const TOOL_DEFINITIONS: ToolDefinition[] = [
+  {
+    name: 'get_map',
+    description: 'Get a compact overview of the entire React project: components, hooks, stores, routes, contexts, and their relationships. Call this once at session start instead of exploring files manually.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        max_components: {
+          type: 'number',
+          description: 'Maximum number of components to show (default: 30, sorted by connectivity)',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_subgraph',
+    description: 'Zoom into a specific component, hook, store, or file. Shows what it renders, what hooks it uses, who uses it, and related nodes up to the given depth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description: 'Component name, hook name, store name, or file path to zoom into',
+        },
+        depth: {
+          type: 'number',
+          description: 'How many levels of connections to show (default: 2)',
+        },
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'get_file_context',
+    description: 'Get complete context about a specific file: exports, imports, components, hooks, stores, contexts, routes, effects, and all relationships.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative file path (e.g., "src/components/Dashboard.tsx")',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'trace_flow',
+    description: 'Trace the data flow path between two nodes. Shows how data gets from component/hook A to component/hook B through renders, hooks, stores, and API calls.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: {
+          type: 'string',
+          description: 'Source node name (component, hook, or store)',
+        },
+        to: {
+          type: 'string',
+          description: 'Target node name (component, hook, store, or API endpoint)',
+        },
+      },
+      required: ['from', 'to'],
+    },
+  },
+  {
+    name: 'impact',
+    description: 'Analyze what would break if a component, hook, or store is changed. Shows direct dependents, indirect effects, and safe-to-change analysis.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description: 'Name or file path of the node to analyze',
+        },
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'find_nodes',
+    description: 'Query the graph. Use "query" to find a node by name and see all its connections (readers, writers, renderers, etc). Use other filters for bulk searches.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Find a node by name and show all its connections. Best for "who uses X?" questions. Example: "useUIStore" returns the store + all readers/writers.',
+        },
+        name: {
+          type: 'string',
+          description: 'Filter nodes by name substring match',
+        },
+        kind: {
+          type: 'string',
+          description: 'Node kind filter: Component, Hook, Store, Context, Route, ApiEndpoint',
+        },
+        using_hook: {
+          type: 'string',
+          description: 'Find nodes that use this hook (by name)',
+        },
+        using_store: {
+          type: 'string',
+          description: 'Find nodes that read/write this store (by name)',
+        },
+        fetches: {
+          type: 'boolean',
+          description: 'If true, find nodes that make API calls',
+        },
+        orphan: {
+          type: 'boolean',
+          description: 'If true, find components that are not rendered by anything',
+        },
+      },
+    },
+  },
+];
+
+export function handleToolCall(
+  graph: ReactGraph,
+  name: string,
+  args: Record<string, unknown>,
+): string {
+  switch (name) {
+    case 'get_map':
+      return formatMap(graph, (args.max_components as number) ?? 30);
+
+    case 'get_subgraph':
+      return formatSubgraph(graph, args.target as string, (args.depth as number) ?? 2);
+
+    case 'get_file_context':
+      return formatFileContext(graph, args.path as string);
+
+    case 'trace_flow':
+      return formatTraceFlow(graph, args.from as string, args.to as string);
+
+    case 'impact':
+      return formatImpact(graph, args.target as string);
+
+    case 'find_nodes':
+      return formatFindNodes(graph, args);
+
+    default:
+      return `Unknown tool: ${name}`;
+  }
+}

package/src/output/ai-context.ts

@@ -0,0 +1,29 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ReactGraph } from '../graph/graph.js';
+import { formatMap } from '../mcp/formatter.js';
+
+/**
+ * Generate .reactgraph/ai-context.md — the zero-setup flat file fallback.
+ * Claude can read this file directly without MCP configured.
+ */
+export async function generateAIContext(graph: ReactGraph, projectDir: string): Promise<void> {
+  const map = formatMap(graph);
+  const stats = graph.stats();
+
+  const content = `# ReactGraph AI Context
+# Auto-generated — do not edit. Re-generate with: reactgraph index
+# Add to CLAUDE.md: "Read .reactgraph/ai-context.md at session start"
+
+${map}
+
+---
+# To get more detail on any node, use the ReactGraph MCP server:
+#   reactgraph.get_subgraph("ComponentName")
+#   reactgraph.get_file_context("src/path/to/file.tsx")
+`;
+
+  const dir = join(projectDir, '.reactgraph');
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'ai-context.md'), content);
+}

package/src/parser/extractors/api-calls.ts

@@ -0,0 +1,192 @@
+import type Parser from 'tree-sitter';
+import type { GraphNode, GraphEdge } from '../../graph/schema.js';
+import { nodeId, findAll, findEnclosingFunction } from './types.js';
+import type { ExtractionResult } from './types.js';
+
+/**
+ * API call extractor — detects fetch, axios, and API wrapper calls.
+ *
+ * Patterns:
+ *   fetch('/api/users')
+ *   fetch('/api/users', { method: 'POST' })
+ *   axios.get('/api/users')
+ *   api.get('/api/users')
+ *   api('/api/users', { method: 'POST' })
+ */
+export function extractApiCalls(
+  tree: Parser.Tree,
+  filePath: string,
+  sourceCode: string,
+  existingNodes: GraphNode[],
+): ExtractionResult {
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+  const root = tree.rootNode;
+
+  // Build function map for edge sources
+  const functionNodes = new Map<string, GraphNode>();
+  for (const n of existingNodes) {
+    if (n.file === filePath && (n.kind === 'Component' || n.kind === 'Hook')) {
+      functionNodes.set(n.name, n);
+    }
+  }
+
+  const callExprs = findAll(root, 'call_expression');
+
+  for (const call of callExprs) {
+    const callee = call.childForFieldName('function');
+    if (!callee) continue;
+
+    const apiCall = detectApiCall(callee, call);
+    if (!apiCall) continue;
+
+    // Find enclosing function
+    const enclosingFn = findEnclosingFunction(call);
+    if (!enclosingFn) continue;
+    const enclosingName = getFunctionName(enclosingFn);
+    if (!enclosingName) continue;
+    const enclosingNode = functionNodes.get(enclosingName);
+    if (!enclosingNode) continue;
+
+    // Create or reference an ApiEndpoint node
+    const endpointId = `endpoint:${apiCall.method}:${apiCall.url}`;
+
+    edges.push({
+      source: enclosingNode.id,
+      target: endpointId,
+      kind: 'fetches',
+      meta: {
+        method: apiCall.method,
+        url: apiCall.url,
+        caller: apiCall.caller,
+      },
+    });
+  }
+
+  return { nodes, edges };
+}
+
+interface ApiCallInfo {
+  method: string;
+  url: string;
+  caller: string; // 'fetch' | 'axios' | 'api' | etc.
+}
+
+function detectApiCall(
+  callee: Parser.SyntaxNode,
+  call: Parser.SyntaxNode,
+): ApiCallInfo | null {
+  const args = call.childForFieldName('arguments');
+  if (!args) return null;
+
+  // Pattern 1: fetch('/api/users') or fetch('/api/users', { method: 'POST' })
+  if (callee.type === 'identifier' && callee.text === 'fetch') {
+    const url = extractStringArg(args, 0);
+    if (!url || !looksLikeApiUrl(url)) return null;
+    const method = extractMethodFromOptions(args) ?? 'GET';
+    return { method, url, caller: 'fetch' };
+  }
+
+  // Pattern 2: axios.get('/api/users'), axios.post(...)
+  if (callee.type === 'member_expression') {
+    const obj = callee.childForFieldName('object');
+    const prop = callee.childForFieldName('property');
+    if (!obj || !prop) return null;
+
+    const objName = obj.text;
+    const methodName = prop.text;
+
+    // axios.get, axios.post, etc.
+    const httpMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+    if (httpMethods.includes(methodName)) {
+      const url = extractStringArg(args, 0);
+      if (!url) return null;
+
+      // Accept axios, api, apiClient, http, client, etc.
+      const knownCallers = ['axios', 'api', 'apiClient', 'http', 'client', 'fetcher'];
+      if (knownCallers.includes(objName) || objName.toLowerCase().includes('api') || objName.toLowerCase().includes('client')) {
+        return { method: methodName.toUpperCase(), url, caller: objName };
+      }
+    }
+  }
+
+  // Pattern 3: api('/api/users') — direct function call with URL string
+  if (callee.type === 'identifier') {
+    const name = callee.text;
+    const knownWrappers = ['api', 'apiClient', 'fetcher', 'request', 'http'];
+    if (knownWrappers.includes(name)) {
+      const url = extractStringArg(args, 0);
+      if (!url || !looksLikeApiUrl(url)) return null;
+      const method = extractMethodFromOptions(args) ?? 'GET';
+      return { method, url, caller: name };
+    }
+  }
+
+  return null;
+}
+
+function extractStringArg(args: Parser.SyntaxNode, index: number): string | null {
+  // args children: ( arg0, arg1, ... )
+  // Skip punctuation nodes
+  let argIndex = 0;
+  for (let i = 0; i < args.childCount; i++) {
+    const child = args.child(i)!;
+    if (child.type === '(' || child.type === ')' || child.type === ',') continue;
+    if (argIndex === index) {
+      if (child.type === 'string') {
+        return child.text.replace(/^['"`]|['"`]$/g, '');
+      }
+      // Template literal: `${base}/api/users`
+      if (child.type === 'template_string') {
+        return child.text.replace(/^`|`$/g, '');
+      }
+      return null;
+    }
+    argIndex++;
+  }
+  return null;
+}
+
+function extractMethodFromOptions(args: Parser.SyntaxNode): string | null {
+  // Look for second argument that's an object with { method: 'POST' }
+  let argIndex = 0;
+  for (let i = 0; i < args.childCount; i++) {
+    const child = args.child(i)!;
+    if (child.type === '(' || child.type === ')' || child.type === ',') continue;
+    if (argIndex === 1 && child.type === 'object') {
+      // Find method property
+      for (let j = 0; j < child.childCount; j++) {
+        const prop = child.child(j)!;
+        if (prop.type === 'pair') {
+          const key = prop.childForFieldName('key');
+          const value = prop.childForFieldName('value');
+          if (key?.text === 'method' && value) {
+            return value.text.replace(/^['"`]|['"`]$/g, '').toUpperCase();
+          }
+        }
+      }
+    }
+    argIndex++;
+  }
+  return null;
+}
+
+function looksLikeApiUrl(url: string): boolean {
+  return url.startsWith('/api') ||
+    url.startsWith('http') ||
+    url.startsWith('/v1') ||
+    url.startsWith('/v2') ||
+    url.includes('/api/');
+}
+
+function getFunctionName(node: Parser.SyntaxNode): string | null {
+  const nameField = node.childForFieldName('name');
+  if (nameField) return nameField.text;
+  if (node.type === 'arrow_function' || node.type === 'function_expression') {
+    const parent = node.parent;
+    if (parent?.type === 'variable_declarator') {
+      return parent.childForFieldName('name')?.text ?? null;
+    }
+  }
+  return null;
+}

package/src/parser/extractors/components.ts

@@ -0,0 +1,273 @@
+import type Parser from 'tree-sitter';
+import type { GraphNode, GraphEdge } from '../../graph/schema.js';
+import { nodeId, isPascalCase, findAll, findFirst } from './types.js';
+import type { ExtractionResult } from './types.js';
+
+export function extractComponents(
+  tree: Parser.Tree,
+  filePath: string,
+  sourceCode: string,
+  _existingNodes: GraphNode[],
+): ExtractionResult {
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+  const root = tree.rootNode;
+
+  for (let i = 0; i < root.childCount; i++) {
+    const child = root.child(i)!;
+    const component = detectComponent(child, filePath);
+    if (component) nodes.push(component);
+  }
+
+  return { nodes, edges };
+}
+
+function detectComponent(node: Parser.SyntaxNode, filePath: string): GraphNode | null {
+  // Pattern A: function_declaration
+  if (node.type === 'function_declaration') {
+    return tryFunctionComponent(node, filePath, 'none');
+  }
+
+  // Pattern: export_statement wrapping a declaration
+  if (node.type === 'export_statement') {
+    const isDefault = node.text.startsWith('export default');
+    const exportType = isDefault ? 'default' : 'named';
+
+    // export function Foo() { ... }
+    const funcDecl = findDirectChild(node, 'function_declaration');
+    if (funcDecl) return tryFunctionComponent(funcDecl, filePath, exportType);
+
+    // export const Foo = ...
+    const lexDecl = findDirectChild(node, 'lexical_declaration');
+    if (lexDecl) return tryLexicalComponent(lexDecl, filePath, exportType);
+
+    // export default function() { ... } (anonymous)
+    const funcExpr = findDirectChild(node, 'function');
+    if (funcExpr) return tryFunctionComponent(funcExpr, filePath, exportType);
+
+    // export class Foo extends Component { ... }
+    const classDecl = findDirectChild(node, 'class_declaration');
+    if (classDecl) return tryClassComponent(classDecl, filePath, exportType);
+
+    return null;
+  }
+
+  // Pattern B: const Foo = () => ...
+  if (node.type === 'lexical_declaration') {
+    return tryLexicalComponent(node, filePath, 'none');
+  }
+
+  // Pattern D: class Foo extends Component
+  if (node.type === 'class_declaration') {
+    return tryClassComponent(node, filePath, 'none');
+  }
+
+  return null;
+}
+
+function tryFunctionComponent(
+  node: Parser.SyntaxNode,
+  filePath: string,
+  exportType: 'default' | 'named' | 'none',
+): GraphNode | null {
+  const nameNode = node.childForFieldName('name');
+  const name = nameNode?.text;
+  if (!name || !isPascalCase(name)) return null;
+
+  const body = node.childForFieldName('body');
+  if (!body || !containsJSX(body)) return null;
+
+  return {
+    id: nodeId(filePath, name),
+    kind: 'Component',
+    name,
+    file: filePath,
+    line: node.startPosition.row + 1,
+    exportType,
+    props: extractProps(node),
+    meta: {},
+  };
+}
+
+function tryLexicalComponent(
+  node: Parser.SyntaxNode,
+  filePath: string,
+  exportType: 'default' | 'named' | 'none',
+): GraphNode | null {
+  const declarator = findDirectChild(node, 'variable_declarator');
+  if (!declarator) return null;
+
+  const nameNode = declarator.childForFieldName('name');
+  const name = nameNode?.text;
+  if (!name || !isPascalCase(name)) return null;
+
+  const value = declarator.childForFieldName('value');
+  if (!value) return null;
+
+  // Direct arrow function: const Foo = () => <div/>
+  if (value.type === 'arrow_function' || value.type === 'function_expression') {
+    const body = value.childForFieldName('body');
+    if (!body) return null;
+    if (!containsJSX(body) && !isJSX(body)) return null;
+
+    return {
+      id: nodeId(filePath, name),
+      kind: 'Component',
+      name,
+      file: filePath,
+      line: node.startPosition.row + 1,
+      exportType,
+      props: extractPropsFromArrow(value),
+      meta: {},
+    };
+  }
+
+  // Wrapped: const Foo = React.memo(() => ...) or memo(() => ...)
+  if (value.type === 'call_expression') {
+    const wrapper = getWrapperName(value);
+    if (wrapper) {
+      const innerFn = findInnerFunction(value);
+      if (innerFn) {
+        const body = innerFn.childForFieldName('body');
+        if (body && (containsJSX(body) || isJSX(body))) {
+          return {
+            id: nodeId(filePath, name),
+            kind: 'Component',
+            name,
+            file: filePath,
+            line: node.startPosition.row + 1,
+            exportType,
+            props: extractPropsFromArrow(innerFn),
+            meta: { wrapped: wrapper },
+          };
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+function tryClassComponent(
+  node: Parser.SyntaxNode,
+  filePath: string,
+  exportType: 'default' | 'named' | 'none',
+): GraphNode | null {
+  const nameNode = node.childForFieldName('name');
+  const name = nameNode?.text;
+  if (!name || !isPascalCase(name)) return null;
+
+  // Check extends React.Component or Component
+  const heritage = findDirectChild(node, 'class_heritage');
+  if (!heritage) return null;
+
+  const extendsText = heritage.text;
+  if (!extendsText.includes('Component') && !extendsText.includes('PureComponent')) return null;
+
+  // Check render() method has JSX
+  const body = node.childForFieldName('body');
+  if (!body) return null;
+
+  const renderMethod = findAll(body, 'method_definition').find(m => {
+    const n = m.childForFieldName('name');
+    return n?.text === 'render';
+  });
+
+  if (!renderMethod || !containsJSX(renderMethod)) return null;
+
+  return {
+    id: nodeId(filePath, name),
+    kind: 'Component',
+    name,
+    file: filePath,
+    line: node.startPosition.row + 1,
+    exportType,
+    props: [],
+    meta: { isClass: true },
+  };
+}
+
+function containsJSX(node: Parser.SyntaxNode): boolean {
+  if (isJSX(node)) return true;
+  for (let i = 0; i < node.childCount; i++) {
+    if (containsJSX(node.child(i)!)) return true;
+  }
+  return false;
+}
+
+function isJSX(node: Parser.SyntaxNode): boolean {
+  return (
+    node.type === 'jsx_element' ||
+    node.type === 'jsx_self_closing_element' ||
+    node.type === 'jsx_fragment'
+  );
+}
+
+function extractProps(funcNode: Parser.SyntaxNode): string[] {
+  const params = funcNode.childForFieldName('parameters');
+  if (!params || params.childCount === 0) return [];
+  return extractParamProps(params);
+}
+
+function extractPropsFromArrow(arrowNode: Parser.SyntaxNode): string[] {
+  const params = arrowNode.childForFieldName('parameters');
+  if (!params) return [];
+  return extractParamProps(params);
+}
+
+function extractParamProps(params: Parser.SyntaxNode): string[] {
+  // Look for destructured first param: ({ a, b, c })
+  for (let i = 0; i < params.childCount; i++) {
+    const param = params.child(i)!;
+    // required_parameter or just object_pattern
+    const objPattern =
+      param.type === 'object_pattern'
+        ? param
+        : findDirectChild(param, 'object_pattern');
+
+    if (objPattern) {
+      const props: string[] = [];
+      for (let j = 0; j < objPattern.childCount; j++) {
+        const child = objPattern.child(j)!;
+        if (child.type === 'shorthand_property_identifier_pattern' || child.type === 'shorthand_property_identifier') {
+          props.push(child.text);
+        } else if (child.type === 'pair_pattern') {
+          const key = child.childForFieldName('key');
+          if (key) props.push(key.text);
+        }
+      }
+      return props;
+    }
+  }
+
+  return [];
+}
+
+function getWrapperName(callNode: Parser.SyntaxNode): string | null {
+  const fn = callNode.childForFieldName('function');
+  if (!fn) return null;
+
+  const WRAPPERS = ['memo', 'React.memo', 'forwardRef', 'React.forwardRef'];
+  if (WRAPPERS.includes(fn.text)) return fn.text;
+  return null;
+}
+
+function findInnerFunction(callNode: Parser.SyntaxNode): Parser.SyntaxNode | null {
+  const args = callNode.childForFieldName('arguments');
+  if (!args) return null;
+
+  for (let i = 0; i < args.childCount; i++) {
+    const child = args.child(i)!;
+    if (child.type === 'arrow_function' || child.type === 'function_expression') {
+      return child;
+    }
+  }
+  return null;
+}
+
+function findDirectChild(node: Parser.SyntaxNode, type: string): Parser.SyntaxNode | null {
+  for (let i = 0; i < node.childCount; i++) {
+    if (node.child(i)!.type === type) return node.child(i)!;
+  }
+  return null;
+}