@reactgraph/cli 0.1.1

package/src/parser/pipeline.ts

@@ -0,0 +1,89 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { GraphNode, GraphEdge } from '../graph/schema.js';
+import { parseFile } from './setup.js';
+import { extractImports } from './extractors/imports.js';
+import { extractComponents } from './extractors/components.js';
+import { extractHooks } from './extractors/hooks.js';
+import { extractJSXTree } from './extractors/jsx-tree.js';
+import { extractContext } from './extractors/context.js';
+import { extractState } from './extractors/state.js';
+import { extractApiCalls } from './extractors/api-calls.js';
+import { extractRoutes } from './extractors/routes.js';
+import { extractEffects } from './extractors/effects.js';
+import type { ExtractionResult } from './extractors/types.js';
+
+export interface PipelineResult {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  filePath: string;
+}
+
+/**
+ * Run all extractors on a single file in order.
+ *
+ * @param globalNodes - Nodes from ALL previously-processed files.
+ *   Cross-file extractors (state, context, hooks, jsx-tree) use this
+ *   to resolve references to stores, contexts, and components defined
+ *   in other files.
+ */
+export async function processFile(
+  relativePath: string,
+  projectDir: string,
+  globalNodes: GraphNode[] = [],
+): Promise<PipelineResult> {
+  const absolutePath = resolve(projectDir, relativePath);
+  const sourceCode = await readFile(absolutePath, 'utf-8');
+  const tree = parseFile(relativePath, sourceCode);
+
+  if (!tree) {
+    return { nodes: [], edges: [], filePath: relativePath };
+  }
+
+  // allNodes = this file's nodes as they accumulate through extractors
+  const allNodes: GraphNode[] = [];
+  const allEdges: GraphEdge[] = [];
+
+  // visibleNodes = this file's nodes + global nodes from other files
+  // Extractors see both when resolving cross-file references
+  function visibleNodes(): GraphNode[] {
+    return [...globalNodes, ...allNodes];
+  }
+
+  function run(extractor: (tree: any, fp: string, src: string, nodes: GraphNode[]) => ExtractionResult) {
+    const result = extractor(tree, relativePath, sourceCode, visibleNodes());
+    allNodes.push(...result.nodes);
+    allEdges.push(...result.edges);
+  }
+
+  // 1. Imports (creates Module nodes + import edges)
+  const importResult = extractImports(tree, relativePath, sourceCode, visibleNodes(), projectDir);
+  allNodes.push(...importResult.nodes);
+  allEdges.push(...importResult.edges);
+
+  // 2. Components
+  run(extractComponents);
+
+  // 3. Hooks
+  run(extractHooks);
+
+  // 4. JSX render tree
+  run(extractJSXTree);
+
+  // 5. Context (needs components/hooks for edge sources)
+  run(extractContext);
+
+  // 6. State management (needs components/hooks + cross-file stores)
+  run(extractState);
+
+  // 7. API calls (needs components/hooks for edge sources)
+  run(extractApiCalls);
+
+  // 8. Routes (needs components for linking)
+  run(extractRoutes);
+
+  // 9. Effects (annotates existing nodes — must run last)
+  run(extractEffects);
+
+  return { nodes: allNodes, edges: allEdges, filePath: relativePath };
+}

package/src/parser/setup.ts

@@ -0,0 +1,33 @@
+import Parser from 'tree-sitter';
+// @ts-expect-error no declaration file for tree-sitter grammars
+import TypeScript from 'tree-sitter-typescript/typescript';
+// @ts-expect-error no declaration file for tree-sitter grammars
+import TSX from 'tree-sitter-typescript/tsx';
+import JavaScript from 'tree-sitter-javascript';
+
+const tsParser = new Parser();
+tsParser.setLanguage(TypeScript);
+
+const tsxParser = new Parser();
+tsxParser.setLanguage(TSX);
+
+const jsParser = new Parser();
+jsParser.setLanguage(JavaScript as unknown as Parser.Language);
+
+const EXT_MAP: Record<string, Parser> = {
+  '.ts': tsParser,
+  '.tsx': tsxParser,
+  '.js': jsParser,
+  '.jsx': tsxParser, // JSX uses TSX grammar
+};
+
+export function getParser(filePath: string): Parser | null {
+  const ext = filePath.slice(filePath.lastIndexOf('.'));
+  return EXT_MAP[ext] ?? null;
+}
+
+export function parseFile(filePath: string, sourceCode: string): Parser.Tree | null {
+  const parser = getParser(filePath);
+  if (!parser) return null;
+  return parser.parse(sourceCode);
+}

package/src/parser/walker.ts

@@ -0,0 +1,61 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ignore, { type Ignore } from 'ignore';
+
+const ALWAYS_SKIP = new Set(['node_modules', '.next', 'dist', 'build', '.reactgraph', '.git']);
+const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+
+export interface WalkedFile {
+  absolutePath: string;
+  relativePath: string;
+}
+
+export async function walkProject(
+  projectDir: string,
+  extraExclude: string[] = [],
+): Promise<WalkedFile[]> {
+  const ig = await loadGitignore(projectDir);
+  for (const pat of extraExclude) ig.add(pat);
+
+  const files: WalkedFile[] = [];
+  await walk(projectDir, projectDir, ig, files);
+  return files;
+}
+
+async function loadGitignore(projectDir: string): Promise<Ignore> {
+  const ig = ignore();
+  try {
+    const content = await readFile(join(projectDir, '.gitignore'), 'utf-8');
+    ig.add(content);
+  } catch {
+    // no .gitignore, that's fine
+  }
+  return ig;
+}
+
+async function walk(
+  dir: string,
+  projectDir: string,
+  ig: Ignore,
+  files: WalkedFile[],
+): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (ALWAYS_SKIP.has(entry.name)) continue;
+
+    const abs = join(dir, entry.name);
+    const rel = relative(projectDir, abs);
+
+    if (ig.ignores(rel)) continue;
+
+    if (entry.isDirectory()) {
+      await walk(abs, projectDir, ig, files);
+    } else if (entry.isFile()) {
+      const ext = entry.name.slice(entry.name.lastIndexOf('.'));
+      if (EXTENSIONS.has(ext)) {
+        files.push({ absolutePath: abs, relativePath: rel });
+      }
+    }
+  }
+}

package/src/watcher.ts

@@ -0,0 +1,91 @@
+import { watch } from 'chokidar';
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { relative } from 'node:path';
+import { ReactGraph } from './graph/graph.js';
+import { saveGraph } from './graph/serialize.js';
+import { processFile } from './parser/pipeline.js';
+import { generateAIContext } from './output/ai-context.js';
+
+const EXTENSIONS = /\.(tsx?|jsx?)$/;
+const IGNORE = ['**/node_modules/**', '**/.next/**', '**/dist/**', '**/build/**', '**/.reactgraph/**'];
+
+export interface WatcherOptions {
+  projectDir: string;
+  graph: ReactGraph;
+  onUpdate?: (file: string, stats: { nodes: number; edges: number }) => void;
+  onError?: (file: string, error: Error) => void;
+}
+
+export function startWatcher(opts: WatcherOptions): () => void {
+  const { projectDir, graph, onUpdate, onError } = opts;
+  const fileHashes = new Map<string, string>();
+
+  // Initialize hashes for current graph files
+  // (We'll compute them on first change detection)
+
+  const watcher = watch(projectDir, {
+    ignored: IGNORE,
+    ignoreInitial: true,
+    persistent: true,
+  });
+
+  const handleChange = async (absPath: string) => {
+    if (!EXTENSIONS.test(absPath)) return;
+
+    const relPath = relative(projectDir, absPath).replace(/\\/g, '/');
+
+    try {
+      const content = await readFile(absPath, 'utf-8');
+      const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+
+      // Skip if unchanged
+      if (fileHashes.get(relPath) === hash) return;
+      fileHashes.set(relPath, hash);
+
+      // Remove old nodes/edges for this file
+      graph.removeNodesByFile(relPath);
+
+      // Re-process file
+      const result = await processFile(relPath, projectDir);
+      for (const node of result.nodes) graph.addNode(node);
+      for (const edge of result.edges) graph.addEdge(edge);
+
+      // Persist
+      await saveGraph(graph, projectDir);
+      await generateAIContext(graph, projectDir);
+
+      onUpdate?.(relPath, {
+        nodes: graph.stats().totalNodes,
+        edges: graph.stats().totalEdges,
+      });
+    } catch (err) {
+      onError?.(relPath, err as Error);
+    }
+  };
+
+  const handleDelete = async (absPath: string) => {
+    if (!EXTENSIONS.test(absPath)) return;
+
+    const relPath = relative(projectDir, absPath).replace(/\\/g, '/');
+    graph.removeNodesByFile(relPath);
+    fileHashes.delete(relPath);
+
+    await saveGraph(graph, projectDir);
+    await generateAIContext(graph, projectDir);
+
+    onUpdate?.(relPath, {
+      nodes: graph.stats().totalNodes,
+      edges: graph.stats().totalEdges,
+    });
+  };
+
+  watcher.on('change', handleChange);
+  watcher.on('add', handleChange);
+  watcher.on('unlink', handleDelete);
+
+  // Return cleanup function
+  return () => {
+    watcher.close();
+  };
+}

package/templates/CLAUDE.md

@@ -0,0 +1,7 @@
+## Navigation Rules (ReactGraph)
+
+- ALWAYS call reactgraph.get_map() at session start instead of exploring files
+- Use reactgraph.get_subgraph(name) before modifying any component or hook
+- Use reactgraph.get_file_context(path) for detailed file info before editing
+- Do NOT use grep/find/glob to discover project structure — the graph has it
+- If ReactGraph MCP is not available, read .reactgraph/ai-context.md instead

package/tests/extractors.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import { parseFile } from '../src/parser/setup.js';
+import { extractComponents } from '../src/parser/extractors/components.js';
+import { extractHooks } from '../src/parser/extractors/hooks.js';
+import { extractJSXTree } from '../src/parser/extractors/jsx-tree.js';
+
+describe('Component extractor', () => {
+  it('detects function declaration component', () => {
+    const code = `
+      function Dashboard() {
+        return <div>Hello</div>;
+      }
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const { nodes } = extractComponents(tree, 'test.tsx', code, []);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]!.name).toBe('Dashboard');
+    expect(nodes[0]!.kind).toBe('Component');
+  });
+
+  it('detects arrow function component', () => {
+    const code = `
+      const Card = ({ title, value }: Props) => {
+        return <div>{title}: {value}</div>;
+      };
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const { nodes } = extractComponents(tree, 'test.tsx', code, []);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]!.name).toBe('Card');
+    expect(nodes[0]!.props).toContain('title');
+    expect(nodes[0]!.props).toContain('value');
+  });
+
+  it('detects memo-wrapped component', () => {
+    const code = `
+      const Card = React.memo(({ title }: Props) => {
+        return <div>{title}</div>;
+      });
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const { nodes } = extractComponents(tree, 'test.tsx', code, []);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]!.name).toBe('Card');
+    expect(nodes[0]!.meta.wrapped).toBe('React.memo');
+  });
+
+  it('detects exported component', () => {
+    const code = `
+      export function Header() {
+        return <header>Logo</header>;
+      }
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const { nodes } = extractComponents(tree, 'test.tsx', code, []);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]!.exportType).toBe('named');
+  });
+
+  it('ignores non-component functions', () => {
+    const code = `
+      function formatDate(date: Date) {
+        return date.toISOString();
+      }
+      const helper = () => 42;
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const { nodes } = extractComponents(tree, 'test.tsx', code, []);
+    expect(nodes).toHaveLength(0);
+  });
+});
+
+describe('Hook extractor', () => {
+  it('detects custom hook definition', () => {
+    const code = `
+      function useCounter() {
+        const [count, setCount] = useState(0);
+        return { count, increment: () => setCount(c => c + 1) };
+      }
+    `;
+    const tree = parseFile('test.ts', code)!;
+    const { nodes } = extractHooks(tree, 'test.ts', code, []);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]!.name).toBe('useCounter');
+    expect(nodes[0]!.kind).toBe('Hook');
+  });
+
+  it('detects hook usage in component', () => {
+    const code = `
+      function Dashboard() {
+        const { data } = useQuery();
+        return <div>{data}</div>;
+      }
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    // Provide the Dashboard component node so the hook extractor can find it
+    const existingNodes = [{
+      id: 'test.tsx:Dashboard',
+      kind: 'Component' as const,
+      name: 'Dashboard',
+      file: 'test.tsx',
+      line: 2,
+      exportType: 'none' as const,
+      meta: {},
+    }];
+    const { edges } = extractHooks(tree, 'test.tsx', code, existingNodes);
+    const hookEdge = edges.find(e => e.kind === 'uses_hook');
+    expect(hookEdge).toBeDefined();
+    expect(hookEdge!.source).toBe('test.tsx:Dashboard');
+  });
+});
+
+describe('JSX tree extractor', () => {
+  it('detects rendered components', () => {
+    const code = `
+      function App() {
+        return (
+          <div>
+            <Header />
+            <Sidebar isOpen={true} />
+          </div>
+        );
+      }
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const existingNodes = [{
+      id: 'test.tsx:App',
+      kind: 'Component' as const,
+      name: 'App',
+      file: 'test.tsx',
+      line: 2,
+      exportType: 'none' as const,
+      meta: {},
+    }];
+    const { edges } = extractJSXTree(tree, 'test.tsx', code, existingNodes);
+
+    const rendersEdges = edges.filter(e => e.kind === 'renders');
+    expect(rendersEdges).toHaveLength(2);
+
+    const propEdges = edges.filter(e => e.kind === 'passes_prop');
+    expect(propEdges.length).toBeGreaterThanOrEqual(1);
+    expect(propEdges.some(e => (e.meta.prop as string) === 'isOpen')).toBe(true);
+  });
+
+  it('ignores HTML elements', () => {
+    const code = `
+      function App() {
+        return <div><span>text</span></div>;
+      }
+    `;
+    const tree = parseFile('test.tsx', code)!;
+    const existingNodes = [{
+      id: 'test.tsx:App',
+      kind: 'Component' as const,
+      name: 'App',
+      file: 'test.tsx',
+      line: 2,
+      exportType: 'none' as const,
+      meta: {},
+    }];
+    const { edges } = extractJSXTree(tree, 'test.tsx', code, existingNodes);
+    expect(edges.filter(e => e.kind === 'renders')).toHaveLength(0);
+  });
+});

package/tests/fixtures/basic/src/App.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import Dashboard from './components/Dashboard';
+import Sidebar from './components/Sidebar';
+
+export default function App() {
+  return (
+    <div>
+      <Sidebar isOpen={true} onClose={() => {}} />
+      <Dashboard />
+    </div>
+  );
+}

package/tests/fixtures/basic/src/components/Dashboard.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { useAuth } from '../hooks/useAuth';
+import { useAuthStore } from '../stores/authStore';
+import MetricsCard from './MetricsCard';
+
+export default function Dashboard() {
+  const { user, isLoading } = useAuth();
+  const token = useAuthStore((s) => s.token);
+  const items = [
+    { id: 1, title: 'Revenue', value: 1000 },
+    { id: 2, title: 'Users', value: 500 },
+  ];
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user?.name}</h1>
+      {items.map(item => (
+        <MetricsCard key={item.id} title={item.title} value={item.value} />
+      ))}
+    </div>
+  );
+}

package/tests/fixtures/basic/src/components/MetricsCard.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+
+interface MetricsCardProps {
+  title: string;
+  value: number;
+}
+
+export default function MetricsCard({ title, value }: MetricsCardProps) {
+  return (
+    <div>
+      <h3>{title}</h3>
+      <span>{value}</span>
+    </div>
+  );
+}

package/tests/fixtures/basic/src/components/Sidebar.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { useAuth } from '../hooks/useAuth';
+
+interface SidebarProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export default function Sidebar({ isOpen, onClose }: SidebarProps) {
+  const { user } = useAuth();
+
+  if (!isOpen) return null;
+
+  return (
+    <nav>
+      <div>{user?.name}</div>
+      <button onClick={onClose}>Close</button>
+    </nav>
+  );
+}

package/tests/fixtures/basic/src/contexts/ThemeContext.tsx

@@ -0,0 +1,16 @@
+import React, { createContext, useContext, useState } from 'react';
+
+export const ThemeContext = createContext('light');
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState('light');
+  return (
+    <ThemeContext.Provider value={theme}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  return useContext(ThemeContext);
+}

package/tests/fixtures/basic/src/hooks/useAuth.ts

@@ -0,0 +1,25 @@
+import { useState, useEffect } from 'react';
+
+export function useAuth() {
+  const [user, setUser] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/auth/me')
+      .then(res => res.json())
+      .then(data => {
+        setUser(data);
+        setIsLoading(false);
+      });
+  }, []);
+
+  const login = (email: string, password: string) => {
+    // login logic
+  };
+
+  const logout = () => {
+    setUser(null);
+  };
+
+  return { user, isLoading, login, logout };
+}

package/tests/fixtures/basic/src/stores/authStore.ts

@@ -0,0 +1,15 @@
+import { create } from 'zustand';
+
+interface AuthState {
+  user: { name: string } | null;
+  token: string | null;
+  login: (user: { name: string }, token: string) => void;
+  logout: () => void;
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  token: null,
+  login: (user, token) => set({ user, token }),
+  logout: () => set({ user: null, token: null }),
+}));

package/tests/fixtures/basic/src/utils.ts

@@ -0,0 +1,7 @@
+export function formatDate(date: Date): string {
+  return date.toLocaleDateString();
+}
+
+export function cn(...classes: string[]): string {
+  return classes.filter(Boolean).join(' ');
+}

package/tests/graph.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { ReactGraph } from '../src/graph/graph.js';
+import type { GraphNode, GraphEdge } from '../src/graph/schema.js';
+
+function makeNode(overrides: Partial<GraphNode> = {}): GraphNode {
+  return {
+    id: 'test:Node',
+    kind: 'Component',
+    name: 'Node',
+    file: 'src/Node.tsx',
+    line: 1,
+    exportType: 'default',
+    meta: {},
+    ...overrides,
+  };
+}
+
+describe('ReactGraph', () => {
+  it('adds and retrieves nodes', () => {
+    const g = new ReactGraph();
+    const node = makeNode();
+    g.addNode(node);
+
+    expect(g.getNode('test:Node')).toBe(node);
+    expect(g.getNodesByKind('Component')).toHaveLength(1);
+    expect(g.getNodesByFile('src/Node.tsx')).toHaveLength(1);
+    expect(g.getNodesByName('Node')).toHaveLength(1);
+  });
+
+  it('adds and retrieves edges', () => {
+    const g = new ReactGraph();
+    g.addNode(makeNode({ id: 'a', name: 'A' }));
+    g.addNode(makeNode({ id: 'b', name: 'B' }));
+    g.addEdge({ source: 'a', target: 'b', kind: 'renders', meta: {} });
+
+    expect(g.getEdgesFrom('a')).toHaveLength(1);
+    expect(g.getEdgesTo('b')).toHaveLength(1);
+    expect(g.getEdgesByKind('renders')).toHaveLength(1);
+  });
+
+  it('removes nodes by file', () => {
+    const g = new ReactGraph();
+    g.addNode(makeNode({ id: 'a', name: 'A', file: 'f1.tsx' }));
+    g.addNode(makeNode({ id: 'b', name: 'B', file: 'f2.tsx' }));
+    g.addEdge({ source: 'a', target: 'b', kind: 'renders', meta: {} });
+
+    g.removeNodesByFile('f1.tsx');
+
+    expect(g.getNode('a')).toBeUndefined();
+    expect(g.getNode('b')).toBeDefined();
+    expect(g.getEdgesFrom('a')).toHaveLength(0);
+    expect(g.getEdgesTo('b')).toHaveLength(0);
+  });
+
+  it('finds nodes with fuzzy matching', () => {
+    const g = new ReactGraph();
+    g.addNode(makeNode({ id: 'a', name: 'Dashboard' }));
+
+    expect(g.findNode('Dashboard')?.id).toBe('a');
+    expect(g.findNode('dashboard')?.id).toBe('a');
+    expect(g.findNode('dash')?.id).toBe('a');
+    expect(g.findNode('zzz')).toBeUndefined();
+  });
+
+  it('reports stats', () => {
+    const g = new ReactGraph();
+    g.addNode(makeNode({ id: 'a', name: 'A' }));
+    g.addNode(makeNode({ id: 'b', name: 'B', kind: 'Hook' }));
+    g.addEdge({ source: 'a', target: 'b', kind: 'uses_hook', meta: {} });
+
+    const s = g.stats();
+    expect(s.totalNodes).toBe(2);
+    expect(s.totalEdges).toBe(1);
+    expect(s.Component).toBe(1);
+    expect(s.Hook).toBe(1);
+  });
+
+  it('computes connectivity', () => {
+    const g = new ReactGraph();
+    g.addNode(makeNode({ id: 'a', name: 'A' }));
+    g.addNode(makeNode({ id: 'b', name: 'B' }));
+    g.addNode(makeNode({ id: 'c', name: 'C' }));
+    g.addEdge({ source: 'a', target: 'b', kind: 'renders', meta: {} });
+    g.addEdge({ source: 'a', target: 'c', kind: 'renders', meta: {} });
+    g.addEdge({ source: 'c', target: 'a', kind: 'uses_hook', meta: {} });
+
+    expect(g.connectivity('a')).toBe(3); // 2 out + 1 in
+    expect(g.connectivity('b')).toBe(1); // 1 in
+    expect(g.connectivity('c')).toBe(2); // 1 in + 1 out
+  });
+});