@grafema/core 0.1.1-alpha → 0.2.1-beta

package/src/plugins/enrichment/NodejsBuiltinsResolver.ts

@@ -0,0 +1,365 @@
+/**
+ * NodejsBuiltinsResolver - Creates EXTERNAL_FUNCTION nodes for Node.js builtin calls (REG-218)
+ *
+ * This ENRICHMENT plugin:
+ * 1. Queries all CALL nodes
+ * 2. For each call that targets a builtin function:
+ *    - Checks if call's `object` matches a builtin module (fs, path, etc.)
+ *    - Or traces via IMPORT node to find the module source
+ * 3. Creates EXTERNAL_FUNCTION node lazily (if not exists)
+ * 4. Creates CALLS edge from CALL to EXTERNAL_FUNCTION
+ *
+ * Architecture:
+ * - Nodes are created lazily - only when a call is detected
+ * - ID format: EXTERNAL_FUNCTION:fs.readFile
+ * - Metadata includes: isBuiltin:true, security?, pure?
+ *
+ * Also creates:
+ * - EXTERNAL_MODULE nodes for imported builtin modules
+ * - IMPORTS_FROM edges from IMPORT to EXTERNAL_MODULE
+ */
+
+import { Plugin, createSuccessResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+import type { BaseNodeRecord } from '@grafema/types';
+import { BuiltinRegistry } from '../../data/builtins/BuiltinRegistry.js';
+
+/**
+ * Call node with method properties
+ */
+interface CallNode extends BaseNodeRecord {
+  object?: string;
+  method?: string;
+  callee?: string;
+}
+
+/**
+ * Import node with source info
+ */
+interface ImportNode extends BaseNodeRecord {
+  source?: string;
+  imported?: string;
+  importType?: string;
+}
+
+export class NodejsBuiltinsResolver extends Plugin {
+  private registry: BuiltinRegistry;
+
+  constructor(config: Record<string, unknown> = {}) {
+    super(config);
+    this.registry = new BuiltinRegistry();
+  }
+
+  get metadata(): PluginMetadata {
+    return {
+      name: 'NodejsBuiltinsResolver',
+      phase: 'ENRICHMENT',
+      priority: 45, // After ImportExportLinker (90), before/around MethodCallResolver (50)
+      creates: {
+        nodes: ['EXTERNAL_FUNCTION', 'EXTERNAL_MODULE'],
+        edges: ['CALLS', 'IMPORTS_FROM']
+      },
+      dependencies: ['JSASTAnalyzer', 'ImportExportLinker']
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const { graph, onProgress } = context;
+    const logger = this.log(context);
+
+    logger.info('Starting Node.js builtins resolution');
+    const startTime = Date.now();
+
+    // Track created nodes and edges to avoid duplicates
+    const createdExternalFunctions = new Set<string>();
+    const createdExternalModules = new Set<string>();
+    const createdCallsEdges = new Set<string>();
+    const createdImportsFromEdges = new Set<string>();
+
+    // Build import index: local name -> {source, imported}
+    // For tracking what module each imported function comes from
+    const importIndex = await this.buildImportIndex(graph);
+    logger.debug('Built import index', { entries: importIndex.size });
+
+    // Step 1: Create EXTERNAL_MODULE nodes for builtin imports
+    // and IMPORTS_FROM edges
+    let externalModulesCreated = 0;
+    let importsFromEdgesCreated = 0;
+
+    for (const [, importInfo] of importIndex) {
+      const { source, file, localName, importNodeId, importType } = importInfo;
+      const normalizedSource = this.registry.normalizeModule(source);
+
+      if (this.registry.isBuiltinModule(normalizedSource)) {
+        // Create EXTERNAL_MODULE node if not exists
+        if (!createdExternalModules.has(normalizedSource)) {
+          const moduleNodeId = `EXTERNAL_MODULE:${normalizedSource}`;
+
+          // Check if node already exists in graph
+          const existingNode = await graph.getNode(moduleNodeId);
+          if (!existingNode) {
+            await graph.addNode({
+              id: moduleNodeId,
+              type: 'EXTERNAL_MODULE',
+              name: normalizedSource,
+              file: '',
+              line: 0
+            });
+            externalModulesCreated++;
+          }
+          createdExternalModules.add(normalizedSource);
+        }
+
+        // Create IMPORTS_FROM edge from IMPORT to EXTERNAL_MODULE
+        const moduleNodeId = `EXTERNAL_MODULE:${normalizedSource}`;
+        const edgeKey = `${importNodeId}:${moduleNodeId}`;
+
+        if (!createdImportsFromEdges.has(edgeKey) && importNodeId) {
+          // Check if edge already exists
+          const existingEdges = await graph.getOutgoingEdges(importNodeId, ['IMPORTS_FROM']);
+          const alreadyExists = existingEdges.some(e => e.dst === moduleNodeId);
+
+          if (!alreadyExists) {
+            await graph.addEdge({
+              type: 'IMPORTS_FROM',
+              src: importNodeId,
+              dst: moduleNodeId
+            });
+            importsFromEdgesCreated++;
+          }
+          createdImportsFromEdges.add(edgeKey);
+        }
+      }
+    }
+
+    logger.debug('Created EXTERNAL_MODULE nodes', { count: externalModulesCreated });
+    logger.debug('Created IMPORTS_FROM edges', { count: importsFromEdgesCreated });
+
+    // Step 2: Process all CALL nodes
+    const allCalls: CallNode[] = [];
+    for await (const node of graph.queryNodes({ nodeType: 'CALL' })) {
+      allCalls.push(node as CallNode);
+    }
+    logger.info('Found CALL nodes to process', { count: allCalls.length });
+
+    let nodesCreated = 0;
+    let edgesCreated = 0;
+    let processed = 0;
+
+    for (const callNode of allCalls) {
+      processed++;
+
+      // Progress reporting
+      if (onProgress && processed % 100 === 0) {
+        onProgress({
+          phase: 'enrichment',
+          currentPlugin: 'NodejsBuiltinsResolver',
+          message: `Processing calls ${processed}/${allCalls.length}`,
+          totalFiles: allCalls.length,
+          processedFiles: processed
+        });
+      }
+
+      // Determine module and function name
+      const resolution = this.resolveBuiltinCall(callNode, importIndex);
+      if (!resolution) {
+        continue;
+      }
+
+      const { moduleName, functionName } = resolution;
+
+      // Check if this is a known builtin function
+      const funcDef = this.registry.getFunction(moduleName, functionName);
+      if (!funcDef) {
+        continue;
+      }
+
+      // Create EXTERNAL_FUNCTION node if not exists
+      const externalFuncId = this.registry.createNodeId(moduleName, functionName);
+
+      if (!createdExternalFunctions.has(externalFuncId)) {
+        // Check if node already exists in graph
+        const existingNode = await graph.getNode(externalFuncId);
+        if (!existingNode) {
+          await graph.addNode({
+            id: externalFuncId,
+            type: 'EXTERNAL_FUNCTION',
+            name: `${this.registry.normalizeModule(moduleName)}.${functionName}`,
+            file: '',
+            line: 0,
+            isBuiltin: true,
+            ...(funcDef.security && { security: funcDef.security }),
+            ...(funcDef.pure !== undefined && { pure: funcDef.pure })
+          });
+          nodesCreated++;
+        }
+        createdExternalFunctions.add(externalFuncId);
+      }
+
+      // Create CALLS edge from CALL to EXTERNAL_FUNCTION
+      const edgeKey = `${callNode.id}:${externalFuncId}`;
+      if (!createdCallsEdges.has(edgeKey)) {
+        // Check if CALLS edge already exists
+        const existingEdges = await graph.getOutgoingEdges(callNode.id, ['CALLS']);
+        const alreadyExists = existingEdges.some(e => e.dst === externalFuncId);
+
+        if (!alreadyExists) {
+          await graph.addEdge({
+            type: 'CALLS',
+            src: callNode.id,
+            dst: externalFuncId
+          });
+          edgesCreated++;
+        }
+        createdCallsEdges.add(edgeKey);
+      }
+    }
+
+    const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+    const summary = {
+      callsProcessed: processed,
+      externalFunctionsCreated: nodesCreated,
+      externalModulesCreated,
+      callsEdgesCreated: edgesCreated,
+      importsFromEdgesCreated,
+      time: `${totalTime}s`
+    };
+
+    logger.info('Complete', summary);
+
+    return createSuccessResult(
+      {
+        nodes: nodesCreated + externalModulesCreated,
+        edges: edgesCreated + importsFromEdgesCreated
+      },
+      summary
+    );
+  }
+
+  /**
+   * Build index of imports for tracking module sources.
+   *
+   * Maps: file:localName -> {source, imported, importNodeId, importType}
+   */
+  private async buildImportIndex(
+    graph: PluginContext['graph']
+  ): Promise<Map<string, {
+    source: string;
+    imported: string;
+    localName: string;
+    file: string;
+    importNodeId: string;
+    importType?: string;
+  }>> {
+    const index = new Map<string, {
+      source: string;
+      imported: string;
+      localName: string;
+      file: string;
+      importNodeId: string;
+      importType?: string;
+    }>();
+
+    for await (const node of graph.queryNodes({ nodeType: 'IMPORT' })) {
+      const importNode = node as ImportNode;
+      if (!importNode.source || !importNode.file) continue;
+
+      const localName = importNode.name as string;
+      const imported = importNode.imported || localName;
+      const importType = importNode.importType;
+
+      // Key: file:localName - for looking up what module a local name comes from
+      const key = `${importNode.file}:${localName}`;
+
+      index.set(key, {
+        source: importNode.source,
+        imported,
+        localName,
+        file: importNode.file,
+        importNodeId: importNode.id,
+        importType
+      });
+    }
+
+    return index;
+  }
+
+  /**
+   * Resolve a CALL node to its builtin module and function.
+   *
+   * Handles:
+   * 1. Method calls: fs.readFile() -> {module: 'fs', function: 'readFile'}
+   * 2. Direct calls from imports: readFile() -> trace to import source
+   * 3. Aliased imports: rf() where rf = readFile from 'fs'
+   */
+  private resolveBuiltinCall(
+    callNode: CallNode,
+    importIndex: Map<string, {
+      source: string;
+      imported: string;
+      localName: string;
+      file: string;
+      importNodeId: string;
+      importType?: string;
+    }>
+  ): { moduleName: string; functionName: string } | null {
+    const file = callNode.file;
+    if (!file) return null;
+
+    // Case 1: Method call - obj.method()
+    if (callNode.object && callNode.method) {
+      const objectName = callNode.object;
+      const methodName = callNode.method;
+
+      // Check if objectName is a namespace import (import * as fs from 'fs')
+      const importKey = `${file}:${objectName}`;
+      const importInfo = importIndex.get(importKey);
+
+      if (importInfo) {
+        // Object is an imported namespace or module
+        const normalizedSource = this.registry.normalizeModule(importInfo.source);
+
+        if (this.registry.isBuiltinModule(normalizedSource)) {
+          return {
+            moduleName: normalizedSource,
+            functionName: methodName
+          };
+        }
+      }
+
+      // Check if objectName directly matches a builtin module
+      // (for cases like: const fs = require('fs'); fs.readFile())
+      if (this.registry.isBuiltinModule(objectName)) {
+        return {
+          moduleName: this.registry.normalizeModule(objectName),
+          functionName: methodName
+        };
+      }
+
+      return null;
+    }
+
+    // Case 2: Direct call - funcName()
+    const calleeName = callNode.name as string || callNode.callee;
+    if (!calleeName) return null;
+
+    // Look up in import index
+    const importKey = `${file}:${calleeName}`;
+    const importInfo = importIndex.get(importKey);
+
+    if (importInfo) {
+      const normalizedSource = this.registry.normalizeModule(importInfo.source);
+
+      if (this.registry.isBuiltinModule(normalizedSource)) {
+        // Use the original imported name, not the alias
+        const originalName = importInfo.imported || calleeName;
+        return {
+          moduleName: normalizedSource,
+          functionName: originalName
+        };
+      }
+    }
+
+    return null;
+  }
+}

package/src/plugins/enrichment/ValueDomainAnalyzer.ts

@@ -17,6 +17,15 @@ import { Plugin, createSuccessResult } from '../Plugin.js';
 import type { PluginMetadata, PluginContext, PluginResult } from '../Plugin.js';
 import type { NodeRecord } from '@grafema/types';
 import type { EdgeRecord } from '@grafema/types';
+import {
+  traceValues,
+  aggregateValues,
+  NONDETERMINISTIC_PATTERNS,
+  NONDETERMINISTIC_OBJECTS,
+} from '../../queries/traceValues.js';
+
+// Re-export for backward compatibility
+export { NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS };
 
 interface ComputedCallNode {
   id: string;
@@ -42,22 +51,6 @@ interface VariableNode {
   [key: string]: unknown;
 }
 
-interface ExpressionNode {
-  id: string;
-  type: string;
-  name?: string;
-  file?: string;
-  line?: number;
-  expressionType?: string;
-  object?: string;
-  property?: string;
-  attrs?: {
-    expressionType?: string;
-    object?: string;
-    property?: string;
-  };
-}
-
 interface ScopeNode {
   id: string;
   type: string;
@@ -89,11 +82,6 @@ interface ValueSetAtNodeResult extends ValueSetResult {
   globalHasUnknown: boolean;
 }
 
-interface NondeterministicPattern {
-  object: string;
-  property: string;
-}
-
 interface Graph {
   queryNodes(filter: { nodeType: string }): AsyncIterable<NodeRecord>;
   getNode(id: string): Promise<NodeRecord | null>;
@@ -116,37 +104,6 @@ interface ProgressCallback {
 export class ValueDomainAnalyzer extends Plugin {
   static MAX_DEPTH = 10; // Maximum depth for tracing
 
-  // Nondeterministic MemberExpression patterns
-  // object.property patterns that are external/user input
-  static NONDETERMINISTIC_PATTERNS: NondeterministicPattern[] = [
-    // Environment variables
-    { object: 'process', property: 'env' },
-    // HTTP request data (Express.js patterns)
-    { object: 'req', property: 'body' },
-    { object: 'req', property: 'query' },
-    { object: 'req', property: 'params' },
-    { object: 'req', property: 'headers' },
-    { object: 'req', property: 'cookies' },
-    { object: 'request', property: 'body' },
-    { object: 'request', property: 'query' },
-    { object: 'request', property: 'params' },
-    // Context patterns (Koa, etc.)
-    { object: 'ctx', property: 'request' },
-    { object: 'ctx', property: 'body' },
-    { object: 'ctx', property: 'query' },
-    { object: 'ctx', property: 'params' },
-  ];
-
-  // Nondeterministic object prefixes (any property access is nondeterministic)
-  static NONDETERMINISTIC_OBJECTS: string[] = [
-    'process.env',  // process.env.ANY_VAR
-    'req.body',     // req.body.userId
-    'req.query',    // req.query.filter
-    'req.params',   // req.params.id
-    'request.body',
-    'ctx.request',
-  ];
-
   get metadata(): PluginMetadata {
     return {
       name: 'ValueDomainAnalyzer',
@@ -508,135 +465,69 @@ export class ValueDomainAnalyzer extends Plugin {
   }
 
   /**
-   * Check if an EXPRESSION node represents a nondeterministic source
-   */
-  isNondeterministicExpression(node: ExpressionNode): boolean {
-    const expressionType = node.expressionType || node.attrs?.expressionType;
-    if (expressionType !== 'MemberExpression') {
-      return false;
-    }
-
-    const object = node.object || node.attrs?.object;
-    const property = node.property || node.attrs?.property;
-
-    if (!object || !property) {
-      return false;
-    }
-
-    // Check exact patterns (object.property)
-    for (const pattern of ValueDomainAnalyzer.NONDETERMINISTIC_PATTERNS) {
-      if (object === pattern.object && property === pattern.property) {
-        return true;
-      }
-    }
-
-    // Check if object is a known nondeterministic prefix
-    // e.g., process.env.VAR where object is 'process.env'
-    for (const prefix of ValueDomainAnalyzer.NONDETERMINISTIC_OBJECTS) {
-      if (object === prefix || object.startsWith(prefix + '.')) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Recursive value set tracing through ASSIGNED_FROM edges
+   * Recursive value set tracing through ASSIGNED_FROM edges.
+   * Delegates to shared traceValues utility (REG-244).
    */
   async traceValueSet(
     node: NodeRecord,
     graph: Graph,
-    visited: Set<string>,
+    _visited: Set<string>,
     depth: number
   ): Promise<ValueSetResult> {
-    const result: ValueSetResult = { values: [], hasUnknown: false };
-
-    // Cycle protection
-    if (visited.has(node.id)) {
-      return result;
-    }
-    visited.add(node.id);
-
-    // Depth protection
-    if (depth > ValueDomainAnalyzer.MAX_DEPTH) {
-      result.hasUnknown = true;
-      return result;
-    }
-
-    // Support both fields: nodeType (from getNode) and type (alias)
-    const nodeType = (node as { nodeType?: string; type?: string }).nodeType ||
-                     (node as { type?: string }).type;
-
-    // If it's a LITERAL - add value
-    if (nodeType === 'LITERAL') {
-      const value = (node as { value?: unknown }).value;
-      if (value !== undefined && value !== null) {
-        result.values.push(value);
-      }
-      return result;
-    }
-
-    // If it's a PARAMETER or nondeterministic source
-    if (nodeType === 'PARAMETER') {
-      result.hasUnknown = true;
-      return result;
-    }
-
-    // If it's a CALL - consider nondeterministic (for now)
-    if (nodeType === 'CALL') {
-      result.hasUnknown = true;
-      return result;
-    }
-
-    // If it's an EXPRESSION - check nondeterministic patterns
-    if (nodeType === 'EXPRESSION') {
-      if (this.isNondeterministicExpression(node as ExpressionNode)) {
-        result.hasUnknown = true;
-        return result;
-      }
-    }
+    // Create adapter from Graph interface to TraceValuesGraphBackend
+    const backend = {
+      getNode: async (id: string) => {
+        const n = await graph.getNode(id);
+        if (!n) return null;
+        return {
+          id: n.id,
+          type: (n as { type?: string }).type,
+          nodeType: (n as { nodeType?: string }).nodeType,
+          value: (n as { value?: unknown }).value,
+          file: (n as { file?: string }).file,
+          line: (n as { line?: number }).line,
+          expressionType: (n as { expressionType?: string }).expressionType,
+          object: (n as { object?: string }).object,
+          property: (n as { property?: string }).property,
+        };
+      },
+      getOutgoingEdges: async (nodeId: string, edgeTypes: string[] | null) => {
+        const edges = await graph.getOutgoingEdges(nodeId);
+        const filtered = edgeTypes === null
+          ? edges
+          : edges.filter(e => edgeTypes.includes(e.type));
+        return filtered.map(e => ({
+          src: (e as { src?: string; source_id?: string }).src ||
+               (e as { source_id?: string }).source_id || '',
+          dst: (e as { dst?: string; target_id?: string }).dst ||
+               (e as { target_id?: string }).target_id || '',
+          type: e.type,
+        }));
+      },
+      // REG-334: getIncomingEdges required for Promise tracing
+      getIncomingEdges: async (nodeId: string, edgeTypes: string[] | null) => {
+        const edges = await graph.getIncomingEdges(nodeId);
+        const filtered = edgeTypes === null
+          ? edges
+          : edges.filter(e => edgeTypes.includes(e.type));
+        return filtered.map(e => ({
+          src: (e as { src?: string; source_id?: string }).src ||
+               (e as { source_id?: string }).source_id || '',
+          dst: (e as { dst?: string; target_id?: string }).dst ||
+               (e as { target_id?: string }).target_id || '',
+          type: e.type,
+        }));
+      },
+    };
 
-    // Follow ASSIGNED_FROM and DERIVES_FROM edges
-    // DERIVES_FROM is used for template literals and other composite expressions
-    const outgoing = await graph.getOutgoingEdges(node.id);
-    // edgeType (from getOutgoingEdges) or edge_type (from other APIs)
-    const dataFlowEdges = outgoing.filter(e => {
-      const edgeType = (e as { edgeType?: string; edge_type?: string }).edgeType ||
-                       (e as { edge_type?: string }).edge_type;
-      return edgeType === 'ASSIGNED_FROM' || edgeType === 'DERIVES_FROM';
+    // Use shared utility
+    const traced = await traceValues(backend, node.id, {
+      maxDepth: ValueDomainAnalyzer.MAX_DEPTH - depth,
+      followDerivesFrom: true,
+      detectNondeterministic: true,
     });
 
-    if (dataFlowEdges.length === 0) {
-      // No sources - unknown
-      result.hasUnknown = true;
-      return result;
-    }
-
-    // Recursively trace each source
-    for (const edge of dataFlowEdges) {
-      // dst (from getOutgoingEdges) or target_id (from other APIs)
-      const targetId = (edge as { dst?: string; target_id?: string }).dst ||
-                       (edge as { target_id?: string }).target_id;
-      if (!targetId) continue;
-
-      const sourceNode = await graph.getNode(targetId);
-      if (!sourceNode) continue;
-
-      const sourceResult = await this.traceValueSet(
-        sourceNode,
-        graph,
-        visited,
-        depth + 1
-      );
-
-      sourceResult.values.forEach(v => result.values.push(v));
-      if (sourceResult.hasUnknown) {
-        result.hasUnknown = true;
-      }
-    }
-
-    return result;
+    return aggregateValues(traced);
   }
 
   /**
@@ -655,11 +546,7 @@ export class ValueDomainAnalyzer extends Plugin {
         // Check if this is a method of the right object
         // Simplified: check via incoming CONTAINS edges from CLASS
         const incoming = await graph.getIncomingEdges(node.id);
-        const containsEdges = incoming.filter(e => {
-          const edgeType = (e as { edgeType?: string; edge_type?: string }).edgeType ||
-                           (e as { edge_type?: string }).edge_type;
-          return edgeType === 'CONTAINS';
-        });
+        const containsEdges = incoming.filter(e => e.type === 'CONTAINS');
 
         for (const edge of containsEdges) {
           const sourceId = (edge as { src?: string; source_id?: string }).src ||
@@ -714,18 +601,14 @@ export class ValueDomainAnalyzer extends Plugin {
       const outgoing = await graph.getOutgoingEdges(node.id);
 
       for (const edge of outgoing) {
-        const edgeType = (edge as { edgeType?: string; edge_type?: string; type?: string }).edgeType ||
-                         (edge as { edge_type?: string }).edge_type ||
-                         (edge as { type?: string }).type;
-
-        if (edgeType !== 'FLOWS_INTO') continue;
+        if (edge.type !== 'FLOWS_INTO') continue;
 
         const edgeKey = `${edge.src}->${edge.dst}:FLOWS_INTO`;
         if (processedEdges.has(edgeKey)) continue;
         processedEdges.add(edgeKey);
 
-        const mutationType = (edge as { mutationType?: string }).mutationType;
-        const computedPropertyVar = (edge as { computedPropertyVar?: string }).computedPropertyVar;
+        const mutationType = edge.metadata?.mutationType as string | undefined;
+        const computedPropertyVar = edge.metadata?.computedPropertyVar as string | undefined;
 
         if (mutationType !== 'computed' || !computedPropertyVar) continue;