@grafema/core 0.2.7 → 0.2.9

package/src/plugins/analysis/ast/GraphBuilder.ts

@@ -1,6 +1,7 @@
 /**
  * GraphBuilder - orchestrator that delegates to domain-specific builders
- * OPTIMIZED: Uses batched writes to reduce FFI overhead
+ * Writes nodes/edges directly to graph during RFDBClient batch window.
+ * Only FUNCTION nodes are deferred (pending metadata mutation by ModuleRuntimeBuilder).
  */
 
 import type { GraphBackend, NodeRecord } from '@grafema/types';
@@ -36,8 +37,19 @@ export class GraphBuilder {
   // Track singleton nodes to avoid duplicates (net:stdio, net:request, etc.)
   private _createdSingletons: Set<string> = new Set();
 
-  // Batching buffers for optimized writes
-  private _nodeBuffer: GraphNode[] = [];
+  // Graph reference for direct writes (set during build(), cleared after)
+  private _graph: GraphBackend | null = null;
+
+  // Pending function nodes (deferred until domain builders can mutate metadata)
+  private _pendingFunctions: Map<string, GraphNode> = new Map();
+
+  // Sync batch mode: push directly to RFDBClient batch arrays (no intermediate buffer)
+  private _useSyncBatch: boolean = false;
+  private _directNodeCount: number = 0;
+  private _directEdgeCount: number = 0;
+
+  // Fallback buffers (when graph.batchNode is not available)
+  private _nodeBuffer: unknown[] = [];
   private _edgeBuffer: GraphEdge[] = [];
 
   // Domain builders
@@ -72,7 +84,7 @@ export class GraphBuilder {
       bufferEdge: (edge) => this._bufferEdge(edge),
       isCreated: (key) => this._createdSingletons.has(key),
       markCreated: (key) => { this._createdSingletons.add(key); },
-      findBufferedNode: (id) => this._nodeBuffer.find(n => n.id === id),
+      findBufferedNode: (id) => this._pendingFunctions.get(id),
       findFunctionByName: (functions, name, file, callScopeId) =>
         this.findFunctionByName(functions, name, file, callScopeId),
       resolveVariableInScope: (name, scopePath, file, variables) =>
@@ -84,46 +96,79 @@ export class GraphBuilder {
   }
 
   /**
-   * Buffer a node for batched writing
+   * Buffer a node for batched writing.
+   * INVARIANT: Only FUNCTION nodes are deferred (stored in _pendingFunctions)
+   * because ModuleRuntimeBuilder mutates their metadata (rejectionPatterns)
+   * after buffering. All other nodes go to sync batch or fallback buffer.
    */
   private _bufferNode(node: GraphNode): void {
-    this._nodeBuffer.push(node);
+    if (!this._graph) throw new Error('_bufferNode called outside build() — _graph is null');
+    const branded = brandNodeInternal(node as unknown as NodeRecord);
+    if ((node as Record<string, unknown>).type === 'FUNCTION') {
+      this._pendingFunctions.set(node.id, branded as unknown as GraphNode);
+    } else if (this._useSyncBatch) {
+      this._graph.batchNode!(branded as unknown as Parameters<NonNullable<GraphBackend['batchNode']>>[0]);
+      this._directNodeCount++;
+    } else {
+      this._nodeBuffer.push(branded);
+    }
   }
 
   /**
-   * Buffer an edge for batched writing
+   * Buffer an edge for batched writing.
    */
   private _bufferEdge(edge: GraphEdge): void {
-    this._edgeBuffer.push(edge);
+    if (!this._graph) throw new Error('_bufferEdge called outside build() — _graph is null');
+    if (this._useSyncBatch) {
+      this._graph.batchEdge!(edge as unknown as Parameters<NonNullable<GraphBackend['batchEdge']>>[0]);
+      this._directEdgeCount++;
+    } else {
+      this._edgeBuffer.push(edge);
+    }
   }
 
   /**
-   * Flush all buffered nodes to the graph
+   * Flush pending function nodes to the graph.
+   * In sync batch mode, pushes each to batchNode. In fallback mode, uses addNodes.
+   * Returns count of function nodes flushed.
    */
-  private async _flushNodes(graph: GraphBackend): Promise<number> {
-    if (this._nodeBuffer.length > 0) {
-      // Brand nodes before flushing - they're validated by builders
-      const brandedNodes = this._nodeBuffer.map(node => brandNodeInternal(node as unknown as NodeRecord));
-      await graph.addNodes(brandedNodes);
-      const count = this._nodeBuffer.length;
-      this._nodeBuffer = [];
-      return count;
+  private async _flushPendingFunctions(graph: GraphBackend): Promise<number> {
+    const pendingFunctions = Array.from(this._pendingFunctions.values());
+    if (pendingFunctions.length === 0) return 0;
+
+    // Nodes already branded in _bufferNode() — no need to brand again
+    if (this._useSyncBatch) {
+      for (const node of pendingFunctions) {
+        graph.batchNode!(node as unknown as Parameters<NonNullable<GraphBackend['batchNode']>>[0]);
+      }
+    } else {
+      await graph.addNodes(pendingFunctions as unknown as Parameters<GraphBackend['addNodes']>[0]);
     }
-    return 0;
+
+    const count = pendingFunctions.length;
+    this._pendingFunctions.clear();
+    return count;
   }
 
   /**
-   * Flush all buffered edges to the graph
-   * Note: skip_validation=true because nodes were just flushed
+   * Flush fallback buffers (only used when sync batch is not available).
    */
-  private async _flushEdges(graph: GraphBackend): Promise<number> {
+  private async _flushFallbackBuffers(graph: GraphBackend): Promise<{ nodes: number; edges: number }> {
+    let nodesCreated = 0;
+    if (this._nodeBuffer.length > 0) {
+      await graph.addNodes(this._nodeBuffer as unknown as Parameters<GraphBackend['addNodes']>[0]);
+      nodesCreated = this._nodeBuffer.length;
+    }
+
+    let edgesCreated = 0;
     if (this._edgeBuffer.length > 0) {
-      await (graph as GraphBackend & { addEdges(e: GraphEdge[], skip?: boolean): Promise<void> }).addEdges(this._edgeBuffer, true /* skip_validation */);
-      const count = this._edgeBuffer.length;
-      this._edgeBuffer = [];
-      return count;
+      await (graph as GraphBackend & { addEdges(e: GraphEdge[], skip?: boolean): Promise<void> }).addEdges(this._edgeBuffer, true);
+      edgesCreated = this._edgeBuffer.length;
     }
-    return 0;
+
+    this._nodeBuffer = [];
+    this._edgeBuffer = [];
+    return { nodes: nodesCreated, edges: edgesCreated };
   }
 
   /**
@@ -150,7 +195,12 @@ export class GraphBuilder {
       hasTopLevelAwait = false
     } = data;
 
-    // Reset buffers for this build
+    // Reset state for this build
+    this._graph = graph;
+    this._pendingFunctions.clear();
+    this._useSyncBatch = typeof graph.batchNode === 'function' && typeof graph.batchEdge === 'function';
+    this._directNodeCount = 0;
+    this._directEdgeCount = 0;
     this._nodeBuffer = [];
     this._edgeBuffer = [];
 
@@ -275,9 +325,20 @@ export class GraphBuilder {
     this._typeSystemBuilder.buffer(module, data);
     this._moduleRuntimeBuilder.buffer(module, data);
 
-    // FLUSH: Write all nodes first, then edges in single batch calls
-    const nodesCreated = await this._flushNodes(graph);
-    const edgesCreated = await this._flushEdges(graph);
+    // FLUSH: Write pending function nodes (after domain builders mutated metadata)
+    const functionsCount = await this._flushPendingFunctions(graph);
+
+    // Flush fallback buffers if not using sync batch
+    let fallbackNodes = 0;
+    let fallbackEdges = 0;
+    if (!this._useSyncBatch) {
+      const fallback = await this._flushFallbackBuffers(graph);
+      fallbackNodes = fallback.nodes;
+      fallbackEdges = fallback.edges;
+    }
+
+    const nodesCreated = this._useSyncBatch ? this._directNodeCount + functionsCount : fallbackNodes + functionsCount;
+    const edgesCreated = this._useSyncBatch ? this._directEdgeCount : fallbackEdges;
 
     // Handle async operations for ASSIGNED_FROM with CLASS lookups
     const classAssignmentEdges = await this.createClassAssignmentEdges(variableAssignments, graph);
@@ -289,6 +350,8 @@ export class GraphBuilder {
     // REG-297: Update MODULE node with hasTopLevelAwait metadata
     await this.updateModuleTopLevelAwaitMetadata(module, graph, hasTopLevelAwait);
 
+    this._graph = null; // release reference
+
     return { nodes: nodesCreated, edges: edgesCreated + classAssignmentEdges };
   }
 
@@ -528,11 +591,9 @@ export class GraphBuilder {
         const file = parts.length >= 3 ? parts[2] : null;
 
         let classNode: { id: string; name: string; file?: string } | null = null;
-        for await (const node of graph.queryNodes({ type: 'CLASS' })) {
-          if (node.name === className && (!file || node.file === file)) {
-            classNode = node as { id: string; name: string; file?: string };
-            break;
-          }
+        for await (const node of graph.queryNodes(file ? { type: 'CLASS', name: className, file } : { type: 'CLASS', name: className })) {
+          classNode = node as { id: string; name: string; file?: string };
+          break;
         }
 
         if (classNode) {

package/src/plugins/analysis/ast/builders/types.ts

@@ -28,7 +28,7 @@ export interface BuilderContext {
   isCreated(singletonKey: string): boolean;
   markCreated(singletonKey: string): void;
 
-  // Buffered node lookup (for metadata updates, e.g., rejection patterns)
+  // Pending function node lookup (for metadata updates by ModuleRuntimeBuilder)
   findBufferedNode(id: string): GraphNode | undefined;
 
   // Scope-aware variable/parameter resolution (REG-309)

package/src/plugins/enrichment/MethodCallResolver.ts

@@ -27,7 +27,12 @@ import { StrictModeError } from '../../errors/GrafemaError.js';
 import { BUILTIN_PROTOTYPE_METHODS } from './method-call/MethodCallData.js';
 import type { MethodCallNode, LibraryCallStats } from './method-call/MethodCallData.js';
 import { isExternalMethod, isBuiltInObject, trackLibraryCall } from './method-call/MethodCallDetectors.js';
-import { buildClassMethodIndex, buildVariableTypeIndex } from './method-call/MethodCallIndexers.js';
+import {
+  buildClassMethodIndex,
+  buildVariableTypeIndex,
+  buildInterfaceMethodIndex,
+  buildInterfaceImplementationIndex
+} from './method-call/MethodCallIndexers.js';
 import { resolveMethodCall } from './method-call/MethodCallResolution.js';
 import { analyzeResolutionFailure, generateContextualSuggestion } from './method-call/MethodCallErrorAnalysis.js';
 
@@ -45,7 +50,7 @@ export class MethodCallResolver extends Plugin {
         edges: ['CALLS']
       },
       dependencies: ['ImportExportLinker'],
-      consumes: ['CONTAINS', 'INSTANCE_OF', 'DERIVES_FROM'],
+      consumes: ['CONTAINS', 'INSTANCE_OF', 'DERIVES_FROM', 'IMPLEMENTS', 'EXTENDS'],
       produces: ['CALLS']
     };
   }
@@ -104,6 +109,13 @@ export class MethodCallResolver extends Plugin {
 
     const variableTypes = await buildVariableTypeIndex(graph, logger);
 
+    // Build interface indexes for CHA fallback (REG-485)
+    const methodToInterfaces = await buildInterfaceMethodIndex(graph, logger);
+    logger.info('Indexed interface methods', { methods: methodToInterfaces.size });
+
+    const interfaceImpls = await buildInterfaceImplementationIndex(graph, logger);
+    logger.info('Indexed interface implementations', { interfaces: interfaceImpls.size });
+
     // Cache for containing class lookups (local to this execution)
     const containingClassCache = new Map<string, BaseNodeRecord | null>();
 
@@ -162,7 +174,9 @@ export class MethodCallResolver extends Plugin {
         classMethodIndex,
         variableTypes,
         graph,
-        containingClassCache
+        containingClassCache,
+        methodToInterfaces,
+        interfaceImpls
       );
 
       if (targetMethod) {

package/src/plugins/enrichment/method-call/MethodCallIndexers.ts

@@ -58,6 +58,165 @@ export async function buildClassMethodIndex(
   return index;
 }
 
+/**
+ * Builds an index of interface methods for CHA-based resolution (REG-485).
+ * Maps method name to the set of interface names that declare (or inherit) that method.
+ *
+ * Algorithm:
+ * 1. Query all INTERFACE nodes and extract method names from properties
+ * 2. Track EXTENDS edges between interfaces
+ * 3. Flatten inherited methods (walk EXTENDS chain with cycle protection, max depth 10)
+ * 4. Build final map: method name -> set of interface names
+ */
+export async function buildInterfaceMethodIndex(
+  graph: PluginContext['graph'],
+  logger: Logger
+): Promise<Map<string, Set<string>>> {
+  const startTime = Date.now();
+  const index = new Map<string, Set<string>>();
+
+  // Collect direct methods per interface and EXTENDS relationships
+  const interfaceMethods = new Map<string, Set<string>>();
+  const interfaceExtends = new Map<string, string[]>();
+
+  for await (const node of graph.queryNodes({ nodeType: 'INTERFACE' })) {
+    const interfaceName = node.name as string;
+    if (!interfaceName) continue;
+
+    // Parse properties field (may be JSON string or already parsed array)
+    let properties: Array<{ name: string; type?: string }> = [];
+    if (node.properties) {
+      try {
+        properties = typeof node.properties === 'string'
+          ? JSON.parse(node.properties)
+          : node.properties as Array<{ name: string; type?: string }>;
+      } catch {
+        // Skip unparseable properties
+      }
+    }
+
+    const methods = new Set<string>();
+    if (Array.isArray(properties)) {
+      for (const prop of properties) {
+        if (prop && typeof prop.name === 'string' && prop.name) {
+          methods.add(prop.name);
+        }
+      }
+    }
+    interfaceMethods.set(interfaceName, methods);
+
+    // Track EXTENDS edges for inheritance flattening
+    const extendsEdges = await graph.getOutgoingEdges(node.id, ['EXTENDS']);
+    if (extendsEdges.length > 0) {
+      const parentNames: string[] = [];
+      for (const edge of extendsEdges) {
+        const parentNode = await graph.getNode(edge.dst);
+        if (parentNode && parentNode.name) {
+          parentNames.push(parentNode.name as string);
+        }
+      }
+      if (parentNames.length > 0) {
+        interfaceExtends.set(interfaceName, parentNames);
+      }
+    }
+  }
+
+  // Flatten inherited methods with cycle protection
+  const resolvedMethods = new Map<string, Set<string>>();
+
+  function collectMethods(name: string, visited: Set<string>, depth: number): Set<string> {
+    if (depth > 10 || visited.has(name)) return new Set();
+    if (resolvedMethods.has(name)) return resolvedMethods.get(name)!;
+
+    visited.add(name);
+    const ownMethods = interfaceMethods.get(name) || new Set<string>();
+    const allMethods = new Set(ownMethods);
+
+    const parents = interfaceExtends.get(name);
+    if (parents) {
+      for (const parent of parents) {
+        const parentMethods = collectMethods(parent, visited, depth + 1);
+        for (const m of parentMethods) {
+          allMethods.add(m);
+        }
+      }
+    }
+
+    resolvedMethods.set(name, allMethods);
+    return allMethods;
+  }
+
+  for (const name of interfaceMethods.keys()) {
+    collectMethods(name, new Set(), 0);
+  }
+
+  // Build final index: method name -> set of interface names
+  for (const [interfaceName, methods] of resolvedMethods) {
+    for (const methodName of methods) {
+      let interfaces = index.get(methodName);
+      if (!interfaces) {
+        interfaces = new Set();
+        index.set(methodName, interfaces);
+      }
+      interfaces.add(interfaceName);
+    }
+  }
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  logger.debug('Built interface method index', {
+    interfaces: interfaceMethods.size,
+    methods: index.size,
+    time: `${elapsed}s`
+  });
+
+  return index;
+}
+
+/**
+ * Builds an index of interface implementations for CHA-based resolution (REG-485).
+ * Maps interface name to the set of class names that implement it.
+ *
+ * Algorithm:
+ * 1. Query all CLASS nodes
+ * 2. For each class, get outgoing IMPLEMENTS edges
+ * 3. For each IMPLEMENTS edge, get the target INTERFACE node name
+ * 4. Accumulate: interface name -> Set of class names
+ */
+export async function buildInterfaceImplementationIndex(
+  graph: PluginContext['graph'],
+  logger: Logger
+): Promise<Map<string, Set<string>>> {
+  const startTime = Date.now();
+  const index = new Map<string, Set<string>>();
+
+  for await (const classNode of graph.queryNodes({ nodeType: 'CLASS' })) {
+    const className = classNode.name as string;
+    if (!className) continue;
+
+    const implementsEdges = await graph.getOutgoingEdges(classNode.id, ['IMPLEMENTS']);
+    for (const edge of implementsEdges) {
+      const interfaceNode = await graph.getNode(edge.dst);
+      if (!interfaceNode || !interfaceNode.name) continue;
+
+      const interfaceName = interfaceNode.name as string;
+      let classes = index.get(interfaceName);
+      if (!classes) {
+        classes = new Set();
+        index.set(interfaceName, classes);
+      }
+      classes.add(className);
+    }
+  }
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  logger.debug('Built interface implementation index', {
+    interfaces: index.size,
+    time: `${elapsed}s`
+  });
+
+  return index;
+}
+
 /**
  * Builds an index of variables and their types (from INSTANCE_OF edges).
  */

package/src/plugins/enrichment/method-call/MethodCallResolution.ts

@@ -18,13 +18,16 @@ import type { MethodCallNode, ClassEntry } from './MethodCallData.js';
  * 2. Local class in same file
  * 3. "this" reference to containing class
  * 4. Variable type index (INSTANCE_OF)
+ * 5. Interface-aware CHA fallback (REG-485)
  */
 export async function resolveMethodCall(
   methodCall: MethodCallNode,
   classMethodIndex: Map<string, ClassEntry>,
   variableTypes: Map<string, string>,
   graph: PluginContext['graph'],
-  containingClassCache: Map<string, BaseNodeRecord | null>
+  containingClassCache: Map<string, BaseNodeRecord | null>,
+  methodToInterfaces?: Map<string, Set<string>>,
+  interfaceImpls?: Map<string, Set<string>>
 ): Promise<BaseNodeRecord | null> {
   const { object, method, file } = methodCall;
 
@@ -88,6 +91,55 @@ export async function resolveMethodCall(
     }
   }
 
+  // 5. Interface-aware CHA fallback (REG-485)
+  if (methodToInterfaces && interfaceImpls) {
+    const chaResult = await resolveViaInterfaceCHA(
+      method, classMethodIndex, methodToInterfaces, interfaceImpls, graph
+    );
+    if (chaResult) return chaResult;
+  }
+
+  return null;
+}
+
+/**
+ * Step 5: Interface-aware CHA fallback (REG-485).
+ *
+ * When steps 1-4 fail, look up method name in interface method index,
+ * find implementing classes, and resolve to their method definition.
+ * Also checks parent classes via DERIVES_FROM for inherited methods.
+ * This enables resolution for calls on variables typed as interfaces.
+ */
+export async function resolveViaInterfaceCHA(
+  methodName: string,
+  classMethodIndex: Map<string, ClassEntry>,
+  methodToInterfaces: Map<string, Set<string>>,
+  interfaceImpls: Map<string, Set<string>>,
+  graph: PluginContext['graph']
+): Promise<BaseNodeRecord | null> {
+  const candidateInterfaces = methodToInterfaces.get(methodName);
+  if (!candidateInterfaces || candidateInterfaces.size === 0) return null;
+
+  for (const interfaceName of candidateInterfaces) {
+    const implementingClasses = interfaceImpls.get(interfaceName);
+    if (!implementingClasses) continue;
+
+    for (const className of implementingClasses) {
+      const classEntry = classMethodIndex.get(className);
+      if (!classEntry) continue;
+
+      if (classEntry.methods.has(methodName)) {
+        return classEntry.methods.get(methodName)!;
+      }
+
+      // Check parent classes via DERIVES_FROM chain
+      const inherited = await findMethodInParentClasses(
+        classEntry.classNode, methodName, classMethodIndex, graph
+      );
+      if (inherited) return inherited;
+    }
+  }
+
   return null;
 }
 

package/src/storage/backends/RFDBServerBackend.ts

@@ -775,6 +775,45 @@ export class RFDBServerBackend {
     return this.client.commitBatch(tags);
   }
 
+  /**
+   * Synchronously batch a node. Must be inside beginBatch/commitBatch.
+   * Bypasses async wrapper for direct batch insertion.
+   */
+  batchNode(node: InputNode): void {
+    if (!this.client) throw new Error('Not connected');
+    const { id, type, nodeType, node_type, name, file, exported, ...rest } = node;
+    const useV3 = this.protocolVersion >= 3;
+    const wire: Record<string, unknown> = {
+      id: String(id),
+      nodeType: (nodeType || node_type || type || 'UNKNOWN'),
+      name: name || '',
+      file: file || '',
+      exported: exported || false,
+      metadata: useV3 ? JSON.stringify(rest) : JSON.stringify({ originalId: String(id), ...rest }),
+    };
+    if (useV3) {
+      wire.semanticId = String(id);
+    }
+    this.client.batchNode(wire as Parameters<typeof this.client.batchNode>[0]);
+  }
+
+  /**
+   * Synchronously batch an edge. Must be inside beginBatch/commitBatch.
+   */
+  batchEdge(edge: InputEdge): void {
+    if (!this.client) throw new Error('Not connected');
+    const { src, dst, type, edgeType, edge_type, etype, metadata, ...rest } = edge;
+    const edgeTypeStr = edgeType || edge_type || (etype as string) || type;
+    if (typeof edgeTypeStr === 'string') this.edgeTypes.add(edgeTypeStr);
+    const flatMetadata = { ...rest, ...(typeof metadata === 'object' && metadata !== null ? metadata as Record<string, unknown> : {}) };
+    this.client.batchEdge({
+      src: String(src),
+      dst: String(dst),
+      edgeType: (edgeTypeStr || 'UNKNOWN'),
+      metadata: JSON.stringify(flatMetadata),
+    } as Record<string, unknown>);
+  }
+
   /**
    * Abort the current batch, discarding all buffered data.
    */