@reactgraph/cli 0.1.1

package/src/cli/init.ts

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ReactGraphConfig } from '../graph/schema.js';
+
+export interface InitResult {
+  framework: string;
+  srcDirs: string[];
+  configCreated: boolean;
+  gitignoreUpdated: boolean;
+}
+
+export function runInit(projectDir: string): InitResult {
+  const framework = detectFramework(projectDir);
+  const srcDirs = detectSrcDirs(projectDir);
+
+  // Create .reactgraph/ directory
+  const rgDir = join(projectDir, '.reactgraph');
+  mkdirSync(rgDir, { recursive: true });
+
+  // Write config
+  const config: ReactGraphConfig = {
+    srcDirs,
+    framework,
+    exclude: ['**/*.test.*', '**/*.spec.*', '**/*.stories.*'],
+  };
+  writeFileSync(join(rgDir, 'config.json'), JSON.stringify(config, null, 2));
+
+  // Update .gitignore
+  const gitignoreUpdated = ensureGitignore(projectDir);
+
+  return {
+    framework,
+    srcDirs,
+    configCreated: true,
+    gitignoreUpdated,
+  };
+}
+
+function detectFramework(projectDir: string): ReactGraphConfig['framework'] {
+  // Next.js
+  if (
+    existsSync(join(projectDir, 'next.config.js')) ||
+    existsSync(join(projectDir, 'next.config.mjs')) ||
+    existsSync(join(projectDir, 'next.config.ts'))
+  ) {
+    return 'next';
+  }
+
+  // Vite
+  if (
+    existsSync(join(projectDir, 'vite.config.ts')) ||
+    existsSync(join(projectDir, 'vite.config.js'))
+  ) {
+    return 'vite';
+  }
+
+  // Remix
+  if (existsSync(join(projectDir, 'remix.config.js'))) {
+    return 'remix';
+  }
+
+  // CRA (react-scripts in package.json)
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+    if (pkg.dependencies?.['react-scripts'] || pkg.devDependencies?.['react-scripts']) {
+      return 'cra';
+    }
+  } catch {
+    // no package.json
+  }
+
+  return 'unknown';
+}
+
+function detectSrcDirs(projectDir: string): string[] {
+  const candidates = ['src', 'app', 'pages', 'lib'];
+  const found = candidates.filter(d => existsSync(join(projectDir, d)));
+  return found.length > 0 ? found : ['.'];
+}
+
+function ensureGitignore(projectDir: string): boolean {
+  const gitignorePath = join(projectDir, '.gitignore');
+  const entry = '.reactgraph/';
+
+  try {
+    if (existsSync(gitignorePath)) {
+      const content = readFileSync(gitignorePath, 'utf-8');
+      if (content.includes(entry)) return false;
+      appendFileSync(gitignorePath, `\n# ReactGraph cache\n${entry}\n`);
+    } else {
+      writeFileSync(gitignorePath, `# ReactGraph cache\n${entry}\n`);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/cli/serve.ts

@@ -0,0 +1,29 @@
+import { loadGraph } from '../graph/serialize.js';
+import { startServer } from '../mcp/server.js';
+import { startWatcher } from '../watcher.js';
+
+export async function runServe(projectDir: string, watchMode: boolean = false): Promise<void> {
+  if (watchMode) {
+    const graph = await loadGraph(projectDir);
+    if (!graph) {
+      console.error('No graph found. Run "reactgraph index" first.');
+      process.exit(1);
+    }
+
+    startWatcher({
+      projectDir,
+      graph,
+      onUpdate: (file, stats) => {
+        process.stderr.write(`[reactgraph] Updated: ${file} (${stats.nodes} nodes, ${stats.edges} edges)\n`);
+      },
+      onError: (file, err) => {
+        process.stderr.write(`[reactgraph] Error parsing ${file}: ${err.message}\n`);
+      },
+    });
+
+    // Start MCP server with the live graph
+    await startServer(projectDir, graph);
+  } else {
+    await startServer(projectDir);
+  }
+}

package/src/cli/unused.ts

@@ -0,0 +1,88 @@
+import { render } from 'ink';
+import React from 'react';
+import { Box, Text } from 'ink';
+import { loadGraph } from '../graph/serialize.js';
+import type { ReactGraph } from '../graph/graph.js';
+import type { GraphNode } from '../graph/schema.js';
+
+export async function runUnused(projectDir: string): Promise<void> {
+  const graph = await loadGraph(projectDir);
+  if (!graph) {
+    console.error('No graph found. Run "reactgraph index" first.');
+    process.exit(1);
+  }
+
+  const orphanComponents = findOrphanComponents(graph);
+  const unusedHooks = findUnusedHooks(graph);
+  const unusedExports = findUnusedExports(graph);
+
+  const App = () => React.createElement(Box, { flexDirection: 'column', paddingTop: 1 },
+    React.createElement(Text, { bold: true }, 'ReactGraph — Unused Analysis'),
+    React.createElement(Text, null, ''),
+
+    // Orphan components
+    orphanComponents.length > 0
+      ? React.createElement(Box, { flexDirection: 'column' },
+          React.createElement(Text, { color: 'yellow' }, `Orphan components (${orphanComponents.length}) — rendered by nothing:`),
+          ...orphanComponents.map(c =>
+            React.createElement(Text, { key: c.id, dimColor: true }, `  ${c.name}  [${c.file}:${c.line}]`)
+          )
+        )
+      : React.createElement(Text, { color: 'green' }, '✓ No orphan components'),
+
+    React.createElement(Text, null, ''),
+
+    // Unused hooks
+    unusedHooks.length > 0
+      ? React.createElement(Box, { flexDirection: 'column' },
+          React.createElement(Text, { color: 'yellow' }, `Unused hooks (${unusedHooks.length}) — never called:`),
+          ...unusedHooks.map(h =>
+            React.createElement(Text, { key: h.id, dimColor: true }, `  ${h.name}  [${h.file}:${h.line}]`)
+          )
+        )
+      : React.createElement(Text, { color: 'green' }, '✓ No unused hooks'),
+
+    React.createElement(Text, null, ''),
+
+    // Unused exports
+    unusedExports.length > 0
+      ? React.createElement(Box, { flexDirection: 'column' },
+          React.createElement(Text, { color: 'yellow' }, `Unused exports (${unusedExports.length}) — never imported:`),
+          ...unusedExports.map(e =>
+            React.createElement(Text, { key: e.id, dimColor: true }, `  ${e.name}  [${e.file}:${e.line}]`)
+          )
+        )
+      : React.createElement(Text, { color: 'green' }, '✓ No unused exports'),
+  );
+
+  const { unmount } = render(React.createElement(App));
+  setTimeout(() => unmount(), 100);
+}
+
+function findOrphanComponents(graph: ReactGraph): GraphNode[] {
+  return graph.getNodesByKind('Component').filter(c => {
+    // A component is orphan if nothing renders it and it's not a route target
+    const renderedBy = graph.getEdgesTo(c.id, ['renders']);
+    return renderedBy.length === 0;
+  });
+}
+
+function findUnusedHooks(graph: ReactGraph): GraphNode[] {
+  return graph.getNodesByKind('Hook').filter(h => {
+    const usedBy = graph.getEdgesTo(h.id, ['uses_hook']);
+    return usedBy.length === 0;
+  });
+}
+
+function findUnusedExports(graph: ReactGraph): GraphNode[] {
+  // Find exported nodes that are never imported by anything
+  const allNodes = graph.getAllNodes();
+  return allNodes.filter(n => {
+    if (n.exportType === 'none') return false;
+    if (n.kind === 'Module') return false; // Modules themselves aren't "used"
+
+    // Check if any edge points to this node
+    const incoming = graph.getEdgesTo(n.id);
+    return incoming.length === 0;
+  });
+}

package/src/graph/graph.ts

@@ -0,0 +1,179 @@
+import type { GraphNode, GraphEdge, NodeKind, EdgeKind } from './schema.js';
+
+export class ReactGraph {
+  private nodes = new Map<string, GraphNode>();
+  private edges: GraphEdge[] = [];
+
+  // Secondary indexes
+  private byKind = new Map<NodeKind, Set<string>>();
+  private byFile = new Map<string, Set<string>>();
+  private byName = new Map<string, string[]>();
+  private edgesBySource = new Map<string, GraphEdge[]>();
+  private edgesByTarget = new Map<string, GraphEdge[]>();
+  private edgesByKind = new Map<EdgeKind, GraphEdge[]>();
+
+  addNode(node: GraphNode): void {
+    this.nodes.set(node.id, node);
+
+    // Index by kind
+    if (!this.byKind.has(node.kind)) this.byKind.set(node.kind, new Set());
+    this.byKind.get(node.kind)!.add(node.id);
+
+    // Index by file
+    if (!this.byFile.has(node.file)) this.byFile.set(node.file, new Set());
+    this.byFile.get(node.file)!.add(node.id);
+
+    // Index by name
+    if (!this.byName.has(node.name)) this.byName.set(node.name, []);
+    this.byName.get(node.name)!.push(node.id);
+  }
+
+  addEdge(edge: GraphEdge): void {
+    this.edges.push(edge);
+
+    if (!this.edgesBySource.has(edge.source)) this.edgesBySource.set(edge.source, []);
+    this.edgesBySource.get(edge.source)!.push(edge);
+
+    if (!this.edgesByTarget.has(edge.target)) this.edgesByTarget.set(edge.target, []);
+    this.edgesByTarget.get(edge.target)!.push(edge);
+
+    if (!this.edgesByKind.has(edge.kind)) this.edgesByKind.set(edge.kind, []);
+    this.edgesByKind.get(edge.kind)!.push(edge);
+  }
+
+  getNode(id: string): GraphNode | undefined {
+    return this.nodes.get(id);
+  }
+
+  getAllNodes(): GraphNode[] {
+    return Array.from(this.nodes.values());
+  }
+
+  getAllEdges(): GraphEdge[] {
+    return this.edges;
+  }
+
+  getNodesByKind(kind: NodeKind): GraphNode[] {
+    const ids = this.byKind.get(kind);
+    if (!ids) return [];
+    return Array.from(ids).map(id => this.nodes.get(id)!);
+  }
+
+  getNodesByFile(file: string): GraphNode[] {
+    const ids = this.byFile.get(file);
+    if (!ids) return [];
+    return Array.from(ids).map(id => this.nodes.get(id)!);
+  }
+
+  getNodesByName(name: string): GraphNode[] {
+    const ids = this.byName.get(name);
+    if (!ids) return [];
+    return ids.map(id => this.nodes.get(id)!);
+  }
+
+  getEdgesFrom(nodeId: string, kinds?: EdgeKind[]): GraphEdge[] {
+    const edges = this.edgesBySource.get(nodeId) ?? [];
+    if (!kinds) return edges;
+    return edges.filter(e => kinds.includes(e.kind));
+  }
+
+  getEdgesTo(nodeId: string, kinds?: EdgeKind[]): GraphEdge[] {
+    const edges = this.edgesByTarget.get(nodeId) ?? [];
+    if (!kinds) return edges;
+    return edges.filter(e => kinds.includes(e.kind));
+  }
+
+  getEdgesByKind(kind: EdgeKind): GraphEdge[] {
+    return this.edgesByKind.get(kind) ?? [];
+  }
+
+  removeNodesByFile(file: string): void {
+    const ids = this.byFile.get(file);
+    if (!ids) return;
+
+    // Remove edges referencing these nodes
+    const idSet = new Set(ids);
+    this.edges = this.edges.filter(e => !idSet.has(e.source) && !idSet.has(e.target));
+
+    // Rebuild edge indexes
+    this.edgesBySource.clear();
+    this.edgesByTarget.clear();
+    this.edgesByKind.clear();
+    for (const edge of this.edges) {
+      if (!this.edgesBySource.has(edge.source)) this.edgesBySource.set(edge.source, []);
+      this.edgesBySource.get(edge.source)!.push(edge);
+      if (!this.edgesByTarget.has(edge.target)) this.edgesByTarget.set(edge.target, []);
+      this.edgesByTarget.get(edge.target)!.push(edge);
+      if (!this.edgesByKind.has(edge.kind)) this.edgesByKind.set(edge.kind, []);
+      this.edgesByKind.get(edge.kind)!.push(edge);
+    }
+
+    // Remove nodes
+    for (const id of ids) {
+      const node = this.nodes.get(id)!;
+      this.nodes.delete(id);
+
+      // Clean kind index
+      this.byKind.get(node.kind)?.delete(id);
+
+      // Clean name index
+      const nameIds = this.byName.get(node.name);
+      if (nameIds) {
+        const idx = nameIds.indexOf(id);
+        if (idx >= 0) nameIds.splice(idx, 1);
+        if (nameIds.length === 0) this.byName.delete(node.name);
+      }
+    }
+
+    this.byFile.delete(file);
+  }
+
+  clear(): void {
+    this.nodes.clear();
+    this.edges = [];
+    this.byKind.clear();
+    this.byFile.clear();
+    this.byName.clear();
+    this.edgesBySource.clear();
+    this.edgesByTarget.clear();
+    this.edgesByKind.clear();
+  }
+
+  /** Find a node by name with fuzzy matching: exact → case-insensitive → partial */
+  findNode(name: string): GraphNode | undefined {
+    // Exact match
+    const exact = this.byName.get(name);
+    if (exact?.length) return this.nodes.get(exact[0]);
+
+    // Case-insensitive
+    const lower = name.toLowerCase();
+    for (const [key, ids] of this.byName) {
+      if (key.toLowerCase() === lower && ids.length) return this.nodes.get(ids[0]);
+    }
+
+    // Partial match
+    for (const [key, ids] of this.byName) {
+      if (key.toLowerCase().includes(lower) && ids.length) return this.nodes.get(ids[0]);
+    }
+
+    return undefined;
+  }
+
+  /** Count of in+out edges for a node */
+  connectivity(nodeId: string): number {
+    return (this.edgesBySource.get(nodeId)?.length ?? 0) +
+           (this.edgesByTarget.get(nodeId)?.length ?? 0);
+  }
+
+  stats(): Record<string, number> {
+    const s: Record<string, number> = {
+      totalNodes: this.nodes.size,
+      totalEdges: this.edges.length,
+      files: this.byFile.size,
+    };
+    for (const [kind, ids] of this.byKind) {
+      s[kind] = ids.size;
+    }
+    return s;
+  }
+}

package/src/graph/index.ts

@@ -0,0 +1,4 @@
+export { ReactGraph } from './graph.js';
+export * from './schema.js';
+export * from './serialize.js';
+export * from './traverse.js';

package/src/graph/schema.ts

@@ -0,0 +1,68 @@
+// ---- Node Types ----
+
+export type NodeKind =
+  | 'Component'
+  | 'Hook'
+  | 'BuiltinHook'
+  | 'Context'
+  | 'Route'
+  | 'Module'
+  | 'Store'
+  | 'ApiEndpoint'
+  | 'Type'
+  | 'Util'
+  | 'Constant';
+
+export interface GraphNode {
+  id: string;
+  kind: NodeKind;
+  name: string;
+  file: string; // relative path
+  line: number;
+  exportType: 'default' | 'named' | 'none';
+  props?: string[];
+  returns?: string;
+  doc?: string;
+  meta: Record<string, unknown>;
+}
+
+// ---- Edge Types ----
+
+export type EdgeKind =
+  | 'imports'
+  | 'renders'
+  | 'passes_prop'
+  | 'uses_hook'
+  | 'provides'
+  | 'consumes'
+  | 'calls'
+  | 'fetches'
+  | 'reads_store'
+  | 'writes_store'
+  | 'routes_to'
+  | 'type_of';
+
+export interface GraphEdge {
+  source: string; // node id
+  target: string; // node id
+  kind: EdgeKind;
+  meta: Record<string, unknown>;
+}
+
+// ---- Serialization ----
+
+export interface SerializedGraph {
+  version: number;
+  timestamp: string;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+// ---- Config ----
+
+export interface ReactGraphConfig {
+  srcDirs: string[];
+  framework: 'next' | 'vite' | 'cra' | 'remix' | 'unknown';
+  exclude: string[];
+  aliases?: Record<string, string>;
+}

package/src/graph/serialize.ts

@@ -0,0 +1,40 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { SerializedGraph } from './schema.js';
+import { ReactGraph } from './graph.js';
+
+const GRAPH_VERSION = 1;
+
+export function serializeGraph(graph: ReactGraph): SerializedGraph {
+  return {
+    version: GRAPH_VERSION,
+    timestamp: new Date().toISOString(),
+    nodes: graph.getAllNodes(),
+    edges: graph.getAllEdges(),
+  };
+}
+
+export function deserializeGraph(data: SerializedGraph): ReactGraph {
+  const graph = new ReactGraph();
+  for (const node of data.nodes) graph.addNode(node);
+  for (const edge of data.edges) graph.addEdge(edge);
+  return graph;
+}
+
+export async function saveGraph(graph: ReactGraph, projectDir: string): Promise<void> {
+  const dir = join(projectDir, '.reactgraph');
+  await mkdir(dir, { recursive: true });
+  const data = serializeGraph(graph);
+  await writeFile(join(dir, 'graph.json'), JSON.stringify(data, null, 2));
+}
+
+export async function loadGraph(projectDir: string): Promise<ReactGraph | null> {
+  try {
+    const raw = await readFile(join(projectDir, '.reactgraph', 'graph.json'), 'utf-8');
+    const data: SerializedGraph = JSON.parse(raw);
+    if (data.version !== GRAPH_VERSION) return null;
+    return deserializeGraph(data);
+  } catch {
+    return null;
+  }
+}

package/src/graph/traverse.ts

@@ -0,0 +1,66 @@
+import type { GraphNode, GraphEdge, EdgeKind } from './schema.js';
+import { ReactGraph } from './graph.js';
+
+export interface SubgraphResult {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  root: GraphNode;
+}
+
+/** BFS from a node, collecting all connected nodes/edges up to depth */
+export function getSubgraph(graph: ReactGraph, nodeId: string, depth: number = 2): SubgraphResult | null {
+  const root = graph.getNode(nodeId);
+  if (!root) return null;
+
+  const visitedNodes = new Set<string>([nodeId]);
+  const resultEdges: GraphEdge[] = [];
+  let frontier = [nodeId];
+
+  for (let d = 0; d < depth && frontier.length > 0; d++) {
+    const nextFrontier: string[] = [];
+
+    for (const id of frontier) {
+      // Outgoing edges
+      for (const edge of graph.getEdgesFrom(id)) {
+        resultEdges.push(edge);
+        if (!visitedNodes.has(edge.target)) {
+          visitedNodes.add(edge.target);
+          nextFrontier.push(edge.target);
+        }
+      }
+
+      // Incoming edges
+      for (const edge of graph.getEdgesTo(id)) {
+        resultEdges.push(edge);
+        if (!visitedNodes.has(edge.source)) {
+          visitedNodes.add(edge.source);
+          nextFrontier.push(edge.source);
+        }
+      }
+    }
+
+    frontier = nextFrontier;
+  }
+
+  const nodes = Array.from(visitedNodes)
+    .map(id => graph.getNode(id))
+    .filter((n): n is GraphNode => n !== undefined);
+
+  return { nodes, edges: resultEdges, root };
+}
+
+/** Get all nodes pointing to this node */
+export function getIncoming(graph: ReactGraph, nodeId: string, edgeKinds?: EdgeKind[]): GraphNode[] {
+  const edges = graph.getEdgesTo(nodeId, edgeKinds);
+  return edges
+    .map(e => graph.getNode(e.source))
+    .filter((n): n is GraphNode => n !== undefined);
+}
+
+/** Get all nodes this node points to */
+export function getOutgoing(graph: ReactGraph, nodeId: string, edgeKinds?: EdgeKind[]): GraphNode[] {
+  const edges = graph.getEdgesFrom(nodeId, edgeKinds);
+  return edges
+    .map(e => graph.getNode(e.target))
+    .filter((n): n is GraphNode => n !== undefined);
+}