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

package/src/plugins/analysis/ast/IdGenerator.ts

@@ -0,0 +1,177 @@
+/**
+ * IdGenerator - Centralized ID generation for AST nodes
+ *
+ * Encapsulates the dual ID system:
+ * - Semantic IDs (stable, based on scope path) when ScopeTracker is available
+ * - Legacy IDs (hash-separated, location-based) as fallback
+ *
+ * This removes 18+ duplicate instances of the same pattern across visitor files.
+ */
+
+import type { ScopeTracker } from '../../../core/ScopeTracker.js';
+import { computeSemanticId } from '../../../core/SemanticId.js';
+
+/**
+ * Counter reference for legacy ID generation
+ */
+export interface CounterRef {
+  value: number;
+}
+
+/**
+ * Options for ID generation
+ */
+export interface IdGeneratorOptions {
+  /**
+   * Whether to use discriminator for same-named items in same scope.
+   * When true, calls scopeTracker.getItemCounter() to get a unique discriminator.
+   */
+  useDiscriminator?: boolean;
+
+  /**
+   * Custom key for discriminator counter.
+   * Defaults to `${type}:${name}` if not specified.
+   */
+  discriminatorKey?: string;
+}
+
+/**
+ * IdGenerator - Centralized ID generation for AST nodes
+ *
+ * Usage:
+ * ```typescript
+ * const idGen = new IdGenerator(scopeTracker);
+ *
+ * // For nodes with counter (VARIABLE, CALL, etc.)
+ * const varId = idGen.generate('VARIABLE', 'myVar', file, line, col, counterRef);
+ *
+ * // For nodes with discriminator (CALL - same function called multiple times)
+ * const callId = idGen.generate('CALL', 'console.log', file, line, col, counterRef, {
+ *   useDiscriminator: true
+ * });
+ *
+ * // For nodes without counter (FUNCTION)
+ * const funcId = idGen.generateSimple('FUNCTION', 'myFunc', file, line);
+ *
+ * // For scope bodies
+ * const scopeId = idGen.generateScope('body', 'myFunc:body', file, line);
+ * ```
+ */
+export class IdGenerator {
+  constructor(private scopeTracker?: ScopeTracker) {}
+
+  /**
+   * Generate ID for nodes that use a counter in legacy format.
+   *
+   * Legacy format: `TYPE#name#file#line:column:counter`
+   * Semantic format: `file->scope->TYPE->name[#discriminator]`
+   *
+   * Used for: VARIABLE, CONSTANT, CALL, METHOD_CALL, LITERAL
+   */
+  generate(
+    type: string,
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    counterRef: CounterRef,
+    options?: IdGeneratorOptions
+  ): string {
+    const legacyId = `${type}#${name}#${file}#${line}:${column}:${counterRef.value++}`;
+
+    if (!this.scopeTracker) return legacyId;
+
+    const discriminator = options?.useDiscriminator
+      ? this.scopeTracker.getItemCounter(options.discriminatorKey ?? `${type}:${name}`)
+      : undefined;
+
+    return computeSemanticId(type, name, this.scopeTracker.getContext(), { discriminator });
+  }
+
+  /**
+   * Generate ID for nodes without counter in legacy format.
+   *
+   * Legacy format: `TYPE#name#file#line` or `TYPE#name#file#line:column`
+   * Semantic format: `file->scope->TYPE->name`
+   *
+   * Used for: FUNCTION (named), CLASS
+   */
+  generateSimple(
+    type: string,
+    name: string,
+    file: string,
+    line: number,
+    column?: number
+  ): string {
+    const legacyId = column !== undefined
+      ? `${type}#${name}#${file}#${line}:${column}`
+      : `${type}#${name}#${file}#${line}`;
+
+    if (!this.scopeTracker) return legacyId;
+
+    return computeSemanticId(type, name, this.scopeTracker.getContext());
+  }
+
+  /**
+   * Generate ID for scope nodes.
+   *
+   * Legacy format: `SCOPE#funcName:body#file#line` or with column
+   * Semantic format: `file->scope->SCOPE->body`
+   *
+   * @param semanticName - Name for semantic ID (usually 'body')
+   * @param legacyName - Name for legacy ID (usually 'funcName:body')
+   */
+  generateScope(
+    semanticName: string,
+    legacyName: string,
+    file: string,
+    line: number,
+    column?: number
+  ): string {
+    const legacyId = column !== undefined
+      ? `SCOPE#${legacyName}#${file}#${line}:${column}`
+      : `SCOPE#${legacyName}#${file}#${line}`;
+
+    if (!this.scopeTracker) return legacyId;
+
+    return computeSemanticId('SCOPE', semanticName, this.scopeTracker.getContext());
+  }
+
+  /**
+   * Generate legacy-only ID (no semantic version).
+   *
+   * Used for: LITERAL (arguments), DECORATOR, PROPERTY
+   *
+   * NOTE: PARAMETER nodes use computeSemanticId() for stable, semantic identifiers.
+   * See createParameterNodes.ts for the implementation.
+   *
+   * @param includeSuffix - Additional suffix after line:column (counter or index)
+   */
+  generateLegacy(
+    type: string,
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    suffix?: string | number
+  ): string {
+    if (suffix !== undefined) {
+      return `${type}#${name}#${file}#${line}:${column}:${suffix}`;
+    }
+    return `${type}#${name}#${file}#${line}:${column}`;
+  }
+
+  /**
+   * Check if semantic IDs are available (scopeTracker is present)
+   */
+  hasSemanticIds(): boolean {
+    return this.scopeTracker !== undefined;
+  }
+
+  /**
+   * Get the underlying ScopeTracker (for advanced usage)
+   */
+  getScopeTracker(): ScopeTracker | undefined {
+    return this.scopeTracker;
+  }
+}

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

@@ -19,7 +19,6 @@ export interface ModuleNode {
 // === FUNCTION INFO ===
 export interface FunctionInfo {
   id: string;
-  stableId: string;
   type: 'FUNCTION';
   name: string;
   file: string;
@@ -36,12 +35,15 @@ export interface FunctionInfo {
 // === PARAMETER INFO ===
 export interface ParameterInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->PARAMETER->name
   type: 'PARAMETER';
   name: string;
   file: string;
   line: number;
   index?: number;
-  functionId: string;
+  hasDefault?: boolean;  // Has default value (e.g., function(a = 1))
+  isRest?: boolean;      // Rest parameter (e.g., function(...args))
+  functionId?: string;   // Legacy field - prefer parentFunctionId
   parentFunctionId?: string;
 }
 
@@ -51,7 +53,7 @@ export interface ScopeInfo {
   type: 'SCOPE';
   scopeType: string;
   name?: string;
-  semanticId?: string;  // Stable ID for diff comparison (e.g., "MyClass.myMethod:if_statement[0]")
+  semanticId?: string;  // Stable ID for diff comparison (e.g., "MyClass->myMethod:if_statement[0]")
   conditional?: boolean;
   condition?: string;
   constraints?: unknown[];
@@ -66,6 +68,7 @@ export interface ScopeInfo {
 // === VARIABLE DECLARATION INFO ===
 export interface VariableDeclarationInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->VARIABLE->name
   type: 'VARIABLE' | 'CONSTANT';
   name: string;
   file: string;
@@ -78,6 +81,7 @@ export interface VariableDeclarationInfo {
 // === CALL SITE INFO ===
 export interface CallSiteInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->CALL->name#N
   type: 'CALL';
   name: string;
   file: string;
@@ -91,10 +95,13 @@ export interface CallSiteInfo {
 // === METHOD CALL INFO ===
 export interface MethodCallInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->CALL->object.method#N
   type: 'CALL';
   name: string;
   object: string;
   method: string;
+  computed?: boolean;             // Whether method was accessed via computed property [x]
+  computedPropertyVar?: string | null;  // Variable name used in obj[x]() calls
   file: string;
   line: number;
   column?: number;
@@ -106,6 +113,7 @@ export interface MethodCallInfo {
 // === EVENT LISTENER INFO ===
 export interface EventListenerInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->EVENT_LISTENER->name#N
   type: 'event:listener';
   name: string;
   object: string;
@@ -127,6 +135,7 @@ export interface ClassInstantiationInfo {
 // === CLASS DECLARATION INFO ===
 export interface ClassDeclarationInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->CLASS->name
   type: 'CLASS';
   name: string;
   file: string;
@@ -139,7 +148,12 @@ export interface ClassDeclarationInfo {
 
 // === INTERFACE DECLARATION INFO ===
 export interface InterfaceDeclarationInfo {
-  id: string;
+  /**
+   * @deprecated ID is now generated by InterfaceNode.create() in GraphBuilder.
+   * This field will be removed in a future version.
+   */
+  id?: string;
+  semanticId?: string;  // Stable ID: file->scope->INTERFACE->name
   type: 'INTERFACE';
   name: string;
   file: string;
@@ -158,7 +172,12 @@ export interface InterfacePropertyInfo {
 
 // === TYPE ALIAS INFO ===
 export interface TypeAliasInfo {
-  id: string;
+  /**
+   * @deprecated ID is now generated by NodeFactory.createType() in GraphBuilder.
+   * This field will be removed in a future version.
+   */
+  id?: string;
+  semanticId?: string;  // Stable ID: file->scope->TYPE->name
   type: 'TYPE';
   name: string;
   file: string;
@@ -169,7 +188,12 @@ export interface TypeAliasInfo {
 
 // === ENUM DECLARATION INFO ===
 export interface EnumDeclarationInfo {
-  id: string;
+  /**
+   * @deprecated ID is now generated by EnumNode.create() in GraphBuilder.
+   * This field will be removed in a future version.
+   */
+  id?: string;
+  semanticId?: string;  // Stable ID: file->scope->ENUM->name
   type: 'ENUM';
   name: string;
   file: string;
@@ -187,6 +211,7 @@ export interface EnumMemberInfo {
 // === DECORATOR INFO ===
 export interface DecoratorInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->target->DECORATOR->name#N
   type: 'DECORATOR';
   name: string;
   file: string;
@@ -229,6 +254,7 @@ export interface ImportInfo {
   source: string;
   file: string;
   line: number;
+  column?: number;  // Column position for ImportNode
   specifiers: ImportSpecifier[];
 }
 
@@ -267,6 +293,7 @@ export interface HttpRequestInfo {
 // === LITERAL INFO ===
 export interface LiteralInfo {
   id: string;
+  semanticId?: string;  // Stable ID: file->scope->LITERAL->type#N
   type: 'LITERAL' | 'CALL';
   value?: unknown;
   valueType?: string;
@@ -281,6 +308,150 @@ export interface LiteralInfo {
   argIndex?: number;
 }
 
+// === OBJECT LITERAL INFO ===
+export interface ObjectLiteralInfo {
+  id: string;
+  semanticId?: string;  // Stable ID: file->scope->OBJECT_LITERAL->literal#N
+  type: 'OBJECT_LITERAL';
+  file: string;
+  line: number;
+  column: number;
+  parentCallId?: string;
+  argIndex?: number;
+  isSpread?: boolean;
+}
+
+// === OBJECT PROPERTY INFO ===
+export interface ObjectPropertyInfo {
+  objectId: string;
+  propertyName: string;
+  valueNodeId?: string;
+  valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL' | 'SPREAD';
+  valueName?: string;       // For VARIABLE
+  literalValue?: unknown;   // For LITERAL
+  file: string;
+  line: number;
+  column: number;
+  // For CALL values
+  callLine?: number;
+  callColumn?: number;
+  // For nested object/array
+  nestedObjectId?: string;
+  nestedArrayId?: string;
+}
+
+// === ARRAY LITERAL INFO ===
+export interface ArrayLiteralInfo {
+  id: string;
+  semanticId?: string;  // Stable ID: file->scope->ARRAY_LITERAL->literal#N
+  type: 'ARRAY_LITERAL';
+  file: string;
+  line: number;
+  column: number;
+  parentCallId?: string;
+  argIndex?: number;
+}
+
+// === ARRAY ELEMENT INFO ===
+export interface ArrayElementInfo {
+  arrayId: string;
+  index: number;
+  valueNodeId?: string;
+  valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL' | 'SPREAD';
+  valueName?: string;       // For VARIABLE
+  literalValue?: unknown;   // For LITERAL
+  file: string;
+  line: number;
+  column: number;
+  // For CALL values
+  callLine?: number;
+  callColumn?: number;
+  // For nested object/array
+  nestedObjectId?: string;
+  nestedArrayId?: string;
+}
+
+// === ARRAY MUTATION INFO ===
+/**
+ * Tracks array mutation calls (push, unshift, splice) and indexed assignments
+ * Used to create FLOWS_INTO edges in GraphBuilder
+ *
+ * IMPORTANT: This type is defined ONLY here. Import from this file everywhere.
+ */
+export interface ArrayMutationInfo {
+  id?: string;                 // Semantic ID for the mutation (optional for backward compatibility)
+  arrayName: string;           // Name of the array variable being mutated
+  arrayLine?: number;          // Line where array is referenced (for scope resolution)
+  mutationMethod: 'push' | 'unshift' | 'splice' | 'indexed';
+  file: string;
+  line: number;
+  column: number;
+  insertedValues: ArrayMutationArgument[];  // What's being added to the array
+  isNested?: boolean;          // REG-117: true if receiver is MemberExpression
+  baseObjectName?: string;     // REG-117: "obj" from obj.arr.push()
+  propertyName?: string;       // REG-117: "arr" - the array property name
+}
+
+export interface ArrayMutationArgument {
+  argIndex: number;
+  isSpread?: boolean;
+  valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL';
+  valueName?: string;          // For VARIABLE type - name of the variable
+  valueNodeId?: string;        // For LITERAL, OBJECT_LITERAL, ARRAY_LITERAL - node ID
+  literalValue?: unknown;      // For LITERAL type
+  callLine?: number;           // For CALL type
+  callColumn?: number;
+}
+
+// === OBJECT MUTATION INFO ===
+/**
+ * Tracks object property mutations for FLOWS_INTO edge creation in GraphBuilder.
+ * Handles: obj.prop = value, obj['prop'] = value, Object.assign(), spread in object literals.
+ *
+ * IMPORTANT: This type is defined ONLY here. Import from this file everywhere.
+ */
+export interface ObjectMutationInfo {
+  id?: string;                   // Semantic ID for the mutation (optional for backward compatibility)
+  objectName: string;            // Name of the object being mutated ('config', 'this', etc.)
+  objectLine?: number;           // Line where object is referenced (for scope resolution)
+  enclosingClassName?: string;   // Class name when objectName === 'this' (REG-152)
+  propertyName: string;          // Property name or '<computed>' for obj[x] or '<assign>' for Object.assign
+  mutationType: 'property' | 'computed' | 'assign' | 'spread';
+  computedPropertyVar?: string;  // Variable name in obj[key] = value (for computed mutation type)
+  file: string;
+  line: number;
+  column: number;
+  value: ObjectMutationValue;
+}
+
+export interface ObjectMutationValue {
+  valueType: 'LITERAL' | 'VARIABLE' | 'CALL' | 'EXPRESSION' | 'OBJECT_LITERAL' | 'ARRAY_LITERAL';
+  valueName?: string;            // For VARIABLE type - name of the variable
+  valueNodeId?: string;          // For LITERAL, OBJECT_LITERAL, ARRAY_LITERAL - node ID
+  literalValue?: unknown;        // For LITERAL type
+  callLine?: number;             // For CALL type
+  callColumn?: number;
+  isSpread?: boolean;            // For Object.assign with spread: Object.assign(target, ...sources)
+  argIndex?: number;             // For Object.assign - which source argument (0, 1, 2, ...)
+}
+
+/**
+ * Resolution status for computed property names.
+ * Used in FLOWS_INTO edge metadata to indicate how property name was determined.
+ *
+ * - RESOLVED: Single deterministic value traced from literals
+ * - RESOLVED_CONDITIONAL: Multiple possible values (ternary, logical OR, etc.)
+ * - UNKNOWN_PARAMETER: Variable traces to function parameter
+ * - UNKNOWN_RUNTIME: Variable traces to function call result
+ * - DEFERRED_CROSS_FILE: Variable traces to import (requires cross-file analysis)
+ */
+export type ResolutionStatus =
+  | 'RESOLVED'
+  | 'RESOLVED_CONDITIONAL'
+  | 'UNKNOWN_PARAMETER'
+  | 'UNKNOWN_RUNTIME'
+  | 'DEFERRED_CROSS_FILE';
+
 // === VARIABLE ASSIGNMENT INFO ===
 export interface VariableAssignmentInfo {
   variableId: string;
@@ -296,6 +467,7 @@ export interface VariableAssignmentInfo {
   className?: string;
   functionName?: string;
   line?: number;
+  column?: number;  // Column position for EXPRESSION nodes
   expressionType?: string;
   object?: string;
   property?: string;
@@ -348,6 +520,15 @@ export interface ASTCollections {
   httpRequests?: HttpRequestInfo[];
   literals?: LiteralInfo[];
   variableAssignments?: VariableAssignmentInfo[];
+  // Object/Array literal tracking for data flow
+  objectLiterals?: ObjectLiteralInfo[];
+  objectProperties?: ObjectPropertyInfo[];
+  arrayLiterals?: ArrayLiteralInfo[];
+  arrayElements?: ArrayElementInfo[];
+  // Array mutation tracking for FLOWS_INTO edges
+  arrayMutations?: ArrayMutationInfo[];
+  // Object mutation tracking for FLOWS_INTO edges
+  objectMutations?: ObjectMutationInfo[];
   // TypeScript-specific collections
   interfaces?: InterfaceDeclarationInfo[];
   typeAliases?: TypeAliasInfo[];
@@ -361,7 +542,11 @@ export interface ASTCollections {
   functionCounterRef?: CounterRef;
   httpRequestCounterRef?: CounterRef;
   literalCounterRef?: CounterRef;
+  objectLiteralCounterRef?: CounterRef;
+  arrayLiteralCounterRef?: CounterRef;
   processedNodes?: ProcessedNodes;
+  // ScopeTracker for semantic ID generation
+  scopeTracker?: import('../../../core/ScopeTracker.js').ScopeTracker;
 }
 
 // === EXTRACTED VARIABLE ===
@@ -381,6 +566,12 @@ export interface GraphNode {
   file?: string;
   line?: number;
   column?: number;
+  // IMPORT node fields
+  source?: string;
+  importType?: 'default' | 'named' | 'namespace';
+  importBinding?: 'value' | 'type' | 'typeof';
+  imported?: string;
+  local?: string;
   [key: string]: unknown;
 }
 
@@ -390,6 +581,18 @@ export interface GraphEdge {
   src: string;
   dst: string;
   index?: number;
+  // For FLOWS_INTO edges (array mutations)
+  mutationMethod?: string;
+  argIndex?: number;
+  isSpread?: boolean;
+  nestedProperty?: string;  // REG-117: Property name for nested mutations (obj.arr.push -> "arr")
+  // For FLOWS_INTO edges (object mutations)
+  mutationType?: 'property' | 'computed' | 'assign' | 'spread' | 'this_property';
+  propertyName?: string;
+  // For computed property resolution (enrichment phase)
+  computedPropertyVar?: string;           // Variable name for obj[key] patterns
+  resolvedPropertyNames?: string[];       // Resolved names after enrichment
+  resolutionStatus?: ResolutionStatus;    // How resolution was determined
   metadata?: Record<string, unknown>;
 }
 

package/src/plugins/analysis/ast/utils/createParameterNodes.ts

@@ -0,0 +1,104 @@
+/**
+ * createParameterNodes - Shared utility for creating PARAMETER nodes
+ *
+ * Used by FunctionVisitor and ClassVisitor to create PARAMETER nodes
+ * for function/method parameters with consistent behavior.
+ *
+ * Uses semantic IDs for stable, scope-based identification that doesn't
+ * change when lines are added/removed above the function.
+ */
+
+import type {
+  Node,
+  Identifier,
+  AssignmentPattern,
+  RestElement
+} from '@babel/types';
+import type { ParameterInfo } from '../types.js';
+import { ScopeTracker } from '../../../../core/ScopeTracker.js';
+import { computeSemanticId } from '../../../../core/SemanticId.js';
+
+/**
+ * Create PARAMETER nodes for function parameters
+ *
+ * Handles:
+ * - Simple Identifier parameters: function(a, b)
+ * - AssignmentPattern (default parameters): function(a = 1)
+ * - RestElement (rest parameters): function(...args)
+ *
+ * Does NOT handle (can be added later):
+ * - ObjectPattern (destructuring): function({ x, y })
+ * - ArrayPattern (destructuring): function([a, b])
+ *
+ * @param params - AST nodes for function parameters
+ * @param functionId - ID of the parent function (for parentFunctionId field)
+ * @param file - File path
+ * @param line - Line number of the function (for ParameterInfo.line fallback)
+ * @param parameters - Array to push ParameterInfo objects into
+ * @param scopeTracker - REQUIRED for semantic ID generation
+ */
+export function createParameterNodes(
+  params: Node[],
+  functionId: string,
+  file: string,
+  line: number,
+  parameters: ParameterInfo[],
+  scopeTracker: ScopeTracker
+): void {
+  if (!parameters) return; // Guard for backward compatibility
+
+  params.forEach((param, index) => {
+    // Handle different parameter types
+    if (param.type === 'Identifier') {
+      const name = (param as Identifier).name;
+      const paramId = computeSemanticId('PARAMETER', name, scopeTracker.getContext(), { discriminator: index });
+      parameters.push({
+        id: paramId,
+        semanticId: paramId,
+        type: 'PARAMETER',
+        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 name = assignmentParam.left.name;
+        const paramId = computeSemanticId('PARAMETER', name, scopeTracker.getContext(), { discriminator: index });
+        parameters.push({
+          id: paramId,
+          semanticId: paramId,
+          type: 'PARAMETER',
+          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 name = restParam.argument.name;
+        const paramId = computeSemanticId('PARAMETER', name, scopeTracker.getContext(), { discriminator: index });
+        parameters.push({
+          id: paramId,
+          semanticId: paramId,
+          type: 'PARAMETER',
+          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
+  });
+}

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

@@ -0,0 +1,12 @@
+/**
+ * AST utility functions
+ */
+export { createParameterNodes } from './createParameterNodes.js';
+export {
+  getNodeLocation,
+  getLine,
+  getColumn,
+  getEndLocation,
+  UNKNOWN_LOCATION,
+  type NodeLocation
+} from './location.js';