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

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';

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

@@ -0,0 +1,103 @@
+/**
+ * Location extraction utilities for AST nodes.
+ *
+ * Convention: 0:0 means "unknown location" when AST node lacks position data.
+ * This can happen with synthetic nodes, transformed AST, or malformed source.
+ *
+ * This is the single source of truth for location extraction across all analyzers.
+ *
+ * @module location
+ */
+import type { Node } from '@babel/types';
+
+/**
+ * Fallback location for nodes without position data.
+ * Used when AST was generated without source maps or from synthetic nodes.
+ */
+export const UNKNOWN_LOCATION = { line: 0, column: 0 } as const;
+
+/**
+ * Location information extracted from an AST node.
+ * Both line and column are guaranteed to be numbers (not undefined).
+ */
+export interface NodeLocation {
+  readonly line: number;
+  readonly column: number;
+}
+
+/**
+ * Extract start location from an AST node.
+ *
+ * Returns { line: 0, column: 0 } if node is null, undefined, or lacks location data.
+ * This is the preferred way to get location info - use this instead of node.loc!
+ *
+ * @example
+ * // Instead of:
+ * const line = node.loc!.start.line;
+ * const column = node.loc!.start.column;
+ *
+ * // Use:
+ * const { line, column } = getNodeLocation(node);
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns Location with line and column (both guaranteed numbers)
+ */
+export function getNodeLocation(node: Node | null | undefined): NodeLocation {
+  return {
+    line: node?.loc?.start?.line ?? 0,
+    column: node?.loc?.start?.column ?? 0
+  };
+}
+
+/**
+ * Extract start line number from an AST node.
+ *
+ * Returns 0 if node is null, undefined, or lacks location data.
+ *
+ * @example
+ * // Instead of:
+ * const line = node.loc!.start.line;
+ *
+ * // Use:
+ * const line = getLine(node);
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns Line number (1-based) or 0 for unknown
+ */
+export function getLine(node: Node | null | undefined): number {
+  return node?.loc?.start?.line ?? 0;
+}
+
+/**
+ * Extract start column number from an AST node.
+ *
+ * Returns 0 if node is null, undefined, or lacks location data.
+ *
+ * @example
+ * // Instead of:
+ * const col = node.loc!.start.column;
+ *
+ * // Use:
+ * const col = getColumn(node);
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns Column number (0-based) or 0 for unknown
+ */
+export function getColumn(node: Node | null | undefined): number {
+  return node?.loc?.start?.column ?? 0;
+}
+
+/**
+ * Extract end location from an AST node.
+ *
+ * Returns { line: 0, column: 0 } if node is null, undefined, or lacks location data.
+ *
+ * @param node - Babel AST node (may be null or undefined)
+ * @returns End location with line and column (both guaranteed numbers)
+ */
+export function getEndLocation(node: Node | null | undefined): NodeLocation {
+  return {
+    line: node?.loc?.end?.line ?? 0,
+    column: node?.loc?.end?.column ?? 0
+  };
+}

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

@@ -3,12 +3,15 @@
  * Each visitor handles specific AST node types and collects relevant data
  */
 import type { Node, SourceLocation } from '@babel/types';
+import { getNodeLocation, type NodeLocation } from '../utils/location.js';
 import type { NodePath } from '@babel/traverse';
 import type {
   FunctionInfo,
   ClassDeclarationInfo,
   ClassInstantiationInfo,
   ScopeInfo,
+  BranchInfo,
+  CaseInfo,
   VariableDeclarationInfo,
   CallSiteInfo,
   MethodCallInfo,
@@ -65,6 +68,10 @@ export interface VisitorCollections {
   sideEffects?: unknown[];  // TODO: define SideEffectInfo type
   code?: string;  // Source code for condition extraction
 
+  // Branching (REG-275)
+  branches?: BranchInfo[];
+  cases?: CaseInfo[];
+
   // Counters - optional
   functionCounterRef?: CounterRef;
   callSiteCounterRef?: CounterRef;
@@ -75,6 +82,8 @@ export interface VisitorCollections {
   varDeclCounterRef?: CounterRef;
   httpRequestCounterRef?: CounterRef;
   anonymousFunctionCounterRef?: CounterRef;
+  branchCounterRef?: CounterRef;
+  caseCounterRef?: CounterRef;
 
   // Deduplication - optional
   processedNodes?: ProcessedNodes;
@@ -84,11 +93,13 @@ export interface VisitorCollections {
 }
 
 /**
- * Location info extracted from AST node
+ * Location info extracted from AST node.
+ * Both line and column are guaranteed to be numbers (not undefined).
+ * Convention: 0:0 means "unknown location".
  */
 export interface LocationInfo {
-  line: number | undefined;
-  column: number | undefined;
+  line: number;
+  column: number;
 }
 
 /**
@@ -126,12 +137,12 @@ export abstract class ASTVisitor {
   abstract getHandlers(): VisitorHandlers;
 
   /**
-   * Utility to get source location info
+   * Utility to get source location info.
+   * Returns { line: 0, column: 0 } if location is unavailable.
+   *
+   * @deprecated Prefer using getLine() or getNodeLocation() directly from utils/location.js
    */
   protected getLoc(node: Node): LocationInfo {
-    return {
-      line: node.loc?.start?.line,
-      column: node.loc?.start?.column
-    };
+    return getNodeLocation(node);
   }
 }