@grafema/core 0.1.0-alpha.1

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

@@ -0,0 +1,339 @@
+/**
+ * ClassVisitor - handles class declarations and their methods
+ *
+ * Handles:
+ * - ClassDeclaration
+ * - ClassMethod (nested)
+ * - ClassProperty with function values (nested)
+ * - Implements (TypeScript)
+ * - Decorators
+ */
+
+import type {
+  ClassDeclaration,
+  ClassMethod,
+  ClassProperty,
+  Identifier,
+  ArrowFunctionExpression,
+  FunctionExpression,
+  Decorator,
+  Node
+} from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+import { ASTVisitor, type VisitorModule, type VisitorCollections, type VisitorHandlers } from './ASTVisitor.js';
+import type { AnalyzeFunctionBodyCallback } from './FunctionVisitor.js';
+import type { DecoratorInfo } from '../types.js';
+import { ExpressionEvaluator } from '../ExpressionEvaluator.js';
+
+/**
+ * Class declaration info
+ */
+interface ClassInfo {
+  id: string;
+  type: 'CLASS';
+  name: string;
+  file: string;
+  line: number;
+  column: number;
+  superClass: string | null;
+  implements?: string[];  // TypeScript implements
+  methods: string[];
+}
+
+/**
+ * Function node info for class methods
+ */
+interface ClassFunctionInfo {
+  id: string;
+  stableId: string;
+  type: 'FUNCTION';
+  name: string;
+  file: string;
+  line: number;
+  column: number;
+  async: boolean;
+  generator?: boolean;
+  arrowFunction?: boolean;
+  isClassProperty?: boolean;
+  isClassMethod?: boolean;
+  className: string;
+  methodKind?: 'constructor' | 'method' | 'get' | 'set';
+}
+
+/**
+ * Scope node info
+ */
+interface ScopeInfo {
+  id: string;
+  type: 'SCOPE';
+  scopeType: string;
+  name: string;
+  conditional?: boolean;
+  file: string;
+  line: number;
+  parentFunctionId: string;
+}
+
+export class ClassVisitor extends ASTVisitor {
+  private analyzeFunctionBody: AnalyzeFunctionBodyCallback;
+
+  /**
+   * @param module - Current module being analyzed
+   * @param collections - Must contain arrays and counter refs
+   * @param analyzeFunctionBody - Callback to analyze method internals
+   */
+  constructor(
+    module: VisitorModule,
+    collections: VisitorCollections,
+    analyzeFunctionBody: AnalyzeFunctionBodyCallback
+  ) {
+    super(module, collections);
+    this.analyzeFunctionBody = analyzeFunctionBody;
+  }
+
+  /**
+   * Extract decorator information from a Decorator node
+   */
+  private extractDecoratorInfo(
+    decorator: Decorator,
+    targetId: string,
+    targetType: 'CLASS' | 'METHOD' | 'PROPERTY' | 'PARAMETER',
+    module: VisitorModule
+  ): DecoratorInfo | null {
+    let decoratorName: string;
+    let decoratorArgs: unknown[] | undefined;
+
+    // @Decorator or @Decorator()
+    if (decorator.expression.type === 'Identifier') {
+      decoratorName = (decorator.expression as Identifier).name;
+    } else if (decorator.expression.type === 'CallExpression') {
+      const callExpr = decorator.expression as { callee: { type: string; name?: string }; arguments: unknown[] };
+      if (callExpr.callee.type === 'Identifier') {
+        decoratorName = callExpr.callee.name!;
+        // Extract arguments (cast to Node since Babel types guarantee these are AST nodes)
+        decoratorArgs = callExpr.arguments.map(arg => {
+          return ExpressionEvaluator.extractLiteralValue(arg as Node);
+        }).filter(v => v !== null);
+        if (decoratorArgs.length === 0) {
+          decoratorArgs = undefined;
+        }
+      } else {
+        return null;  // Complex decorator expression
+      }
+    } else {
+      return null;  // Unsupported decorator type
+    }
+
+    const decoratorId = `DECORATOR#${decoratorName}#${module.file}#${decorator.loc!.start.line}:${decorator.loc!.start.column}`;
+
+    return {
+      id: decoratorId,
+      type: 'DECORATOR',
+      name: decoratorName,
+      file: module.file,
+      line: decorator.loc!.start.line,
+      column: decorator.loc!.start.column,
+      arguments: decoratorArgs,
+      targetId,
+      targetType
+    };
+  }
+
+  getHandlers(): VisitorHandlers {
+    const { module } = this;
+    const {
+      functions,
+      scopes,
+      classDeclarations,
+      decorators
+    } = this.collections;
+
+    const analyzeFunctionBody = this.analyzeFunctionBody;
+    const collections = this.collections;
+
+    return {
+      ClassDeclaration: (classPath: NodePath) => {
+        const classNode = classPath.node as ClassDeclaration;
+        if (!classNode.id) return; // Skip anonymous classes
+
+        const className = classNode.id.name;
+
+        // Create CLASS node for declaration
+        const classId = `CLASS#${className}#${module.file}#${classNode.loc!.start.line}`;
+        const superClassName = classNode.superClass?.type === 'Identifier'
+          ? (classNode.superClass as Identifier).name
+          : null;
+
+        // Extract implements (TypeScript)
+        const implementsNames: string[] = [];
+        const classNodeWithImplements = classNode as ClassDeclaration & { implements?: Array<{ expression: { type: string; name?: string } }> };
+        if (classNodeWithImplements.implements && classNodeWithImplements.implements.length > 0) {
+          for (const impl of classNodeWithImplements.implements) {
+            if (impl.expression.type === 'Identifier') {
+              implementsNames.push(impl.expression.name!);
+            }
+          }
+        }
+
+        (classDeclarations as ClassInfo[]).push({
+          id: classId,
+          type: 'CLASS',
+          name: className,
+          file: module.file,
+          line: classNode.loc!.start.line,
+          column: classNode.loc!.start.column,
+          superClass: superClassName,
+          implements: implementsNames.length > 0 ? implementsNames : undefined,
+          methods: []
+        });
+
+        // Extract class decorators
+        const classNodeWithDecorators = classNode as ClassDeclaration & { decorators?: Decorator[] };
+        if (classNodeWithDecorators.decorators && classNodeWithDecorators.decorators.length > 0 && decorators) {
+          for (const decorator of classNodeWithDecorators.decorators) {
+            const decoratorInfo = this.extractDecoratorInfo(decorator, classId, 'CLASS', module);
+            if (decoratorInfo) {
+              (decorators as DecoratorInfo[]).push(decoratorInfo);
+            }
+          }
+        }
+
+        // Get reference to current class for adding methods
+        const classDeclarationsTyped = classDeclarations as ClassInfo[];
+        const currentClass = classDeclarationsTyped[classDeclarationsTyped.length - 1];
+
+        // Process class methods and properties
+        classPath.traverse({
+          ClassProperty: (propPath: NodePath) => {
+            const propNode = propPath.node as ClassProperty;
+
+            // Skip if not property of current class
+            if (propPath.parent !== classNode.body) {
+              return;
+            }
+
+            const propName = propNode.key.type === 'Identifier'
+              ? propNode.key.name
+              : (propNode.key as { value?: string }).value || 'anonymous';
+
+            // Extract property decorators (even for non-function properties)
+            const propNodeWithDecorators = propNode as ClassProperty & { decorators?: Decorator[] };
+            if (propNodeWithDecorators.decorators && propNodeWithDecorators.decorators.length > 0 && decorators) {
+              // For function properties, target will be set later; for regular properties, create a target ID
+              const propertyTargetId = `PROPERTY#${className}.${propName}#${module.file}#${propNode.loc!.start.line}`;
+              for (const decorator of propNodeWithDecorators.decorators) {
+                const decoratorInfo = this.extractDecoratorInfo(decorator, propertyTargetId, 'PROPERTY', module);
+                if (decoratorInfo) {
+                  (decorators as DecoratorInfo[]).push(decoratorInfo);
+                }
+              }
+            }
+
+            // Only process if value is a function
+            if (propNode.value &&
+                (propNode.value.type === 'ArrowFunctionExpression' ||
+                 propNode.value.type === 'FunctionExpression')) {
+
+              const funcNode = propNode.value as ArrowFunctionExpression | FunctionExpression;
+
+              const functionId = `FUNCTION#${className}.${propName}#${module.file}#${propNode.loc!.start.line}:${propNode.loc!.start.column}`;
+
+              // Add method to class methods list for CONTAINS edges
+              currentClass.methods.push(functionId);
+
+              (functions as ClassFunctionInfo[]).push({
+                id: functionId,
+                stableId: functionId,
+                type: 'FUNCTION',
+                name: propName,
+                file: module.file,
+                line: propNode.loc!.start.line,
+                column: propNode.loc!.start.column,
+                async: funcNode.async || false,
+                generator: funcNode.type === 'FunctionExpression' ? funcNode.generator || false : false,
+                arrowFunction: funcNode.type === 'ArrowFunctionExpression',
+                isClassProperty: true,
+                className: className
+              });
+
+              // Create SCOPE for property function body
+              const propBodyScopeId = `SCOPE#${className}.${propName}:body#${module.file}#${propNode.loc!.start.line}`;
+              (scopes as ScopeInfo[]).push({
+                id: propBodyScopeId,
+                type: 'SCOPE',
+                scopeType: 'property_body',
+                name: `${className}.${propName}:body`,
+                conditional: false,
+                file: module.file,
+                line: propNode.loc!.start.line,
+                parentFunctionId: functionId
+              });
+
+              const funcPath = propPath.get('value') as NodePath<ArrowFunctionExpression | FunctionExpression>;
+              analyzeFunctionBody(funcPath, propBodyScopeId, module, collections);
+            }
+          },
+
+          ClassMethod: (methodPath: NodePath<ClassMethod>) => {
+            const methodNode = methodPath.node;
+            const methodName = methodNode.key.type === 'Identifier'
+              ? methodNode.key.name
+              : (methodNode.key as { value?: string }).value || 'anonymous';
+
+            // Skip if not method of current class (nested classes)
+            if (methodPath.parent !== classNode.body) {
+              return;
+            }
+
+            const functionId = `FUNCTION#${className}.${methodName}#${module.file}#${methodNode.loc!.start.line}:${methodNode.loc!.start.column}`;
+
+            // Add method to class methods list for CONTAINS edges
+            currentClass.methods.push(functionId);
+
+            const funcData: ClassFunctionInfo = {
+              id: functionId,
+              stableId: functionId,
+              type: 'FUNCTION',
+              name: methodName,
+              file: module.file,
+              line: methodNode.loc!.start.line,
+              column: methodNode.loc!.start.column,
+              async: methodNode.async || false,
+              generator: methodNode.generator || false,
+              isClassMethod: true,
+              className: className,
+              methodKind: methodNode.kind as 'constructor' | 'method' | 'get' | 'set'
+            };
+            (functions as ClassFunctionInfo[]).push(funcData);
+
+            // Extract method decorators
+            const methodNodeWithDecorators = methodNode as ClassMethod & { decorators?: Decorator[] };
+            if (methodNodeWithDecorators.decorators && methodNodeWithDecorators.decorators.length > 0 && decorators) {
+              for (const decorator of methodNodeWithDecorators.decorators) {
+                const decoratorInfo = this.extractDecoratorInfo(decorator, functionId, 'METHOD', module);
+                if (decoratorInfo) {
+                  (decorators as DecoratorInfo[]).push(decoratorInfo);
+                }
+              }
+            }
+
+            // Create SCOPE for method body
+            const methodBodyScopeId = `SCOPE#${className}.${methodName}:body#${module.file}#${methodNode.loc!.start.line}`;
+            (scopes as ScopeInfo[]).push({
+              id: methodBodyScopeId,
+              type: 'SCOPE',
+              scopeType: 'method_body',
+              name: `${className}.${methodName}:body`,
+              conditional: false,
+              file: module.file,
+              line: methodNode.loc!.start.line,
+              parentFunctionId: functionId
+            });
+
+            analyzeFunctionBody(methodPath, methodBodyScopeId, module, collections);
+          }
+        });
+      }
+    };
+  }
+}

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

@@ -0,0 +1,273 @@
+/**
+ * FunctionVisitor - handles function declarations and arrow functions
+ *
+ * Handles:
+ * - FunctionDeclaration
+ * - ArrowFunctionExpression (module-level)
+ */
+
+import type {
+  Node,
+  Function,
+  FunctionDeclaration,
+  ArrowFunctionExpression,
+  Identifier,
+  AssignmentPattern,
+  RestElement,
+  VariableDeclarator
+} 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;
+}
+
+/**
+ * Function node info
+ */
+interface FunctionInfo {
+  id: string;
+  stableId: string;
+  type: 'FUNCTION';
+  name: string;
+  file: string;
+  line: number;
+  column?: number;
+  async: boolean;
+  generator?: boolean;
+  arrowFunction?: boolean;
+}
+
+/**
+ * Scope node info
+ */
+interface ScopeInfo {
+  id: string;
+  type: 'SCOPE';
+  scopeType: string;
+  name: string;
+  conditional?: boolean;
+  file: string;
+  line: number;
+  parentFunctionId: string;
+}
+
+/**
+ * Callback type for analyzing function bodies
+ */
+export type AnalyzeFunctionBodyCallback = (
+  path: NodePath<Function>,
+  scopeId: string,
+  module: VisitorModule,
+  collections: VisitorCollections
+) => void;
+
+export class FunctionVisitor extends ASTVisitor {
+  private analyzeFunctionBody: AnalyzeFunctionBodyCallback;
+
+  /**
+   * @param module - Current module being analyzed
+   * @param collections - Must contain arrays and counter refs
+   * @param analyzeFunctionBody - Callback to analyze function internals
+   */
+  constructor(
+    module: VisitorModule,
+    collections: VisitorCollections,
+    analyzeFunctionBody: AnalyzeFunctionBodyCallback
+  ) {
+    super(module, collections);
+    this.analyzeFunctionBody = analyzeFunctionBody;
+  }
+
+  getHandlers(): VisitorHandlers {
+    const { module } = this;
+    const functions = this.collections.functions ?? [];
+    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 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);
+      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
+        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
+          });
+        } 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
+            });
+          }
+        } else if ((param as Node).type === 'RestElement') {
+          // Rest parameter: function(...args)
+          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
+            });
+          }
+        }
+        // ObjectPattern and ArrayPattern (destructuring parameters) can be added later
+      });
+    };
+
+    return {
+      // Regular function declarations
+      FunctionDeclaration: (path: NodePath) => {
+        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}`;
+
+        (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
+        });
+
+        // Create PARAMETER nodes for function parameters
+        createParameterNodes(node.params, functionId, module.file, node.loc!.start.line);
+
+        // Create SCOPE for function body
+        const functionBodyScopeId = `SCOPE#${node.id.name}:body#${module.file}#${node.loc!.start.line}`;
+        (scopes as ScopeInfo[]).push({
+          id: functionBodyScopeId,
+          type: 'SCOPE',
+          scopeType: 'function_body',
+          name: `${node.id.name}:body`,
+          conditional: false,
+          file: module.file,
+          line: node.loc!.start.line,
+          parentFunctionId: functionId
+        });
+
+        // Analyze function body
+        analyzeFunctionBody(path as NodePath<FunctionDeclaration>, functionBodyScopeId, module, collections);
+
+        // Stop traversal - analyzeFunctionBody already processed contents
+        path.skip();
+      },
+
+      // 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;
+
+        // Determine arrow function name (use scope-level counter for stable semanticId)
+        let functionName = generateAnonymousName();
+
+        // If arrow function is assigned to variable: const add = () => {}
+        const parent = path.parent;
+        if (parent.type === 'VariableDeclarator') {
+          const declarator = parent as VariableDeclarator;
+          if (declarator.id.type === 'Identifier') {
+            functionName = declarator.id.name;
+          }
+        }
+
+        const functionId = `FUNCTION#${functionName}#${module.file}#${line}:${column}:${functionCounterRef.value++}`;
+
+        (functions as FunctionInfo[]).push({
+          id: functionId,
+          stableId: functionId,
+          type: 'FUNCTION',
+          name: functionName,
+          file: module.file,
+          line,
+          column,
+          async: node.async || false,
+          arrowFunction: true
+        });
+
+        // Create PARAMETER nodes for arrow function parameters
+        createParameterNodes(node.params, functionId, module.file, line);
+
+        // Create SCOPE for arrow function body
+        const bodyScope = `SCOPE#${functionName}:body#${module.file}#${line}:${column}`;
+        (scopes as ScopeInfo[]).push({
+          id: bodyScope,
+          type: 'SCOPE',
+          name: `${functionName}:body`,
+          file: module.file,
+          line,
+          scopeType: 'function-body',
+          parentFunctionId: functionId
+        });
+
+        analyzeFunctionBody(path as NodePath<ArrowFunctionExpression>, bodyScope, module, collections);
+      }
+    };
+  }
+}