@grafema/core 0.1.0-alpha.5 → 0.1.1-alpha

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

@@ -14,40 +14,23 @@ import type {
   Identifier,
   AssignmentPattern,
   RestElement,
-  VariableDeclarator
+  VariableDeclarator,
+  Comment
 } 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 } from '../types.js';
 
 /**
  * Function node info
  */
 interface FunctionInfo {
   id: string;
-  stableId: string;
   type: 'FUNCTION';
   name: string;
   file: string;
@@ -56,6 +39,11 @@ interface FunctionInfo {
   async: boolean;
   generator?: boolean;
   arrowFunction?: boolean;
+  params?: string[];
+  paramTypes?: string[];
+  returnType?: string;
+  signature?: string;
+  jsdocSummary?: string;
 }
 
 /**
@@ -84,19 +72,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 +97,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 +208,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 +252,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 +269,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 +285,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',
@@ -267,6 +330,9 @@ export class FunctionVisitor extends ASTVisitor {
         });
 
         analyzeFunctionBody(path as NodePath<ArrowFunctionExpression>, bodyScope, module, collections);
+
+        // Exit function scope
+        scopeTracker.exitScope();
       }
     };
   }

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

@@ -26,6 +26,7 @@ import type {
 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 +48,7 @@ interface ImportInfo {
   source: string;
   specifiers: ImportSpecifierInfo[];
   line: number;
+  column?: number;
 }
 
 /**
@@ -127,7 +129,8 @@ export class ImportExportVisitor extends ASTVisitor {
         (imports as ImportInfo[]).push({
           source,
           specifiers,
-          line: node.loc!.start.line
+          line: getLine(node),
+          column: getColumn(node)
         });
       }
     };
@@ -143,13 +146,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 +173,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 +193,7 @@ export class ImportExportVisitor extends ASTVisitor {
 
           (exports as ExportInfo[]).push({
             type: 'named',
-            line: node.loc!.start.line,
+            line: exportLine,
             specifiers
           });
         }
@@ -203,7 +207,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 +221,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 +233,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 +247,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
         });
       }

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

@@ -26,11 +26,14 @@ import type {
   EnumDeclarationInfo,
   EnumMemberInfo
 } from '../types.js';
+import { ScopeTracker } from '../../../../core/ScopeTracker.js';
+import { computeSemanticId } from '../../../../core/SemanticId.js';
+import { getLine, getColumn } from '../utils/location.js';
 
 /**
  * Extracts a string representation of a TypeScript type node
  */
-function typeNodeToString(node: unknown): string {
+export function typeNodeToString(node: unknown): string {
   if (!node || typeof node !== 'object') return 'unknown';
 
   const typeNode = node as { type: string; [key: string]: unknown };
@@ -97,8 +100,16 @@ function typeNodeToString(node: unknown): string {
 }
 
 export class TypeScriptVisitor extends ASTVisitor {
-  constructor(module: VisitorModule, collections: VisitorCollections) {
+  private scopeTracker?: ScopeTracker;
+
+  /**
+   * @param module - Current module being analyzed
+   * @param collections - Must contain interfaces, typeAliases, enums arrays
+   * @param scopeTracker - Optional ScopeTracker for semantic ID generation
+   */
+  constructor(module: VisitorModule, collections: VisitorCollections, scopeTracker?: ScopeTracker) {
     super(module, collections);
+    this.scopeTracker = scopeTracker;
   }
 
   getHandlers(): VisitorHandlers {
@@ -108,6 +119,7 @@ export class TypeScriptVisitor extends ASTVisitor {
       typeAliases,
       enums
     } = this.collections;
+    const scopeTracker = this.scopeTracker;
 
     return {
       TSInterfaceDeclaration: (path: NodePath) => {
@@ -115,7 +127,12 @@ export class TypeScriptVisitor extends ASTVisitor {
         if (!node.id) return;
 
         const interfaceName = node.id.name;
-        const interfaceId = `INTERFACE#${interfaceName}#${module.file}#${node.loc!.start.line}`;
+
+        // Generate semantic ID if scopeTracker available
+        let interfaceSemanticId: string | undefined;
+        if (scopeTracker) {
+          interfaceSemanticId = computeSemanticId('INTERFACE', interfaceName, scopeTracker.getContext());
+        }
 
         // Extract extends
         const extendsNames: string[] = [];
@@ -156,12 +173,12 @@ export class TypeScriptVisitor extends ASTVisitor {
         }
 
         (interfaces as InterfaceDeclarationInfo[]).push({
-          id: interfaceId,
+          semanticId: interfaceSemanticId,
           type: 'INTERFACE',
           name: interfaceName,
           file: module.file,
-          line: node.loc!.start.line,
-          column: node.loc!.start.column,
+          line: getLine(node),
+          column: getColumn(node),
           extends: extendsNames.length > 0 ? extendsNames : undefined,
           properties
         });
@@ -172,18 +189,23 @@ export class TypeScriptVisitor extends ASTVisitor {
         if (!node.id) return;
 
         const typeName = node.id.name;
-        const typeId = `TYPE#${typeName}#${module.file}#${node.loc!.start.line}`;
+
+        // Generate semantic ID if scopeTracker available
+        let typeSemanticId: string | undefined;
+        if (scopeTracker) {
+          typeSemanticId = computeSemanticId('TYPE', typeName, scopeTracker.getContext());
+        }
 
         // Extract the type being aliased
         const aliasOf = typeNodeToString(node.typeAnnotation);
 
         (typeAliases as TypeAliasInfo[]).push({
-          id: typeId,
+          semanticId: typeSemanticId,
           type: 'TYPE',
           name: typeName,
           file: module.file,
-          line: node.loc!.start.line,
-          column: node.loc!.start.column,
+          line: getLine(node),
+          column: getColumn(node),
           aliasOf
         });
       },
@@ -193,7 +215,12 @@ export class TypeScriptVisitor extends ASTVisitor {
         if (!node.id) return;
 
         const enumName = node.id.name;
-        const enumId = `ENUM#${enumName}#${module.file}#${node.loc!.start.line}`;
+
+        // Generate semantic ID if scopeTracker available
+        let enumSemanticId: string | undefined;
+        if (scopeTracker) {
+          enumSemanticId = computeSemanticId('ENUM', enumName, scopeTracker.getContext());
+        }
 
         // Extract members
         const members: EnumMemberInfo[] = [];
@@ -220,12 +247,12 @@ export class TypeScriptVisitor extends ASTVisitor {
         }
 
         (enums as EnumDeclarationInfo[]).push({
-          id: enumId,
+          semanticId: enumSemanticId,
           type: 'ENUM',
           name: enumName,
           file: module.file,
-          line: node.loc!.start.line,
-          column: node.loc!.start.column,
+          line: getLine(node),
+          column: getColumn(node),
           isConst: node.const || false,
           members
         });