@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/src/plugins/enrichment/AliasTracker.ts

@@ -16,6 +16,7 @@
 import { Plugin, createSuccessResult } from '../Plugin.js';
 import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
 import type { BaseNodeRecord, NodeRecord } from '@grafema/types';
+import { StrictModeError } from '../../errors/GrafemaError.js';
 
 /**
  * Alias info from index
@@ -80,13 +81,15 @@ export class AliasTracker extends Plugin {
 
   async execute(context: PluginContext): Promise<PluginResult> {
     const { graph, onProgress } = context;
+    const logger = this.log(context);
 
-    console.log('[AliasTracker] Starting alias resolution...');
+    logger.info('Starting alias resolution');
 
     let callsProcessed = 0;
     let aliasesFound = 0;
     let edgesCreated = 0;
     let resolvedToMethod = 0;
+    const errors: Error[] = [];
 
     // Трекинг превышений глубины
     this.depthExceeded = [];
@@ -105,11 +108,11 @@ export class AliasTracker extends Plugin {
       unresolvedCalls.push(callNode);
     }
 
-    console.log(`[AliasTracker] Found ${unresolvedCalls.length} unresolved call sites`);
+    logger.info('Found unresolved call sites', { count: unresolvedCalls.length });
 
     // 2. Строим индекс алиасов: variableName -> EXPRESSION info
     const aliasIndex = await this.buildAliasIndex(graph);
-    console.log(`[AliasTracker] Found ${aliasIndex.size} potential aliases`);
+    logger.debug('Found potential aliases', { count: aliasIndex.size });
 
     // 3. Строим индекс методов для резолвинга
     const methodIndex = await this.buildMethodIndex(graph);
@@ -182,15 +185,39 @@ export class AliasTracker extends Plugin {
 
     // Алярм если были превышения глубины
     if (this.depthExceeded.length > 0) {
-      console.warn(`[AliasTracker] ⚠️  WARNING: ${this.depthExceeded.length} alias chain(s) exceeded max depth (${AliasTracker.MAX_DEPTH}):`);
-      for (const info of this.depthExceeded) {
-        console.warn(`  - ${info.file}:${info.name} (chain: ${info.chain.join(' → ')}...)`);
+      logger.warn('Alias chains exceeded max depth', {
+        count: this.depthExceeded.length,
+        maxDepth: AliasTracker.MAX_DEPTH,
+        examples: this.depthExceeded.slice(0, 5).map(info => ({
+          file: info.file,
+          name: info.name,
+          chain: info.chain.join(' → ')
+        }))
+      });
+
+      // In strict mode, report as errors
+      if (context.strictMode) {
+        for (const info of this.depthExceeded) {
+          const error = new StrictModeError(
+            `Alias chain exceeded max depth (${info.depth}): ${info.name}`,
+            'STRICT_ALIAS_DEPTH_EXCEEDED',
+            {
+              filePath: info.file,
+              phase: 'ENRICHMENT',
+              plugin: 'AliasTracker',
+              aliasName: info.name,
+              chainLength: info.depth,
+            },
+            `Possible circular alias reference. Chain: ${info.chain.slice(0, 3).join(' -> ')}...`
+          );
+          errors.push(error);
+        }
       }
     }
 
-    console.log('[AliasTracker] Summary:', summary);
+    logger.info('Summary', summary);
 
-    return createSuccessResult({ nodes: 0, edges: edgesCreated }, summary);
+    return createSuccessResult({ nodes: 0, edges: edgesCreated }, summary, errors);
   }
 
   /**

package/src/plugins/enrichment/ArgumentParameterLinker.ts

@@ -0,0 +1,240 @@
+/**
+ * ArgumentParameterLinker - creates RECEIVES_ARGUMENT edges connecting
+ * function parameters to call arguments.
+ *
+ * RECEIVES_ARGUMENT edges connect:
+ *   PARAMETER node -> RECEIVES_ARGUMENT -> argument source (VARIABLE, LITERAL, CALL, etc.)
+ *
+ * This is the inverse of PASSES_ARGUMENT:
+ *   - PASSES_ARGUMENT: CALL -> argument (call site perspective)
+ *   - RECEIVES_ARGUMENT: PARAMETER -> argument (function perspective)
+ *
+ * Edge attributes:
+ *   - argIndex: position of the argument (0-based)
+ *   - callId: ID of the CALL node that passed this argument
+ *
+ * Algorithm:
+ * For each CALL node with PASSES_ARGUMENT edges:
+ *   1. Get outgoing CALLS edge to find target function
+ *   2. If no CALLS edge -> skip (unresolved call)
+ *   3. Get target function's PARAMETER nodes via HAS_PARAMETER edges
+ *   4. For each PASSES_ARGUMENT edge:
+ *      a. Get argIndex from edge metadata
+ *      b. Find PARAMETER with matching index
+ *      c. Create RECEIVES_ARGUMENT edge: PARAMETER -> argument_source
+ */
+
+import { Plugin, createSuccessResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+import { StrictModeError } from '../../errors/GrafemaError.js';
+
+/**
+ * Extended call node type
+ */
+interface CallNode extends BaseNodeRecord {
+  // All properties inherited from BaseNodeRecord
+}
+
+/**
+ * Extended parameter node type
+ */
+interface ParameterNode extends BaseNodeRecord {
+  index?: number;
+}
+
+/**
+ * Edge with metadata for PASSES_ARGUMENT
+ */
+interface PassesArgumentEdge extends EdgeRecord {
+  argIndex?: number;
+  isSpread?: boolean;
+}
+
+/**
+ * Edge record with extended fields for RECEIVES_ARGUMENT lookup
+ */
+interface ExtendedEdgeRecord extends EdgeRecord {
+  callId?: string;
+}
+
+export class ArgumentParameterLinker extends Plugin {
+  get metadata(): PluginMetadata {
+    return {
+      name: 'ArgumentParameterLinker',
+      phase: 'ENRICHMENT',
+      priority: 45, // Runs AFTER MethodCallResolver (50) which creates required CALLS edges
+      creates: {
+        nodes: [],
+        edges: ['RECEIVES_ARGUMENT']
+      },
+      dependencies: ['JSASTAnalyzer', 'MethodCallResolver'] // Requires CALLS edges
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const { graph, onProgress } = context;
+    const logger = this.log(context);
+
+    logger.info('Starting argument-parameter linking');
+
+    const startTime = Date.now();
+
+    let callsProcessed = 0;
+    let edgesCreated = 0;
+    let unresolvedCalls = 0;
+    let noParams = 0;
+    const errors: Error[] = [];
+
+    // Collect all CALL nodes (both CALL and METHOD_CALL via CALL type check)
+    const callNodes: CallNode[] = [];
+    for await (const node of graph.queryNodes({ nodeType: 'CALL' })) {
+      callNodes.push(node as CallNode);
+    }
+
+    logger.info('Found calls to process', { count: callNodes.length });
+
+    // Build a Set of existing RECEIVES_ARGUMENT edges to avoid duplicates
+    // Key: `${paramId}:${dstId}:${callId}`
+    const existingEdges = new Set<string>();
+    for await (const node of graph.queryNodes({ nodeType: 'PARAMETER' })) {
+      const edges = await graph.getOutgoingEdges(node.id, ['RECEIVES_ARGUMENT']) as ExtendedEdgeRecord[];
+      for (const edge of edges) {
+        const callId = edge.callId ?? (edge.metadata?.callId as string | undefined) ?? '';
+        existingEdges.add(`${node.id}:${edge.dst}:${callId}`);
+      }
+    }
+    logger.debug('Found existing RECEIVES_ARGUMENT edges', { count: existingEdges.size });
+
+    for (const callNode of callNodes) {
+      callsProcessed++;
+
+      // Report progress every 100 calls
+      if (onProgress && callsProcessed % 100 === 0) {
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        onProgress({
+          phase: 'enrichment',
+          currentPlugin: 'ArgumentParameterLinker',
+          message: `Linking arguments ${callsProcessed}/${callNodes.length} (${elapsed}s)`,
+          totalFiles: callNodes.length,
+          processedFiles: callsProcessed
+        });
+      }
+
+      // 1. Get PASSES_ARGUMENT edges from this call
+      const passesArgumentEdges = await graph.getOutgoingEdges(callNode.id, ['PASSES_ARGUMENT']);
+      if (passesArgumentEdges.length === 0) {
+        continue; // No arguments passed, skip
+      }
+
+      // 2. Get CALLS edge to find target function
+      const callsEdges = await graph.getOutgoingEdges(callNode.id, ['CALLS']);
+      if (callsEdges.length === 0) {
+        unresolvedCalls++;
+
+        // In strict mode, report unresolved calls that have arguments
+        if (context.strictMode) {
+          const error = new StrictModeError(
+            `Call with arguments has no resolved target: ${callNode.name || callNode.id}`,
+            'STRICT_UNRESOLVED_ARGUMENT',
+            {
+              filePath: callNode.file,
+              lineNumber: callNode.line as number | undefined,
+              phase: 'ENRICHMENT',
+              plugin: 'ArgumentParameterLinker',
+              callId: callNode.id,
+            },
+            `Ensure the called function is imported or defined`
+          );
+          errors.push(error);
+        }
+        continue; // Unresolved call, skip
+      }
+
+      // Get target function node
+      const targetFunctionId = callsEdges[0].dst;
+      const targetFunction = await graph.getNode(targetFunctionId);
+      if (!targetFunction) {
+        unresolvedCalls++;
+        continue;
+      }
+
+      // 3. Get target function's PARAMETER nodes via HAS_PARAMETER edges
+      const hasParameterEdges = await graph.getOutgoingEdges(targetFunctionId, ['HAS_PARAMETER']);
+      if (hasParameterEdges.length === 0) {
+        noParams++;
+        continue; // Function has no parameters
+      }
+
+      // Build parameter index map: argIndex -> paramNode
+      const paramsByIndex = new Map<number, ParameterNode>();
+      for (const paramEdge of hasParameterEdges) {
+        const paramNode = await graph.getNode(paramEdge.dst) as ParameterNode | null;
+        if (paramNode && typeof paramNode.index === 'number') {
+          paramsByIndex.set(paramNode.index, paramNode);
+        }
+      }
+
+      if (paramsByIndex.size === 0) {
+        noParams++;
+        continue;
+      }
+
+      // 4. For each PASSES_ARGUMENT edge, create RECEIVES_ARGUMENT edge
+      for (const passesEdge of passesArgumentEdges as PassesArgumentEdge[]) {
+        // Get argIndex from edge (can be top-level or in metadata)
+        const argIndex = passesEdge.argIndex ?? (passesEdge.metadata?.argIndex as number | undefined);
+        if (argIndex === undefined) {
+          continue; // No argIndex, skip
+        }
+
+        // Find matching parameter
+        const paramNode = paramsByIndex.get(argIndex);
+        if (!paramNode) {
+          continue; // No parameter for this argument index (extra arg)
+        }
+
+        // Check for duplicate
+        const edgeKey = `${paramNode.id}:${passesEdge.dst}:${callNode.id}`;
+        if (existingEdges.has(edgeKey)) {
+          continue; // Already exists
+        }
+
+        // Create RECEIVES_ARGUMENT edge: PARAMETER -> argument_source
+        await graph.addEdge({
+          type: 'RECEIVES_ARGUMENT',
+          src: paramNode.id,
+          dst: passesEdge.dst,
+          metadata: {
+            argIndex,
+            callId: callNode.id
+          }
+        });
+
+        existingEdges.add(edgeKey);
+        edgesCreated++;
+      }
+    }
+
+    const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+    logger.info('Complete', {
+      callsProcessed,
+      edgesCreated,
+      unresolvedCalls,
+      noParams,
+      time: `${totalTime}s`
+    });
+
+    return createSuccessResult(
+      { nodes: 0, edges: edgesCreated },
+      {
+        callsProcessed,
+        edgesCreated,
+        unresolvedCalls,
+        noParams,
+        timeMs: Date.now() - startTime
+      },
+      errors
+    );
+  }
+}

package/src/plugins/enrichment/ClosureCaptureEnricher.ts

@@ -0,0 +1,267 @@
+/**
+ * ClosureCaptureEnricher - tracks transitive closure captures
+ *
+ * Problem: CAPTURES edges only exist for immediate parent scope (depth=1).
+ * Multi-level captures (grandparent, great-grandparent) are not tracked.
+ *
+ * Solution: Walk scope chains upward to find ALL captured variables,
+ * creating CAPTURES edges with depth metadata.
+ *
+ * USES:
+ * - SCOPE nodes with scopeType='closure'
+ * - SCOPE.parentScopeId for scope chain navigation
+ * - VARIABLE nodes with parentScopeId
+ * - CONSTANT nodes with parentScopeId
+ * - PARAMETER nodes with parentFunctionId (resolved via HAS_SCOPE)
+ *
+ * CREATES:
+ * - SCOPE -> CAPTURES -> VARIABLE/CONSTANT/PARAMETER (with metadata: { depth: N })
+ *
+ * NOTE: Depth=1 edges are created by JSASTAnalyzer without depth metadata.
+ * This enricher only creates edges for depth > 1.
+ */
+
+import { Plugin, createSuccessResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ScopeNode extends BaseNodeRecord {
+  scopeType?: string;
+  parentScopeId?: string;
+  capturesFrom?: string;
+}
+
+interface VariableNode extends BaseNodeRecord {
+  parentScopeId?: string;
+}
+
+interface ParameterNode extends BaseNodeRecord {
+  parentFunctionId?: string;
+}
+
+interface ScopeChainEntry {
+  scopeId: string;
+  depth: number;
+}
+
+export class ClosureCaptureEnricher extends Plugin {
+  static MAX_DEPTH = 10;
+
+  get metadata(): PluginMetadata {
+    return {
+      name: 'ClosureCaptureEnricher',
+      phase: 'ENRICHMENT',
+      priority: 40, // Lower number = runs later. Runs after ImportExportLinker (90)
+      creates: {
+        nodes: [],
+        edges: ['CAPTURES']
+      },
+      dependencies: ['JSASTAnalyzer'] // Requires SCOPE and VARIABLE nodes
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const { graph, onProgress } = context;
+    const logger = this.log(context);
+
+    logger.info('Starting transitive capture resolution');
+
+    let closuresProcessed = 0;
+    let capturesCreated = 0;
+    let existingCapturesSkipped = 0;
+
+    // Step 1: Build scope index for fast lookup
+    const scopeIndex = await this.buildScopeIndex(graph);
+    logger.debug('Indexed scopes', { count: scopeIndex.size });
+
+    // Step 2: Build variable index (scopeId -> variables/constants/parameters)
+    const variablesByScopeIndex = await this.buildVariablesByScopeIndex(graph);
+    logger.debug('Indexed variables by scope', { scopes: variablesByScopeIndex.size });
+
+    // Step 3: Find all closure scopes
+    const closureScopes: ScopeNode[] = [];
+    for await (const node of graph.queryNodes({ type: 'SCOPE' })) {
+      const scope = node as ScopeNode;
+      if (scope.scopeType === 'closure') {
+        closureScopes.push(scope);
+      }
+    }
+
+    logger.info('Found closure scopes', { count: closureScopes.length });
+
+    // Step 4: Build existing CAPTURES edge set to avoid duplicates
+    const existingCaptures = await this.buildExistingCapturesSet(graph);
+    logger.debug('Existing CAPTURES edges', { count: existingCaptures.size });
+
+    // Step 5: Process each closure
+    for (const closure of closureScopes) {
+      closuresProcessed++;
+
+      // Progress reporting
+      if (onProgress && closuresProcessed % 50 === 0) {
+        onProgress({
+          phase: 'enrichment',
+          currentPlugin: 'ClosureCaptureEnricher',
+          message: `Processing closures ${closuresProcessed}/${closureScopes.length}`,
+          totalFiles: closureScopes.length,
+          processedFiles: closuresProcessed
+        });
+      }
+
+      // Walk scope chain upward
+      const ancestors = this.walkScopeChain(closure.id, scopeIndex);
+
+      // For each ancestor scope (depth > 1), find variables and create edges
+      for (const ancestor of ancestors) {
+        if (ancestor.depth <= 1) continue; // Skip immediate parent (already handled by JSASTAnalyzer)
+
+        const variables = variablesByScopeIndex.get(ancestor.scopeId) || [];
+
+        for (const variable of variables) {
+          const edgeKey = `${closure.id}:${variable.id}`;
+
+          if (existingCaptures.has(edgeKey)) {
+            existingCapturesSkipped++;
+            continue;
+          }
+
+          await graph.addEdge({
+            src: closure.id,
+            dst: variable.id,
+            type: 'CAPTURES',
+            metadata: { depth: ancestor.depth }
+          });
+
+          capturesCreated++;
+          existingCaptures.add(edgeKey); // Track to avoid duplicates
+        }
+      }
+    }
+
+    const summary = {
+      closuresProcessed,
+      capturesCreated,
+      existingCapturesSkipped
+    };
+
+    logger.info('Summary', summary);
+
+    return createSuccessResult({ nodes: 0, edges: capturesCreated }, summary);
+  }
+
+  /**
+   * Build index: scopeId -> ScopeNode
+   */
+  private async buildScopeIndex(graph: PluginContext['graph']): Promise<Map<string, ScopeNode>> {
+    const index = new Map<string, ScopeNode>();
+
+    for await (const node of graph.queryNodes({ type: 'SCOPE' })) {
+      index.set(node.id, node as ScopeNode);
+    }
+
+    return index;
+  }
+
+  /**
+   * Build index: scopeId -> VariableNode[]
+   * Includes VARIABLE, CONSTANT, and PARAMETER nodes
+   */
+  private async buildVariablesByScopeIndex(graph: PluginContext['graph']): Promise<Map<string, VariableNode[]>> {
+    const index = new Map<string, VariableNode[]>();
+
+    // Index VARIABLE nodes via parentScopeId
+    for await (const node of graph.queryNodes({ type: 'VARIABLE' })) {
+      const variable = node as VariableNode;
+      if (!variable.parentScopeId) continue;
+
+      const vars = index.get(variable.parentScopeId) || [];
+      vars.push(variable);
+      index.set(variable.parentScopeId, vars);
+    }
+
+    // Index CONSTANT nodes via parentScopeId
+    for await (const node of graph.queryNodes({ type: 'CONSTANT' })) {
+      const constant = node as VariableNode;
+      if (!constant.parentScopeId) continue;
+
+      const vars = index.get(constant.parentScopeId) || [];
+      vars.push(constant);
+      index.set(constant.parentScopeId, vars);
+    }
+
+    // Index PARAMETER nodes via parentFunctionId -> HAS_SCOPE lookup
+    for await (const node of graph.queryNodes({ type: 'PARAMETER' })) {
+      const param = node as ParameterNode;
+      if (!param.parentFunctionId) continue;
+
+      // Find the function's scope via HAS_SCOPE edge
+      // FUNCTION -[HAS_SCOPE]-> SCOPE
+      const scopeEdges = await graph.getOutgoingEdges(param.parentFunctionId, ['HAS_SCOPE']);
+      if (scopeEdges.length === 0) continue;
+
+      const scopeId = scopeEdges[0].dst;
+      const params = index.get(scopeId) || [];
+      params.push(param as unknown as VariableNode);
+      index.set(scopeId, params);
+    }
+
+    return index;
+  }
+
+  /**
+   * Build set of existing CAPTURES edges: "srcId:dstId"
+   */
+  private async buildExistingCapturesSet(graph: PluginContext['graph']): Promise<Set<string>> {
+    const set = new Set<string>();
+
+    // Query all SCOPE nodes and get their CAPTURES edges
+    for await (const node of graph.queryNodes({ type: 'SCOPE' })) {
+      const edges = await graph.getOutgoingEdges(node.id, ['CAPTURES']);
+      for (const edge of edges) {
+        set.add(`${edge.src}:${edge.dst}`);
+      }
+    }
+
+    return set;
+  }
+
+  /**
+   * Walk scope chain upward from startScopeId
+   * Returns ancestor scopes with depth (1 = immediate parent, 2 = grandparent, etc.)
+   *
+   * Walks ALL scopes in the chain (including if/for/while blocks),
+   * not just closures.
+   */
+  private walkScopeChain(
+    startScopeId: string,
+    scopeIndex: Map<string, ScopeNode>
+  ): ScopeChainEntry[] {
+    const result: ScopeChainEntry[] = [];
+    const visited = new Set<string>();
+
+    const currentScope = scopeIndex.get(startScopeId);
+    if (!currentScope) return result;
+
+    // Start walking from the closure's capturesFrom (immediate parent) or parentScopeId
+    let parentId = currentScope.capturesFrom || currentScope.parentScopeId;
+    let depth = 1;
+
+    while (parentId && depth <= ClosureCaptureEnricher.MAX_DEPTH) {
+      // Cycle protection
+      if (visited.has(parentId)) break;
+      visited.add(parentId);
+
+      result.push({ scopeId: parentId, depth });
+
+      // Get parent scope
+      const parentScope = scopeIndex.get(parentId);
+      if (!parentScope) break;
+
+      // Move up the chain via parentScopeId
+      parentId = parentScope.parentScopeId;
+      depth++;
+    }
+
+    return result;
+  }
+}