@grafema/core 0.2.5-beta → 0.2.7

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

@@ -0,0 +1,262 @@
+/**
+ * UpdateExpressionBuilder - buffers UPDATE_EXPRESSION nodes and edges.
+ *
+ * Handles: increment/decrement operations for identifiers and member expressions.
+ */
+
+import { basename } from 'path';
+import type {
+  ModuleNode,
+  VariableDeclarationInfo,
+  ParameterInfo,
+  ClassDeclarationInfo,
+  UpdateExpressionInfo,
+  ASTCollections,
+  GraphNode,
+} from '../types.js';
+import type { BuilderContext, DomainBuilder } from './types.js';
+
+export class UpdateExpressionBuilder implements DomainBuilder {
+  constructor(private ctx: BuilderContext) {}
+
+  buffer(module: ModuleNode, data: ASTCollections): void {
+    const {
+      variableDeclarations,
+      updateExpressions = [],
+      parameters = [],
+      classDeclarations = [],
+    } = data;
+
+    this.bufferUpdateExpressionEdges(updateExpressions, variableDeclarations, parameters, classDeclarations);
+  }
+
+  /**
+   * Buffer UPDATE_EXPRESSION nodes and edges for increment/decrement operations.
+   *
+   * Handles two target types:
+   * - IDENTIFIER: Simple variable (i++, --count)
+   * - MEMBER_EXPRESSION: Object property (obj.prop++, arr[i]++, this.count++)
+   *
+   * Creates:
+   * - UPDATE_EXPRESSION node with operator and target metadata
+   * - MODIFIES edge: UPDATE_EXPRESSION -> target (VARIABLE, PARAMETER, or CLASS)
+   * - READS_FROM self-loop: target -> target (reads current value before update)
+   * - CONTAINS edge: SCOPE -> UPDATE_EXPRESSION
+   *
+   * REG-288: Initial implementation for IDENTIFIER targets
+   * REG-312: Extended for MEMBER_EXPRESSION targets
+   */
+  private bufferUpdateExpressionEdges(
+    updateExpressions: UpdateExpressionInfo[],
+    variableDeclarations: VariableDeclarationInfo[],
+    parameters: ParameterInfo[],
+    classDeclarations: ClassDeclarationInfo[]
+  ): void {
+    // Build lookup caches: O(n) instead of O(n*m)
+    const varLookup = new Map<string, VariableDeclarationInfo>();
+    for (const v of variableDeclarations) {
+      varLookup.set(`${v.file}:${v.name}`, v);
+    }
+
+    const paramLookup = new Map<string, ParameterInfo>();
+    for (const p of parameters) {
+      paramLookup.set(`${p.file}:${p.name}`, p);
+    }
+
+    for (const update of updateExpressions) {
+      if (update.targetType === 'IDENTIFIER') {
+        // REG-288: Simple identifier (i++, --count)
+        this.bufferIdentifierUpdate(update, varLookup, paramLookup);
+      } else if (update.targetType === 'MEMBER_EXPRESSION') {
+        // REG-312: Member expression (obj.prop++, arr[i]++)
+        this.bufferMemberExpressionUpdate(update, varLookup, paramLookup, classDeclarations);
+      }
+    }
+  }
+
+  /**
+   * Buffer UPDATE_EXPRESSION node and edges for simple identifier updates (i++, --count)
+   * REG-288: Original implementation extracted for clarity
+   */
+  private bufferIdentifierUpdate(
+    update: UpdateExpressionInfo,
+    varLookup: Map<string, VariableDeclarationInfo>,
+    paramLookup: Map<string, ParameterInfo>
+  ): void {
+    const {
+      variableName,
+      operator,
+      prefix,
+      file,
+      line,
+      column,
+      parentScopeId
+    } = update;
+
+    if (!variableName) return;
+
+    // Find target variable node
+    const targetVar = varLookup.get(`${file}:${variableName}`);
+    const targetParam = !targetVar ? paramLookup.get(`${file}:${variableName}`) : null;
+    const targetNodeId = targetVar?.id ?? targetParam?.id;
+
+    if (!targetNodeId) {
+      // Variable not found - could be module-level or external reference
+      return;
+    }
+
+    // Create UPDATE_EXPRESSION node
+    const updateId = `${file}:UPDATE_EXPRESSION:${operator}:${line}:${column}`;
+
+    this.ctx.bufferNode({
+      type: 'UPDATE_EXPRESSION',
+      id: updateId,
+      name: `${prefix ? operator : ''}${variableName}${prefix ? '' : operator}`,
+      targetType: 'IDENTIFIER',
+      operator,
+      prefix,
+      variableName,
+      file,
+      line,
+      column
+    } as GraphNode);
+
+    // Create READS_FROM self-loop
+    this.ctx.bufferEdge({
+      type: 'READS_FROM',
+      src: targetNodeId,
+      dst: targetNodeId
+    });
+
+    // Create MODIFIES edge
+    this.ctx.bufferEdge({
+      type: 'MODIFIES',
+      src: updateId,
+      dst: targetNodeId
+    });
+
+    // Create CONTAINS edge
+    if (parentScopeId) {
+      this.ctx.bufferEdge({
+        type: 'CONTAINS',
+        src: parentScopeId,
+        dst: updateId
+      });
+    }
+  }
+
+  /**
+   * Buffer UPDATE_EXPRESSION node and edges for member expression updates (obj.prop++, arr[i]++)
+   * REG-312: New implementation for member expression targets
+   *
+   * Creates:
+   * - UPDATE_EXPRESSION node with member expression metadata
+   * - MODIFIES edge: UPDATE_EXPRESSION -> VARIABLE(object) or CLASS (for this.prop++)
+   * - READS_FROM self-loop: VARIABLE(object) -> VARIABLE(object)
+   * - CONTAINS edge: SCOPE -> UPDATE_EXPRESSION
+   */
+  private bufferMemberExpressionUpdate(
+    update: UpdateExpressionInfo,
+    varLookup: Map<string, VariableDeclarationInfo>,
+    paramLookup: Map<string, ParameterInfo>,
+    classDeclarations: ClassDeclarationInfo[]
+  ): void {
+    const {
+      objectName,
+      propertyName,
+      mutationType,
+      computedPropertyVar,
+      enclosingClassName,
+      operator,
+      prefix,
+      file,
+      line,
+      column,
+      parentScopeId
+    } = update;
+
+    if (!objectName || !propertyName) return;
+
+    // Find target object node
+    let objectNodeId: string | null = null;
+
+    if (objectName !== 'this') {
+      // Regular object: obj.prop++, arr[i]++
+      const targetVar = varLookup.get(`${file}:${objectName}`);
+      const targetParam = !targetVar ? paramLookup.get(`${file}:${objectName}`) : null;
+      objectNodeId = targetVar?.id ?? targetParam?.id ?? null;
+    } else {
+      // this.prop++ - follow REG-152 pattern from bufferObjectMutationEdges
+      if (!enclosingClassName) return;
+
+      const fileBasename = basename(file);
+      const classDecl = classDeclarations.find(c =>
+        c.name === enclosingClassName && c.file === fileBasename
+      );
+      objectNodeId = classDecl?.id ?? null;
+    }
+
+    if (!objectNodeId) {
+      // Object not found - external reference or scope issue
+      return;
+    }
+
+    // Create UPDATE_EXPRESSION node
+    const updateId = `${file}:UPDATE_EXPRESSION:${operator}:${line}:${column}`;
+
+    // Display name: "obj.prop++" or "this.count++" or "arr[i]++"
+    const displayName = (() => {
+      const opStr = prefix ? operator : '';
+      const postOpStr = prefix ? '' : operator;
+
+      if (objectName === 'this') {
+        return `${opStr}this.${propertyName}${postOpStr}`;
+      }
+      if (mutationType === 'computed') {
+        const computedPart = computedPropertyVar || '?';
+        return `${opStr}${objectName}[${computedPart}]${postOpStr}`;
+      }
+      return `${opStr}${objectName}.${propertyName}${postOpStr}`;
+    })();
+
+    this.ctx.bufferNode({
+      type: 'UPDATE_EXPRESSION',
+      id: updateId,
+      name: displayName,
+      targetType: 'MEMBER_EXPRESSION',
+      operator,
+      prefix,
+      objectName,
+      propertyName,
+      mutationType,
+      computedPropertyVar,
+      enclosingClassName,
+      file,
+      line,
+      column
+    } as GraphNode);
+
+    // Create READS_FROM self-loop (object reads from itself)
+    this.ctx.bufferEdge({
+      type: 'READS_FROM',
+      src: objectNodeId,
+      dst: objectNodeId
+    });
+
+    // Create MODIFIES edge (UPDATE_EXPRESSION modifies object)
+    this.ctx.bufferEdge({
+      type: 'MODIFIES',
+      src: updateId,
+      dst: objectNodeId
+    });
+
+    // Create CONTAINS edge
+    if (parentScopeId) {
+      this.ctx.bufferEdge({
+        type: 'CONTAINS',
+        src: parentScopeId,
+        dst: updateId
+      });
+    }
+  }
+}

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

@@ -0,0 +1,287 @@
+/**
+ * YieldBuilder - buffers YIELDS and DELEGATES_TO edges connecting yield expressions
+ * to their generator functions.
+ *
+ * Extracted from GraphBuilder.bufferYieldEdges (REG-422).
+ */
+
+import { NodeFactory } from '../../../../core/NodeFactory.js';
+import type {
+  ModuleNode,
+  ASTCollections,
+  YieldExpressionInfo,
+  CallSiteInfo,
+  MethodCallInfo,
+  VariableDeclarationInfo,
+  ParameterInfo,
+} from '../types.js';
+import type { BuilderContext, DomainBuilder } from './types.js';
+
+export class YieldBuilder implements DomainBuilder {
+  constructor(private ctx: BuilderContext) {}
+
+  buffer(module: ModuleNode, data: ASTCollections): void {
+    const {
+      yieldExpressions = [],
+      callSites = [],
+      methodCalls = [],
+      variableDeclarations = [],
+      parameters = [],
+    } = data;
+    this.bufferYieldEdges(yieldExpressions, callSites, methodCalls, variableDeclarations, parameters);
+  }
+
+  /**
+   * Buffer YIELDS and DELEGATES_TO edges connecting yield expressions to their generator functions.
+   *
+   * Edge direction:
+   * - For yield:  yieldedExpression --YIELDS--> generatorFunction
+   * - For yield*: delegatedCall --DELEGATES_TO--> generatorFunction
+   *
+   * This enables tracing data flow through generator functions:
+   * - Query: "What does this generator yield?"
+   * - Answer: Follow YIELDS edges from function to see all possible yielded values
+   * - Query: "What generators does this delegate to?"
+   * - Answer: Follow DELEGATES_TO edges from function
+   *
+   * REG-270: Generator yield tracking
+   */
+  private bufferYieldEdges(
+    yieldExpressions: YieldExpressionInfo[],
+    callSites: CallSiteInfo[],
+    methodCalls: MethodCallInfo[],
+    variableDeclarations: VariableDeclarationInfo[],
+    parameters: ParameterInfo[]
+  ): void {
+    for (const yld of yieldExpressions) {
+      const { parentFunctionId, yieldValueType, file, isDelegate } = yld;
+
+      // Skip if no value yielded (bare yield;)
+      if (yieldValueType === 'NONE') {
+        continue;
+      }
+
+      let sourceNodeId: string | null = null;
+
+      switch (yieldValueType) {
+        case 'LITERAL':
+          // Direct reference to literal node
+          sourceNodeId = yld.yieldValueId ?? null;
+          break;
+
+        case 'VARIABLE': {
+          // Find variable declaration by name in same file
+          const varName = yld.yieldValueName;
+          if (varName) {
+            const sourceVar = variableDeclarations.find(v =>
+              v.name === varName && v.file === file
+            );
+            if (sourceVar) {
+              sourceNodeId = sourceVar.id;
+            } else {
+              // Check parameters
+              const sourceParam = parameters.find(p =>
+                p.name === varName && p.file === file
+              );
+              if (sourceParam) {
+                sourceNodeId = sourceParam.id;
+              }
+            }
+          }
+          break;
+        }
+
+        case 'CALL_SITE': {
+          // Find call site by coordinates
+          const { yieldValueLine, yieldValueColumn, yieldValueCallName } = yld;
+          if (yieldValueLine && yieldValueColumn) {
+            const callSite = callSites.find(cs =>
+              cs.line === yieldValueLine &&
+              cs.column === yieldValueColumn &&
+              (yieldValueCallName ? cs.name === yieldValueCallName : true)
+            );
+            if (callSite) {
+              sourceNodeId = callSite.id;
+            }
+          }
+          break;
+        }
+
+        case 'METHOD_CALL': {
+          // Find method call by coordinates and method name
+          const { yieldValueLine, yieldValueColumn, yieldValueCallName } = yld;
+          if (yieldValueLine && yieldValueColumn) {
+            const methodCall = methodCalls.find(mc =>
+              mc.line === yieldValueLine &&
+              mc.column === yieldValueColumn &&
+              mc.file === file &&
+              (yieldValueCallName ? mc.method === yieldValueCallName : true)
+            );
+            if (methodCall) {
+              sourceNodeId = methodCall.id;
+            }
+          }
+          break;
+        }
+
+        case 'EXPRESSION': {
+          // Create EXPRESSION node and DERIVES_FROM edges for yield expressions
+          const {
+            expressionType,
+            yieldValueId,
+            yieldValueLine,
+            yieldValueColumn,
+            operator,
+            object,
+            property,
+            computed,
+            objectSourceName,
+            leftSourceName,
+            rightSourceName,
+            consequentSourceName,
+            alternateSourceName,
+            expressionSourceNames,
+            unaryArgSourceName
+          } = yld;
+
+          // Skip if no expression ID was generated
+          if (!yieldValueId) {
+            break;
+          }
+
+          // Create EXPRESSION node using NodeFactory
+          const expressionNode = NodeFactory.createExpressionFromMetadata(
+            expressionType || 'Unknown',
+            file,
+            yieldValueLine || yld.line,
+            yieldValueColumn || yld.column,
+            {
+              id: yieldValueId,
+              object,
+              property,
+              computed,
+              operator
+            }
+          );
+
+          this.ctx.bufferNode(expressionNode);
+          sourceNodeId = yieldValueId;
+
+          // Buffer DERIVES_FROM edges based on expression type
+          // Helper function to find source variable or parameter
+          const findSource = (name: string): string | null => {
+            const variable = variableDeclarations.find(v =>
+              v.name === name && v.file === file
+            );
+            if (variable) return variable.id;
+
+            const param = parameters.find(p =>
+              p.name === name && p.file === file
+            );
+            if (param) return param.id;
+
+            return null;
+          };
+
+          // MemberExpression: derives from the object
+          if (expressionType === 'MemberExpression' && objectSourceName) {
+            const srcId = findSource(objectSourceName);
+            if (srcId) {
+              this.ctx.bufferEdge({
+                type: 'DERIVES_FROM',
+                src: yieldValueId,
+                dst: srcId
+              });
+            }
+          }
+
+          // BinaryExpression / LogicalExpression: derives from left and right operands
+          if (expressionType === 'BinaryExpression' || expressionType === 'LogicalExpression') {
+            if (leftSourceName) {
+              const srcId = findSource(leftSourceName);
+              if (srcId) {
+                this.ctx.bufferEdge({
+                  type: 'DERIVES_FROM',
+                  src: yieldValueId,
+                  dst: srcId
+                });
+              }
+            }
+            if (rightSourceName) {
+              const srcId = findSource(rightSourceName);
+              if (srcId) {
+                this.ctx.bufferEdge({
+                  type: 'DERIVES_FROM',
+                  src: yieldValueId,
+                  dst: srcId
+                });
+              }
+            }
+          }
+
+          // ConditionalExpression: derives from consequent and alternate
+          if (expressionType === 'ConditionalExpression') {
+            if (consequentSourceName) {
+              const srcId = findSource(consequentSourceName);
+              if (srcId) {
+                this.ctx.bufferEdge({
+                  type: 'DERIVES_FROM',
+                  src: yieldValueId,
+                  dst: srcId
+                });
+              }
+            }
+            if (alternateSourceName) {
+              const srcId = findSource(alternateSourceName);
+              if (srcId) {
+                this.ctx.bufferEdge({
+                  type: 'DERIVES_FROM',
+                  src: yieldValueId,
+                  dst: srcId
+                });
+              }
+            }
+          }
+
+          // UnaryExpression: derives from the argument
+          if (expressionType === 'UnaryExpression' && unaryArgSourceName) {
+            const srcId = findSource(unaryArgSourceName);
+            if (srcId) {
+              this.ctx.bufferEdge({
+                type: 'DERIVES_FROM',
+                src: yieldValueId,
+                dst: srcId
+              });
+            }
+          }
+
+          // TemplateLiteral: derives from all embedded expressions
+          if (expressionType === 'TemplateLiteral' && expressionSourceNames && expressionSourceNames.length > 0) {
+            for (const sourceName of expressionSourceNames) {
+              const srcId = findSource(sourceName);
+              if (srcId) {
+                this.ctx.bufferEdge({
+                  type: 'DERIVES_FROM',
+                  src: yieldValueId,
+                  dst: srcId
+                });
+              }
+            }
+          }
+
+          break;
+        }
+      }
+
+      // Create YIELDS or DELEGATES_TO edge if we found a source node
+      if (sourceNodeId && parentFunctionId) {
+        const edgeType = isDelegate ? 'DELEGATES_TO' : 'YIELDS';
+        this.ctx.bufferEdge({
+          type: edgeType,
+          src: sourceNodeId,
+          dst: parentFunctionId
+        });
+      }
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+export { CoreBuilder } from './CoreBuilder.js';
+export { ControlFlowBuilder } from './ControlFlowBuilder.js';
+export { AssignmentBuilder } from './AssignmentBuilder.js';
+export { CallFlowBuilder } from './CallFlowBuilder.js';
+export { MutationBuilder } from './MutationBuilder.js';
+export { UpdateExpressionBuilder } from './UpdateExpressionBuilder.js';
+export { ReturnBuilder } from './ReturnBuilder.js';
+export { YieldBuilder } from './YieldBuilder.js';
+export { TypeSystemBuilder } from './TypeSystemBuilder.js';
+export { ModuleRuntimeBuilder } from './ModuleRuntimeBuilder.js';
+export type { BuilderContext, DomainBuilder } from './types.js';

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

@@ -0,0 +1,65 @@
+/**
+ * Shared types for domain-specific graph builders.
+ *
+ * Each builder buffers nodes/edges for a specific domain (core, control flow,
+ * data flow, etc.) using the BuilderContext for shared operations.
+ */
+
+import type {
+  ModuleNode,
+  FunctionInfo,
+  VariableDeclarationInfo,
+  ParameterInfo,
+  ASTCollections,
+  GraphNode,
+  GraphEdge,
+} from '../types.js';
+
+/**
+ * Shared context passed to all domain builders.
+ * Provides access to buffers, singleton tracking, and scope resolution utilities.
+ */
+export interface BuilderContext {
+  // Buffering operations
+  bufferNode(node: GraphNode): void;
+  bufferEdge(edge: GraphEdge): void;
+
+  // Singleton tracking (for net:stdio, net:request, EXTERNAL_MODULE, etc.)
+  isCreated(singletonKey: string): boolean;
+  markCreated(singletonKey: string): void;
+
+  // Buffered node lookup (for metadata updates, e.g., rejection patterns)
+  findBufferedNode(id: string): GraphNode | undefined;
+
+  // Scope-aware variable/parameter resolution (REG-309)
+  findFunctionByName(
+    functions: FunctionInfo[],
+    name: string | undefined,
+    file: string,
+    callScopeId: string
+  ): FunctionInfo | undefined;
+
+  resolveVariableInScope(
+    name: string,
+    scopePath: string[],
+    file: string,
+    variables: VariableDeclarationInfo[]
+  ): VariableDeclarationInfo | null;
+
+  resolveParameterInScope(
+    name: string,
+    scopePath: string[],
+    file: string,
+    parameters: ParameterInfo[]
+  ): ParameterInfo | null;
+
+  scopePathsMatch(a: string[], b: string[]): boolean;
+}
+
+/**
+ * Interface for domain-specific graph builders.
+ * Each builder is responsible for buffering nodes/edges for one domain.
+ */
+export interface DomainBuilder {
+  buffer(module: ModuleNode, data: ASTCollections): void;
+}