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

package/src/plugins/analysis/ast/visitors/FunctionVisitor.ts

@@ -11,43 +11,29 @@ import type {
   Function,
   FunctionDeclaration,
   ArrowFunctionExpression,
+  FunctionExpression,
   Identifier,
   AssignmentPattern,
   RestElement,
-  VariableDeclarator
+  VariableDeclarator,
+  Comment,
+  NewExpression
 } from '@babel/types';
 import type { NodePath } from '@babel/traverse';
 import { ASTVisitor, type VisitorModule, type VisitorCollections, type VisitorHandlers, type CounterRef } from './ASTVisitor.js';
-
-/**
- * Scope context for generating stable semantic IDs
- */
-interface ScopeContext {
-  semanticPath: string;
-  siblingCounters: Map<string, number>;
-}
-
-/**
- * Parameter node info
- */
-interface ParameterInfo {
-  id: string;
-  type: 'PARAMETER';
-  name: string;
-  file: string;
-  line: number;
-  index: number;
-  hasDefault?: boolean;
-  isRest?: boolean;
-  parentFunctionId: string;
-}
+import { typeNodeToString } from './TypeScriptVisitor.js';
+import { ScopeTracker } from '../../../../core/ScopeTracker.js';
+import { IdGenerator } from '../IdGenerator.js';
+import { createParameterNodes } from '../utils/createParameterNodes.js';
+import { getLine, getColumn } from '../utils/location.js';
+import type { ParameterInfo, PromiseExecutorContext } from '../types.js';
+import { ConstructorCallNode } from '../../../../core/nodes/ConstructorCallNode.js';
 
 /**
  * Function node info
  */
 interface FunctionInfo {
   id: string;
-  stableId: string;
   type: 'FUNCTION';
   name: string;
   file: string;
@@ -56,6 +42,11 @@ interface FunctionInfo {
   async: boolean;
   generator?: boolean;
   arrowFunction?: boolean;
+  params?: string[];
+  paramTypes?: string[];
+  returnType?: string;
+  signature?: string;
+  jsdocSummary?: string;
 }
 
 /**
@@ -84,19 +75,23 @@ export type AnalyzeFunctionBodyCallback = (
 
 export class FunctionVisitor extends ASTVisitor {
   private analyzeFunctionBody: AnalyzeFunctionBodyCallback;
+  private scopeTracker: ScopeTracker;
 
   /**
    * @param module - Current module being analyzed
    * @param collections - Must contain arrays and counter refs
    * @param analyzeFunctionBody - Callback to analyze function internals
+   * @param scopeTracker - REQUIRED for semantic ID generation
    */
   constructor(
     module: VisitorModule,
     collections: VisitorCollections,
-    analyzeFunctionBody: AnalyzeFunctionBodyCallback
+    analyzeFunctionBody: AnalyzeFunctionBodyCallback,
+    scopeTracker: ScopeTracker
   ) {
     super(module, collections);
     this.analyzeFunctionBody = analyzeFunctionBody;
+    this.scopeTracker = scopeTracker;
   }
 
   getHandlers(): VisitorHandlers {
@@ -105,76 +100,109 @@ export class FunctionVisitor extends ASTVisitor {
     const parameters = this.collections.parameters ?? [];
     const scopes = this.collections.scopes ?? [];
     const functionCounterRef = (this.collections.functionCounterRef ?? { value: 0 }) as CounterRef;
-    const moduleScopeCtx = this.collections.moduleScopeCtx as ScopeContext | undefined;
+    const scopeTracker = this.scopeTracker;
 
     const analyzeFunctionBody = this.analyzeFunctionBody;
     const collections = this.collections;
 
     // Helper function to generate stable anonymous function name
     const generateAnonymousName = (): string => {
-      if (!moduleScopeCtx) return 'anonymous';
-      const index = moduleScopeCtx.siblingCounters.get('anonymous') || 0;
-      moduleScopeCtx.siblingCounters.set('anonymous', index + 1);
+      const index = scopeTracker.getSiblingIndex('anonymous');
       return `anonymous[${index}]`;
     };
 
-    // Helper function to create PARAMETER nodes for function params
-    const createParameterNodes = (
-      params: Node[],
-      functionId: string,
-      file: string,
-      line: number
-    ): void => {
-      if (!parameters) return; // Guard for backward compatibility
-
-      params.forEach((param, index) => {
-        // Handle different parameter types
+    // Helper function to extract parameter names and types from function params
+    const extractParamInfo = (params: Node[]): { names: string[]; types: string[] } => {
+      const names: string[] = [];
+      const types: string[] = [];
+
+      params.forEach((param) => {
         if (param.type === 'Identifier') {
-          const paramId = `PARAMETER#${param.name}#${file}#${line}:${index}`;
-          (parameters as ParameterInfo[]).push({
-            id: paramId,
-            type: 'PARAMETER',
-            name: param.name,
-            file: file,
-            line: param.loc?.start.line || line,
-            index: index,
-            parentFunctionId: functionId
-          });
+          const id = param as Identifier;
+          names.push(id.name);
+          // Check for type annotation
+          const typeAnnotation = (id as any).typeAnnotation?.typeAnnotation;
+          types.push(typeAnnotation ? typeNodeToString(typeAnnotation) : 'any');
         } else if (param.type === 'AssignmentPattern') {
-          // Default parameter: function(a = 1)
           const assignmentParam = param as AssignmentPattern;
           if (assignmentParam.left.type === 'Identifier') {
-            const paramId = `PARAMETER#${assignmentParam.left.name}#${file}#${line}:${index}`;
-            (parameters as ParameterInfo[]).push({
-              id: paramId,
-              type: 'PARAMETER',
-              name: assignmentParam.left.name,
-              file: file,
-              line: assignmentParam.left.loc?.start.line || line,
-              index: index,
-              hasDefault: true,
-              parentFunctionId: functionId
-            });
+            const id = assignmentParam.left as Identifier;
+            names.push(id.name + '?');
+            const typeAnnotation = (id as any).typeAnnotation?.typeAnnotation;
+            types.push(typeAnnotation ? typeNodeToString(typeAnnotation) : 'any');
           }
-        } else if ((param as Node).type === 'RestElement') {
-          // Rest parameter: function(...args)
+        } else if (param.type === 'RestElement') {
           const restParam = param as unknown as RestElement;
           if (restParam.argument.type === 'Identifier') {
-            const paramId = `PARAMETER#${restParam.argument.name}#${file}#${line}:${index}`;
-            (parameters as ParameterInfo[]).push({
-              id: paramId,
-              type: 'PARAMETER',
-              name: restParam.argument.name,
-              file: file,
-              line: restParam.argument.loc?.start.line || line,
-              index: index,
-              isRest: true,
-              parentFunctionId: functionId
-            });
+            const id = restParam.argument as Identifier;
+            names.push('...' + id.name);
+            const typeAnnotation = (id as any).typeAnnotation?.typeAnnotation;
+            types.push(typeAnnotation ? typeNodeToString(typeAnnotation) : 'any[]');
           }
         }
-        // ObjectPattern and ArrayPattern (destructuring parameters) can be added later
       });
+
+      return { names, types };
+    };
+
+    // Helper function to extract return type from function
+    const extractReturnType = (node: Function): string => {
+      const returnTypeAnnotation = (node as any).returnType?.typeAnnotation;
+      if (returnTypeAnnotation) {
+        return typeNodeToString(returnTypeAnnotation);
+      }
+      return 'void';
+    };
+
+    // Helper function to extract JSDoc summary from leading comments
+    const extractJsdocSummary = (node: Node): string | undefined => {
+      const comments = node.leadingComments as Comment[] | null | undefined;
+      if (!comments || comments.length === 0) return undefined;
+
+      // Find the last block comment that looks like JSDoc
+      for (let i = comments.length - 1; i >= 0; i--) {
+        const comment = comments[i];
+        if (comment.type === 'CommentBlock' && comment.value.startsWith('*')) {
+          // Parse JSDoc - get first non-empty line after the opening
+          const lines = comment.value.split('\n');
+          for (const line of lines) {
+            const trimmed = line.replace(/^\s*\*\s?/, '').trim();
+            // Skip empty lines and @tags
+            if (trimmed && !trimmed.startsWith('@')) {
+              return trimmed.slice(0, 200); // Limit length
+            }
+          }
+        }
+      }
+      return undefined;
+    };
+
+    // Helper function to build function signature
+    const buildSignature = (
+      params: string[],
+      paramTypes: string[],
+      returnType: string,
+      isAsync: boolean
+    ): string => {
+      const paramParts = params.map((name, i) => {
+        const type = paramTypes[i] || 'any';
+        // Handle rest params
+        if (name.startsWith('...')) {
+          return `${name}: ${type}`;
+        }
+        // Handle optional params (with ?)
+        if (name.endsWith('?')) {
+          return `${name}: ${type}`;
+        }
+        return `${name}: ${type}`;
+      });
+
+      const paramsStr = `(${paramParts.join(', ')})`;
+      const retStr = isAsync && !returnType.startsWith('Promise')
+        ? `Promise<${returnType}>`
+        : returnType;
+
+      return `${paramsStr} => ${retStr}`;
     };
 
     return {
@@ -183,24 +211,43 @@ export class FunctionVisitor extends ASTVisitor {
         const node = path.node as FunctionDeclaration;
         if (!node.id) return; // Skip anonymous function declarations
 
-        const functionId = `FUNCTION#${node.id.name}#${module.file}#${node.loc!.start.line}`;
+        const isAsync = node.async || false;
+
+        const line = getLine(node);
+
+        // Generate ID using centralized IdGenerator
+        const idGenerator = new IdGenerator(scopeTracker);
+        const functionId = idGenerator.generateSimple('FUNCTION', node.id.name, module.file, line);
+
+        // Extract type info
+        const { names: paramNames, types: paramTypes } = extractParamInfo(node.params);
+        const returnType = extractReturnType(node);
+        const jsdocSummary = extractJsdocSummary(node);
+        const signature = buildSignature(paramNames, paramTypes, returnType, isAsync);
 
         (functions as FunctionInfo[]).push({
           id: functionId,
-          stableId: functionId,
           type: 'FUNCTION',
           name: node.id.name,
           file: module.file,
-          line: node.loc!.start.line,
-          async: node.async || false,
-          generator: node.generator || false
+          line,
+          async: isAsync,
+          generator: node.generator || false,
+          params: paramNames,
+          paramTypes,
+          returnType,
+          signature,
+          jsdocSummary
         });
 
+        // Enter function scope BEFORE creating parameters (semantic IDs need function context)
+        scopeTracker.enterScope(node.id.name, 'FUNCTION');
+
         // Create PARAMETER nodes for function parameters
-        createParameterNodes(node.params, functionId, module.file, node.loc!.start.line);
+        createParameterNodes(node.params, functionId, module.file, getLine(node), parameters as ParameterInfo[], scopeTracker);
 
         // Create SCOPE for function body
-        const functionBodyScopeId = `SCOPE#${node.id.name}:body#${module.file}#${node.loc!.start.line}`;
+        const functionBodyScopeId = idGenerator.generateScope('body', `${node.id.name}:body`, module.file, line);
         (scopes as ScopeInfo[]).push({
           id: functionBodyScopeId,
           type: 'SCOPE',
@@ -208,13 +255,16 @@ export class FunctionVisitor extends ASTVisitor {
           name: `${node.id.name}:body`,
           conditional: false,
           file: module.file,
-          line: node.loc!.start.line,
+          line,
           parentFunctionId: functionId
         });
 
         // Analyze function body
         analyzeFunctionBody(path as NodePath<FunctionDeclaration>, functionBodyScopeId, module, collections);
 
+        // Exit function scope
+        scopeTracker.exitScope();
+
         // Stop traversal - analyzeFunctionBody already processed contents
         path.skip();
       },
@@ -222,8 +272,9 @@ export class FunctionVisitor extends ASTVisitor {
       // Arrow functions (module-level, assigned to variables or as callbacks)
       ArrowFunctionExpression: (path: NodePath) => {
         const node = path.node as ArrowFunctionExpression;
-        const line = node.loc!.start.line;
-        const column = node.loc!.start.column;
+        const line = getLine(node);
+        const column = getColumn(node);
+        const isAsync = node.async || false;
 
         // Determine arrow function name (use scope-level counter for stable semanticId)
         let functionName = generateAnonymousName();
@@ -237,25 +288,40 @@ export class FunctionVisitor extends ASTVisitor {
           }
         }
 
-        const functionId = `FUNCTION#${functionName}#${module.file}#${line}:${column}:${functionCounterRef.value++}`;
+        // Generate ID using centralized IdGenerator
+        const idGenerator = new IdGenerator(scopeTracker);
+        const functionId = idGenerator.generate('FUNCTION', functionName, module.file, line, column, functionCounterRef);
+
+        // Extract type info
+        const { names: paramNames, types: paramTypes } = extractParamInfo(node.params);
+        const returnType = extractReturnType(node);
+        const jsdocSummary = extractJsdocSummary(node);
+        const signature = buildSignature(paramNames, paramTypes, returnType, isAsync);
 
         (functions as FunctionInfo[]).push({
           id: functionId,
-          stableId: functionId,
           type: 'FUNCTION',
           name: functionName,
           file: module.file,
           line,
           column,
-          async: node.async || false,
-          arrowFunction: true
+          async: isAsync,
+          arrowFunction: true,
+          params: paramNames,
+          paramTypes,
+          returnType,
+          signature,
+          jsdocSummary
         });
 
+        // Enter function scope BEFORE creating parameters (semantic IDs need function context)
+        scopeTracker.enterScope(functionName, 'FUNCTION');
+
         // Create PARAMETER nodes for arrow function parameters
-        createParameterNodes(node.params, functionId, module.file, line);
+        createParameterNodes(node.params, functionId, module.file, line, parameters as ParameterInfo[], scopeTracker);
 
         // Create SCOPE for arrow function body
-        const bodyScope = `SCOPE#${functionName}:body#${module.file}#${line}:${column}`;
+        const bodyScope = idGenerator.generateScope('body', `${functionName}:body`, module.file, line, column);
         (scopes as ScopeInfo[]).push({
           id: bodyScope,
           type: 'SCOPE',
@@ -266,8 +332,83 @@ export class FunctionVisitor extends ASTVisitor {
           parentFunctionId: functionId
         });
 
+        // REG-334: Detect Promise executor context BEFORE analyzing body
+        // This must happen before analyzeFunctionBody so resolve/reject calls can be linked
+        this.detectPromiseExecutorContext(path, node, module, collections);
+
         analyzeFunctionBody(path as NodePath<ArrowFunctionExpression>, bodyScope, module, collections);
+
+        // Exit function scope
+        scopeTracker.exitScope();
+
+        // Stop traversal - analyzeFunctionBody already processed contents
+        // Without this, babel traverse continues into arrow body and finds
+        // nested arrow functions, causing duplicate FUNCTION nodes
+        path.skip();
       }
     };
   }
+
+  /**
+   * REG-334: Detect if this function is a Promise executor callback.
+   * If so, register the context so resolve/reject calls can be linked.
+   *
+   * Pattern: new Promise((resolve, reject) => { ... })
+   *
+   * Must be called BEFORE analyzeFunctionBody so the context is available
+   * when resolve/reject calls are processed.
+   */
+  private detectPromiseExecutorContext(
+    path: NodePath,
+    node: ArrowFunctionExpression | FunctionExpression,
+    module: VisitorModule,
+    collections: VisitorCollections
+  ): void {
+    // Check if this function is the first argument to new Promise()
+    const parent = path.parent;
+    if (parent?.type !== 'NewExpression') return;
+
+    const newExpr = parent as NewExpression;
+
+    // Check it's Promise constructor
+    if (newExpr.callee.type !== 'Identifier') return;
+    if ((newExpr.callee as Identifier).name !== 'Promise') return;
+
+    // Check this function is the first argument
+    if (newExpr.arguments.length === 0) return;
+    if (newExpr.arguments[0] !== node) return;
+
+    // Extract resolve/reject parameter names
+    let resolveName: string | undefined;
+    let rejectName: string | undefined;
+
+    if (node.params.length > 0 && node.params[0].type === 'Identifier') {
+      resolveName = (node.params[0] as Identifier).name;
+    }
+    if (node.params.length > 1 && node.params[1].type === 'Identifier') {
+      rejectName = (node.params[1] as Identifier).name;
+    }
+
+    if (!resolveName) return; // No resolve parameter, nothing to track
+
+    // Generate the CONSTRUCTOR_CALL ID for linking
+    const line = getLine(newExpr);
+    const column = getColumn(newExpr);
+    const constructorCallId = ConstructorCallNode.generateId('Promise', module.file, line, column);
+
+    // Initialize promiseExecutorContexts if not exists
+    if (!collections.promiseExecutorContexts) {
+      collections.promiseExecutorContexts = new Map<string, PromiseExecutorContext>();
+    }
+
+    // Key by function node position to allow nested Promise detection
+    const funcKey = `${node.start}:${node.end}`;
+    (collections.promiseExecutorContexts as Map<string, PromiseExecutorContext>).set(funcKey, {
+      constructorCallId,
+      resolveName,
+      rejectName,
+      file: module.file,
+      line: getLine(node)
+    });
+  }
 }

package/src/plugins/analysis/ast/visitors/ImportExportVisitor.ts

@@ -21,11 +21,14 @@ import type {
   FunctionDeclaration,
   ClassDeclaration,
   Identifier,
-  Node
+  Node,
+  CallExpression,
+  TemplateLiteral
 } from '@babel/types';
 import type { NodePath } from '@babel/traverse';
 import { ASTVisitor, type VisitorModule, type VisitorCollections, type VisitorHandlers } from './ASTVisitor.js';
 import type { VariableInfo } from './VariableVisitor.js';
+import { getLine, getColumn } from '../utils/location.js';
 
 /**
  * Callback type for extracting variable names from patterns
@@ -47,6 +50,10 @@ interface ImportInfo {
   source: string;
   specifiers: ImportSpecifierInfo[];
   line: number;
+  column?: number;
+  isDynamic?: boolean;         // true for dynamic import() expressions
+  isResolvable?: boolean;      // true if path is a string literal (statically analyzable)
+  dynamicPath?: string;        // original expression for template/variable paths
 }
 
 /**
@@ -127,12 +134,119 @@ export class ImportExportVisitor extends ASTVisitor {
         (imports as ImportInfo[]).push({
           source,
           specifiers,
-          line: node.loc!.start.line
+          line: getLine(node),
+          column: getColumn(node)
+        });
+      },
+
+      /**
+       * Handle dynamic import() expressions
+       * Examples:
+       * - import('./module.js')                    -> isResolvable: true
+       * - import(`./plugins/${name}.js`)           -> isResolvable: false, source: './plugins/'
+       * - import(modulePath)                       -> isResolvable: false, source: '<dynamic>'
+       */
+      CallExpression: (path: NodePath) => {
+        const node = path.node as CallExpression;
+
+        // Check if this is an import() call
+        if (node.callee.type !== 'Import') {
+          return;
+        }
+
+        const arg = node.arguments[0];
+        if (!arg) return;
+
+        let source: string;
+        let isResolvable: boolean;
+        let dynamicPath: string | undefined;
+
+        if (arg.type === 'StringLiteral') {
+          // import('./module.js') - literal path, fully resolvable
+          source = arg.value;
+          isResolvable = true;
+        } else if (arg.type === 'TemplateLiteral') {
+          // import(`./plugins/${name}.js`) - template literal
+          const templateArg = arg as TemplateLiteral;
+          const firstQuasi = templateArg.quasis[0];
+
+          // Extract static prefix (part before first expression)
+          const prefix = firstQuasi?.value?.raw || '';
+
+          if (prefix) {
+            source = prefix;
+          } else {
+            // No static prefix - e.g., import(`${baseDir}/loader.js`)
+            source = '<dynamic>';
+          }
+
+          isResolvable = false;
+          // Capture the original template for debugging/analysis
+          dynamicPath = this.templateLiteralToString(templateArg);
+        } else if (arg.type === 'Identifier') {
+          // import(modulePath) - variable path
+          source = '<dynamic>';
+          isResolvable = false;
+          dynamicPath = (arg as Identifier).name;
+        } else {
+          // Other expressions (e.g., function calls, member expressions)
+          source = '<dynamic>';
+          isResolvable = false;
+        }
+
+        // Find the receiving variable name from parent
+        // Patterns: const mod = await import(...) or const mod = import(...)
+        let localName = '*';  // Default for side-effect imports
+        const parent = path.parent;
+
+        if (parent?.type === 'AwaitExpression') {
+          // const mod = await import(...)
+          const awaitParent = path.parentPath?.parent;
+          if (awaitParent?.type === 'VariableDeclarator' &&
+              awaitParent.id?.type === 'Identifier') {
+            localName = awaitParent.id.name;
+          }
+        } else if (parent?.type === 'VariableDeclarator' &&
+                   parent.id?.type === 'Identifier') {
+          // const mod = import(...) (without await)
+          localName = parent.id.name;
+        }
+
+        (imports as ImportInfo[]).push({
+          source,
+          specifiers: [{
+            imported: '*',  // Dynamic imports are always namespace imports
+            local: localName
+          }],
+          line: getLine(node),
+          column: getColumn(node),
+          isDynamic: true,
+          isResolvable,
+          dynamicPath
         });
       }
     };
   }
 
+  /**
+   * Convert a TemplateLiteral to a string representation for debugging
+   */
+  private templateLiteralToString(template: TemplateLiteral): string {
+    let result = '';
+    for (let i = 0; i < template.quasis.length; i++) {
+      result += template.quasis[i].value.raw;
+      if (i < template.expressions.length) {
+        const expr = template.expressions[i];
+        if (expr.type === 'Identifier') {
+          result += `\${${expr.name}}`;
+        } else {
+          result += '${...}';
+        }
+      }
+    }
+    return result;
+  }
+
   getExportHandlers(): VisitorHandlers {
     const { exports } = this.collections;
     const extractVariableNamesFromPattern = this.extractVariableNamesFromPattern;
@@ -143,13 +257,14 @@ export class ImportExportVisitor extends ASTVisitor {
 
         (exports as ExportInfo[]).push({
           type: 'default',
-          line: node.loc!.start.line,
+          line: getLine(node),
           declaration: node.declaration
         });
       },
 
       ExportNamedDeclaration: (path: NodePath) => {
         const node = path.node as ExportNamedDeclaration;
+        const exportLine = getLine(node);
 
         // export { foo, bar } from './module'
         if (node.source) {
@@ -169,7 +284,7 @@ export class ImportExportVisitor extends ASTVisitor {
 
           (exports as ExportInfo[]).push({
             type: 'named',
-            line: node.loc!.start.line,
+            line: exportLine,
             specifiers,
             source: node.source.value
           });
@@ -189,7 +304,7 @@ export class ImportExportVisitor extends ASTVisitor {
 
           (exports as ExportInfo[]).push({
             type: 'named',
-            line: node.loc!.start.line,
+            line: exportLine,
             specifiers
           });
         }
@@ -203,7 +318,7 @@ export class ImportExportVisitor extends ASTVisitor {
             if (funcDecl.id) {
               (exports as ExportInfo[]).push({
                 type: 'named',
-                line: node.loc!.start.line,
+                line: exportLine,
                 name: funcDecl.id.name
               });
             }
@@ -217,7 +332,7 @@ export class ImportExportVisitor extends ASTVisitor {
               variables.forEach((varInfo: VariableInfo) => {
                 (exports as ExportInfo[]).push({
                   type: 'named',
-                  line: node.loc!.start.line,
+                  line: exportLine,
                   name: varInfo.name
                 });
               });
@@ -229,7 +344,7 @@ export class ImportExportVisitor extends ASTVisitor {
             if (classDecl.id) {
               (exports as ExportInfo[]).push({
                 type: 'named',
-                line: node.loc!.start.line,
+                line: exportLine,
                 name: classDecl.id.name
               });
             }
@@ -243,7 +358,7 @@ export class ImportExportVisitor extends ASTVisitor {
         // export * from './module'
         (exports as ExportInfo[]).push({
           type: 'all',
-          line: node.loc!.start.line,
+          line: getLine(node),
           source: node.source.value
         });
       }