@grafema/core 0.1.0-alpha.1

package/src/core/AnalysisWorker.ts

@@ -0,0 +1,410 @@
+/**
+ * AnalysisWorker - worker thread for parallel AST analysis
+ *
+ * Each worker:
+ * 1. Connects to RFDB server
+ * 2. Receives file paths to analyze
+ * 3. Parses AST and writes nodes/edges directly to RFDB
+ *
+ * Communication:
+ *   Main -> Worker: { type: 'analyze', file, moduleId, moduleName }
+ *   Worker -> Main: { type: 'done', file, stats } | { type: 'error', file, error }
+ */
+
+import { parentPort, workerData } from 'worker_threads';
+import { readFileSync } from 'fs';
+import { parse, ParserPlugin } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import type { ImportDeclaration, FunctionDeclaration, ArrowFunctionExpression, ClassDeclaration, CallExpression, Identifier } from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+
+import { RFDBClient } from '@grafema/rfdb-client';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const traverse = (traverseModule as any).default || traverseModule;
+
+/**
+ * Worker data from main thread
+ */
+interface WorkerDataInput {
+  workerId?: number;
+  socketPath?: string;
+  autoConnect?: boolean;
+}
+
+/**
+ * Message types from main thread
+ */
+interface ConnectMessage {
+  type: 'connect';
+  socketPath?: string;
+}
+
+interface AnalyzeMessage {
+  type: 'analyze';
+  file: string;
+  moduleId: string;
+  moduleName: string;
+}
+
+interface DisconnectMessage {
+  type: 'disconnect';
+}
+
+interface ExitMessage {
+  type: 'exit';
+}
+
+type WorkerMessage = ConnectMessage | AnalyzeMessage | DisconnectMessage | ExitMessage;
+
+/**
+ * Analysis stats
+ */
+interface AnalysisStats {
+  nodes: number;
+  edges: number;
+  functions: number;
+  calls: number;
+}
+
+/**
+ * Wire node for RFDB
+ */
+interface WireNode {
+  id: string;
+  type: string;
+  name: string;
+  file: string;
+  metadata?: string;
+}
+
+/**
+ * Wire edge for RFDB
+ */
+interface WireEdge {
+  src: string;
+  dst: string;
+  type: string;
+}
+
+// Worker state
+let client: RFDBClient | null = null;
+const workerId = (workerData as WorkerDataInput)?.workerId || 0;
+let socketPath = (workerData as WorkerDataInput)?.socketPath || '/tmp/rfdb.sock';
+let connected = false;
+
+/**
+ * Connect to RFDB server
+ */
+async function connect(): Promise<void> {
+  if (connected) return;
+
+  client = new RFDBClient(socketPath);
+  await client.connect();
+  connected = true;
+
+  parentPort?.postMessage({ type: 'ready', workerId });
+}
+
+/**
+ * Parse a file and write results directly to RFDB
+ */
+async function analyzeFile(filePath: string, moduleId: string, moduleName: string): Promise<AnalysisStats> {
+  const stats: AnalysisStats = { nodes: 0, edges: 0, functions: 0, calls: 0 };
+
+  try {
+    const code = readFileSync(filePath, 'utf-8');
+
+    const ast = parse(code, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'] as ParserPlugin[],
+      errorRecovery: true
+    });
+
+    // Collections to batch write
+    const nodes: WireNode[] = [];
+    const edges: WireEdge[] = [];
+
+    // Counters for unique IDs
+    let callCounter = 0;
+
+    // Add module node
+    nodes.push({
+      id: moduleId,
+      type: 'MODULE',
+      name: moduleName,
+      file: filePath
+    });
+
+    // Extract imports
+    traverse(ast, {
+      ImportDeclaration(path: NodePath<ImportDeclaration>) {
+        const node = path.node;
+        const source = node.source.value;
+
+        node.specifiers.forEach(spec => {
+          let importedName: string;
+          let localName: string;
+
+          if (spec.type === 'ImportDefaultSpecifier') {
+            importedName = 'default';
+            localName = spec.local.name;
+          } else if (spec.type === 'ImportNamespaceSpecifier') {
+            importedName = '*';
+            localName = spec.local.name;
+          } else {
+            importedName = (spec.imported as Identifier)?.name || spec.local.name;
+            localName = spec.local.name;
+          }
+
+          const importId = `IMPORT#${localName}#${filePath}#${node.loc!.start.line}`;
+          nodes.push({
+            id: importId,
+            type: 'IMPORT',
+            name: localName,
+            file: filePath,
+            metadata: JSON.stringify({ importedName, source, line: node.loc!.start.line })
+          });
+
+          edges.push({ src: moduleId, dst: importId, type: 'CONTAINS' });
+        });
+      }
+    });
+
+    // Extract functions
+    traverse(ast, {
+      FunctionDeclaration(path: NodePath<FunctionDeclaration>) {
+        if (path.getFunctionParent()) return;
+
+        const node = path.node;
+        if (!node.id) return;
+
+        const funcName = node.id.name;
+        const functionId = `FUNCTION#${funcName}#${filePath}#${node.loc!.start.line}`;
+
+        nodes.push({
+          id: functionId,
+          type: 'FUNCTION',
+          name: funcName,
+          file: filePath,
+          metadata: JSON.stringify({
+            line: node.loc!.start.line,
+            async: node.async || false,
+            generator: node.generator || false,
+            exported: path.parent?.type?.includes('Export') || false
+          })
+        });
+
+        edges.push({ src: moduleId, dst: functionId, type: 'CONTAINS' });
+        stats.functions++;
+
+        // Extract parameters
+        node.params.forEach((param, index) => {
+          if (param.type === 'Identifier') {
+            const paramId = `PARAMETER#${param.name}#${functionId}#${index}`;
+            nodes.push({
+              id: paramId,
+              type: 'PARAMETER',
+              name: param.name,
+              file: filePath,
+              metadata: JSON.stringify({ index, functionId })
+            });
+            edges.push({ src: functionId, dst: paramId, type: 'CONTAINS' });
+          }
+        });
+      },
+
+      ArrowFunctionExpression(path: NodePath<ArrowFunctionExpression>) {
+        // Only process top-level arrow functions assigned to variables
+        if (path.getFunctionParent()) return;
+
+        const parent = path.parent;
+        if (parent.type !== 'VariableDeclarator') return;
+        if (!('id' in parent) || !parent.id || parent.id.type !== 'Identifier') return;
+
+        const funcName = parent.id.name;
+        const functionId = `FUNCTION#${funcName}#${filePath}#${path.node.loc!.start.line}`;
+
+        nodes.push({
+          id: functionId,
+          type: 'FUNCTION',
+          name: funcName,
+          file: filePath,
+          metadata: JSON.stringify({
+            line: path.node.loc!.start.line,
+            async: path.node.async || false,
+            arrowFunction: true
+          })
+        });
+
+        edges.push({ src: moduleId, dst: functionId, type: 'CONTAINS' });
+        stats.functions++;
+      }
+    });
+
+    // Extract classes
+    traverse(ast, {
+      ClassDeclaration(path: NodePath<ClassDeclaration>) {
+        if (path.getFunctionParent()) return;
+
+        const node = path.node;
+        if (!node.id) return;
+
+        const className = node.id.name;
+        const classId = `CLASS#${className}#${filePath}#${node.loc!.start.line}`;
+
+        nodes.push({
+          id: classId,
+          type: 'CLASS',
+          name: className,
+          file: filePath,
+          metadata: JSON.stringify({
+            line: node.loc!.start.line,
+            superClass: (node.superClass as Identifier)?.name || null
+          })
+        });
+
+        edges.push({ src: moduleId, dst: classId, type: 'CONTAINS' });
+
+        // Extract methods
+        node.body.body.forEach(member => {
+          if (member.type === 'ClassMethod' && member.key.type === 'Identifier') {
+            const methodName = member.key.name;
+            const methodId = `METHOD#${className}.${methodName}#${filePath}#${member.loc!.start.line}`;
+
+            nodes.push({
+              id: methodId,
+              type: 'METHOD',
+              name: methodName,
+              file: filePath,
+              metadata: JSON.stringify({
+                className,
+                line: member.loc!.start.line,
+                async: member.async || false,
+                static: member.static || false,
+                isConstructor: member.kind === 'constructor'
+              })
+            });
+
+            edges.push({ src: classId, dst: methodId, type: 'CONTAINS' });
+            stats.functions++;
+          }
+        });
+      }
+    });
+
+    // Extract call expressions (simplified)
+    traverse(ast, {
+      CallExpression(path: NodePath<CallExpression>) {
+        const node = path.node;
+
+        if (node.callee.type === 'Identifier') {
+          const callId = `CALL#${node.callee.name}#${filePath}#${node.loc!.start.line}:${callCounter++}`;
+
+          nodes.push({
+            id: callId,
+            type: 'CALL',
+            name: node.callee.name,
+            file: filePath,
+            metadata: JSON.stringify({
+              line: node.loc!.start.line,
+              argsCount: node.arguments.length
+            })
+          });
+
+          // Find parent function to connect
+          const parentFunc = path.getFunctionParent();
+          if (parentFunc) {
+            const parentName =
+              (parentFunc.node as { id?: Identifier }).id?.name ||
+              ((parentFunc.parent as { id?: Identifier })?.id?.name) ||
+              'anonymous';
+            edges.push({
+              src: `FUNCTION#${parentName}#${filePath}#${parentFunc.node.loc!.start.line}`,
+              dst: callId,
+              type: 'CONTAINS'
+            });
+          } else {
+            edges.push({ src: moduleId, dst: callId, type: 'CONTAINS' });
+          }
+
+          stats.calls++;
+        }
+      }
+    });
+
+    // Batch write to RFDB
+    if (nodes.length > 0 && client) {
+      await client.addNodes(nodes);
+      stats.nodes = nodes.length;
+    }
+
+    if (edges.length > 0 && client) {
+      await client.addEdges(edges, true); // skipValidation for speed
+      stats.edges = edges.length;
+    }
+
+    return stats;
+  } catch (err) {
+    throw new Error(`Failed to analyze ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Handle messages from main thread
+ */
+if (parentPort) {
+  parentPort.on('message', async (msg: WorkerMessage) => {
+    switch (msg.type) {
+      case 'connect':
+        try {
+          socketPath = msg.socketPath || socketPath;
+          await connect();
+        } catch (err) {
+          parentPort!.postMessage({ type: 'error', error: (err as Error).message });
+        }
+        break;
+
+      case 'analyze':
+        try {
+          const stats = await analyzeFile(msg.file, msg.moduleId, msg.moduleName);
+          parentPort!.postMessage({
+            type: 'done',
+            file: msg.file,
+            stats,
+            workerId
+          });
+        } catch (err) {
+          parentPort!.postMessage({
+            type: 'error',
+            file: msg.file,
+            error: (err as Error).message,
+            workerId
+          });
+        }
+        break;
+
+      case 'disconnect':
+        if (client) {
+          await client.close();
+          connected = false;
+        }
+        parentPort!.postMessage({ type: 'disconnected', workerId });
+        break;
+
+      case 'exit':
+        if (client) {
+          await client.close();
+        }
+        process.exit(0);
+        break;
+    }
+  });
+
+  // Auto-connect on start if socketPath provided
+  if ((workerData as WorkerDataInput)?.autoConnect) {
+    connect().catch(err => {
+      parentPort!.postMessage({ type: 'error', error: (err as Error).message });
+    });
+  }
+}

package/src/core/GraphBackend.ts

@@ -0,0 +1,265 @@
+/**
+ * GraphBackend - abstract base class for graph storage implementations
+ *
+ * This defines the full contract for graph storage backends.
+ * All operations are async for compatibility with disk-based storage.
+ *
+ * Implementations:
+ * - RFDBServerBackend (Rust-based, production)
+ * - TestBackend (wrapper over RFDBServerBackend for tests)
+ */
+
+import type { NodeRecord } from '@grafema/types';
+import type { EdgeRecord, EdgeType } from '@grafema/types';
+
+// Re-export types for convenience
+export type { NodeRecord as Node } from '@grafema/types';
+export type { EdgeRecord as Edge, EdgeType } from '@grafema/types';
+
+/**
+ * Query filter for finding nodes by attributes
+ */
+export interface AttrQuery {
+  kind?: number;
+  version?: string;
+  file_id?: string;
+  file?: string;
+  exported?: boolean;
+  type?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Graph statistics
+ */
+export interface GraphStats {
+  nodeCount: number;
+  edgeCount: number;
+}
+
+/**
+ * Exported graph data
+ */
+export interface GraphExport {
+  nodes: NodeRecord[];
+  edges: EdgeRecord[];
+}
+
+/**
+ * Abstract GraphBackend class - base for all graph storage implementations
+ */
+export abstract class GraphBackend {
+  /**
+   * Initialize backend
+   */
+  abstract initialize(): Promise<void>;
+
+  /**
+   * Connect to storage (alias for initialize)
+   */
+  async connect(): Promise<void> {
+    return this.initialize();
+  }
+
+  /**
+   * Close connection and flush data to disk
+   */
+  abstract close(): Promise<void>;
+
+  /**
+   * Clear all data
+   */
+  abstract clear(): Promise<void>;
+
+  // ========================================
+  // Node Operations
+  // ========================================
+
+  /**
+   * Add a single node
+   */
+  abstract addNode(node: NodeRecord): Promise<void>;
+
+  /**
+   * Add multiple nodes (batch operation)
+   */
+  abstract addNodes(nodes: NodeRecord[]): Promise<void>;
+
+  /**
+   * Get node by ID
+   */
+  abstract getNode(id: string): Promise<NodeRecord | null>;
+
+  /**
+   * Check if node exists
+   */
+  abstract nodeExists(id: string): Promise<boolean>;
+
+  /**
+   * Delete a node
+   */
+  abstract deleteNode(id: string): Promise<void>;
+
+  /**
+   * Find nodes by attributes
+   * @returns Array of node IDs
+   */
+  abstract findByAttr(query: AttrQuery): Promise<string[]>;
+
+  // ========================================
+  // Edge Operations
+  // ========================================
+
+  /**
+   * Add a single edge
+   */
+  abstract addEdge(edge: EdgeRecord): Promise<void>;
+
+  /**
+   * Add multiple edges (batch operation)
+   */
+  abstract addEdges(edges: EdgeRecord[]): Promise<void>;
+
+  /**
+   * Delete an edge
+   */
+  abstract deleteEdge(src: string, dst: string, type: string): Promise<void>;
+
+  /**
+   * Get outgoing edges from a node
+   * @param nodeId - Node ID
+   * @param edgeTypes - Filter by edge types (optional)
+   */
+  abstract getOutgoingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+
+  /**
+   * Get incoming edges to a node
+   * @param nodeId - Node ID
+   * @param edgeTypes - Filter by edge types (optional)
+   */
+  abstract getIncomingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+
+  // ========================================
+  // Graph Traversal
+  // ========================================
+
+  /**
+   * BFS traversal from start nodes
+   * @param startIds - Starting nodes
+   * @param maxDepth - Maximum depth
+   * @param edgeTypes - Edge types to traverse (as numbers)
+   * @returns Array of reachable node IDs
+   */
+  abstract bfs(startIds: string[], maxDepth: number, edgeTypes: number[]): Promise<string[]>;
+
+  // ========================================
+  // Persistence
+  // ========================================
+
+  /**
+   * Flush data to disk
+   */
+  abstract flush(): Promise<void>;
+
+  /**
+   * Get graph statistics
+   */
+  abstract getStats(): Promise<GraphStats>;
+
+  // ========================================
+  // Compatibility Methods (for tests and GUI)
+  // ========================================
+
+  /**
+   * Export entire graph to memory (only for tests!)
+   * WARNING: Do not use on large graphs
+   */
+  abstract export(): Promise<GraphExport>;
+
+  /**
+   * Find nodes by predicate (for demo-gui compatibility)
+   * WARNING: May be slow on large graphs
+   */
+  abstract findNodes(predicate: (node: NodeRecord) => boolean): Promise<NodeRecord[]>;
+
+  /**
+   * Get all nodes (for GUI - only for first level visualization)
+   * WARNING: Do not use on large graphs
+   */
+  abstract getAllNodes(): Promise<NodeRecord[]>;
+
+  /**
+   * Get all edges (for GUI)
+   * WARNING: Do not use on large graphs
+   */
+  abstract getAllEdges(): Promise<EdgeRecord[]>;
+}
+
+/**
+ * Node type to numeric kind mapping
+ */
+const NODE_TYPE_TO_KIND: Record<string, number> = {
+  'PROJECT': 1,
+  'SERVICE': 2,
+  'FUNCTION': 3,
+  'CLASS': 4,
+  'METHOD': 5,
+  'VARIABLE': 6,
+  'PARAMETER': 7,
+  'MODULE': 8,
+  'ROUTE': 9,
+  'ENDPOINT': 10,
+  'FILE': 11,
+  'EXTERNAL_MODULE': 12,
+  'IMPORT': 13,
+  'EXPORT': 14,
+  'CALL_SITE': 15,
+  'METHOD_CALL': 16,
+  'SCOPE': 17,
+  'VARIABLE_DECLARATION': 18,
+  'CONSTANT': 19,
+  'EVENT_LISTENER': 20,
+  'HTTP_REQUEST': 21,
+};
+
+/**
+ * Convert node type to numeric kind
+ */
+export function typeToKind(type: string): number {
+  return NODE_TYPE_TO_KIND[type] || 0;
+}
+
+/**
+ * Edge type to numeric mapping
+ */
+const EDGE_TYPE_TO_NUMBER: Record<string, number> = {
+  'CONTAINS': 1,
+  'DEPENDS_ON': 2,
+  'CALLS': 3,
+  'EXTENDS': 4,
+  'IMPLEMENTS': 5,
+  'USES': 6,
+  'DEFINES': 7,
+  'IMPORTS': 8,
+  'EXPORTS': 9,
+  'ROUTES_TO': 10,
+  'DECLARES': 11,
+  'HAS_SCOPE': 12,
+  'CAPTURES': 13,
+  'MODIFIES': 14,
+  'WRITES_TO': 15,
+  'INSTANCE_OF': 16,
+  'HANDLED_BY': 17,
+  'HAS_CALLBACK': 18,
+  'MAKES_REQUEST': 19,
+  'IMPORTS_FROM': 20,
+  'EXPORTS_TO': 21,
+};
+
+/**
+ * Convert edge type to number
+ */
+export function edgeTypeToNumber(type: string): number {
+  return EDGE_TYPE_TO_NUMBER[type] || 0;
+}