@grafema/core 0.2.5-beta → 0.2.7

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

@@ -16,7 +16,8 @@ import type {
 } from '@babel/types';
 import type { ParameterInfo } from '../types.js';
 import type { ScopeTracker } from '../../../../core/ScopeTracker.js';
-import { computeSemanticId } from '../../../../core/SemanticId.js';
+import { computeSemanticIdV2 } from '../../../../core/SemanticId.js';
+import { extractNamesFromPattern } from './extractNamesFromPattern.js';
 
 /**
  * Create PARAMETER nodes for function parameters
@@ -25,10 +26,11 @@ import { computeSemanticId } from '../../../../core/SemanticId.js';
  * - 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])
+ * - ObjectPattern (destructuring): function({ x, y })               // REG-399
+ * - ArrayPattern (destructuring): function([a, b])                  // REG-399
+ * - Nested destructuring: function({ data: { user } })              // REG-399
+ * - Defaults in destructuring: function({ x = 42 })                 // REG-399
+ * - Pattern-level defaults: function({ x, y } = {})                 // REG-399
  *
  * @param params - AST nodes for function parameters
  * @param functionId - ID of the parent function (for parentFunctionId field)
@@ -47,11 +49,14 @@ export function createParameterNodes(
 ): void {
   if (!parameters) return; // Guard for backward compatibility
 
+  const scopePath = scopeTracker.getContext().scopePath;
+  const namedParent = scopeTracker.getNamedParent();
+
   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 });
+      const paramId = computeSemanticIdV2('PARAMETER', name, file, namedParent, undefined, index);
       parameters.push({
         id: paramId,
         semanticId: paramId,
@@ -60,14 +65,17 @@ export function createParameterNodes(
         file: file,
         line: param.loc?.start.line || line,
         index: index,
-        parentFunctionId: functionId
+        parentFunctionId: functionId,
+        scopePath
       });
     } else if (param.type === 'AssignmentPattern') {
-      // Default parameter: function(a = 1)
+      // Default parameter: function(a = 1) OR destructured with defaults: function({ x = 1 })
       const assignmentParam = param as AssignmentPattern;
+
       if (assignmentParam.left.type === 'Identifier') {
+        // Simple default: function(a = 1)
         const name = assignmentParam.left.name;
-        const paramId = computeSemanticId('PARAMETER', name, scopeTracker.getContext(), { discriminator: index });
+        const paramId = computeSemanticIdV2('PARAMETER', name, file, namedParent, undefined, index);
         parameters.push({
           id: paramId,
           semanticId: paramId,
@@ -77,7 +85,55 @@ export function createParameterNodes(
           line: assignmentParam.left.loc?.start.line || line,
           index: index,
           hasDefault: true,
-          parentFunctionId: functionId
+          parentFunctionId: functionId,
+          scopePath
+        });
+      } else if (assignmentParam.left.type === 'ObjectPattern' || assignmentParam.left.type === 'ArrayPattern') {
+        // REG-399: Destructuring with default: function({ x } = {}) or function([x] = [])
+        // The pattern-level default means "if argument is undefined, use this default object/array"
+        // extractNamesFromPattern already handles nested AssignmentPattern (property-level defaults)
+        const extractedParams = extractNamesFromPattern(assignmentParam.left);
+
+        extractedParams.forEach((paramInfo, subIndex) => {
+          // Discriminator ensures unique IDs for parameters at same position
+          // Formula: index * 1000 + subIndex
+          // Example: function({ a, b }, c) — a=0, b=1, c=1000
+          const discriminator = index * 1000 + subIndex;
+
+          const paramId = computeSemanticIdV2(
+            'PARAMETER',
+            paramInfo.name,
+            file,
+            namedParent,
+            undefined,
+            discriminator
+          );
+
+          const paramData: ParameterInfo = {
+            id: paramId,
+            semanticId: paramId,
+            type: 'PARAMETER',
+            name: paramInfo.name,
+            file: file,
+            line: paramInfo.loc.start.line,
+            index: index,  // Original parameter position in function signature
+            hasDefault: true,  // Pattern-level default (e.g., = {})
+            parentFunctionId: functionId,
+            scopePath
+          };
+
+          // Add destructuring metadata
+          if (paramInfo.propertyPath && paramInfo.propertyPath.length > 0) {
+            paramData.propertyPath = paramInfo.propertyPath;
+          }
+          if (paramInfo.arrayIndex !== undefined) {
+            paramData.arrayIndex = paramInfo.arrayIndex;
+          }
+          if (paramInfo.isRest) {
+            paramData.isRest = true;
+          }
+
+          parameters.push(paramData);
         });
       }
     } else if ((param as Node).type === 'RestElement') {
@@ -85,7 +141,7 @@ export function createParameterNodes(
       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 });
+        const paramId = computeSemanticIdV2('PARAMETER', name, file, namedParent, undefined, index);
         parameters.push({
           id: paramId,
           semanticId: paramId,
@@ -95,10 +151,59 @@ export function createParameterNodes(
           line: restParam.argument.loc?.start.line || line,
           index: index,
           isRest: true,
-          parentFunctionId: functionId
+          parentFunctionId: functionId,
+          scopePath
         });
       }
+    } else if (param.type === 'ObjectPattern' || param.type === 'ArrayPattern') {
+      // REG-399: Handle destructured parameters
+      // Extract all parameter names from destructuring pattern
+      const extractedParams = extractNamesFromPattern(param);
+
+      extractedParams.forEach((paramInfo, subIndex) => {
+        // Discriminator ensures unique IDs for parameters at same position
+        // Formula: index * 1000 + subIndex
+        // Example: function({ a, b }, c) — a=0, b=1, c=1000
+        const discriminator = index * 1000 + subIndex;
+
+        const paramId = computeSemanticIdV2(
+          'PARAMETER',
+          paramInfo.name,
+          file,
+          namedParent,
+          undefined,
+          discriminator
+        );
+
+        const paramData: ParameterInfo = {
+          id: paramId,
+          semanticId: paramId,
+          type: 'PARAMETER',
+          name: paramInfo.name,
+          file: file,
+          line: paramInfo.loc.start.line,
+          index: index,  // Original parameter position in function signature
+          parentFunctionId: functionId,
+          scopePath
+        };
+
+        // Add destructuring metadata
+        if (paramInfo.propertyPath && paramInfo.propertyPath.length > 0) {
+          paramData.propertyPath = paramInfo.propertyPath;
+        }
+        if (paramInfo.arrayIndex !== undefined) {
+          paramData.arrayIndex = paramInfo.arrayIndex;
+        }
+        if (paramInfo.isRest) {
+          paramData.isRest = true;
+        }
+        // hasDefault already tracked by extractNamesFromPattern for property-level defaults
+        if (paramInfo.hasDefault) {
+          paramData.hasDefault = true;
+        }
+
+        parameters.push(paramData);
+      });
     }
-    // ObjectPattern and ArrayPattern (destructuring parameters) can be added later
   });
 }

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

@@ -0,0 +1,166 @@
+/**
+ * extractNamesFromPattern - Extract variable names from destructuring patterns
+ *
+ * Shared utility for extracting variable bindings from ObjectPattern, ArrayPattern,
+ * and nested destructuring patterns. Used by both VariableVisitor (for variable
+ * declarations) and createParameterNodes (for function parameters).
+ *
+ * Handles:
+ * - Object destructuring: { x, y }
+ * - Nested object destructuring: { data: { user } }
+ * - Property renaming: { old: newName }
+ * - Array destructuring: [first, second]
+ * - Sparse array destructuring: [, , third]
+ * - Rest elements: { a, ...rest } or [first, ...rest]
+ * - Default values: { x = 42 } or [x = 10]
+ * - Mixed patterns: { items: [first, second] }
+ *
+ * REG-201: Original implementation for variable destructuring
+ * REG-399: Extended for parameter destructuring support
+ */
+
+import * as t from '@babel/types';
+
+/**
+ * Information about an extracted variable from a destructuring pattern.
+ * Used for both VARIABLE nodes (declarations) and PARAMETER nodes (function params).
+ */
+export interface ExtractedVariable {
+  /** Variable name (the binding identifier) */
+  name: string;
+  /** Source location for the binding */
+  loc: { start: { line: number; column: number } };
+  /** Property path for nested object destructuring (e.g., ['data', 'user'] for { data: { user } }) */
+  propertyPath?: string[];
+  /** Array index for array destructuring (e.g., 0 for first element in [first, second]) */
+  arrayIndex?: number;
+  /** True for rest elements ({ a, ...rest } or [first, ...rest]) */
+  isRest?: boolean;
+  /** True if this binding has a default value (tracked during AssignmentPattern recursion) */
+  hasDefault?: boolean;
+}
+
+/**
+ * Extract all variable names from a destructuring pattern.
+ *
+ * Pure function - no side effects, no instance state dependencies.
+ * Recursively processes nested patterns and accumulates bindings.
+ *
+ * @param pattern - AST node (ObjectPattern, ArrayPattern, Identifier, etc.)
+ * @param variables - Accumulator for extracted variables (internal)
+ * @param propertyPath - Current property path for nested destructuring (internal)
+ * @param hasDefault - Whether current pattern is wrapped in AssignmentPattern (internal)
+ * @returns Array of extracted variable bindings with metadata
+ *
+ * @example
+ * // Simple object destructuring
+ * const { x, y } = obj;
+ * // Returns: [
+ * //   { name: 'x', loc: {...}, propertyPath: ['x'] },
+ * //   { name: 'y', loc: {...}, propertyPath: ['y'] }
+ * // ]
+ *
+ * @example
+ * // Nested with defaults
+ * const { data: { user = 'guest' } } = response;
+ * // Returns: [
+ * //   { name: 'user', loc: {...}, propertyPath: ['data', 'user'], hasDefault: true }
+ * // ]
+ *
+ * @example
+ * // Array with rest
+ * const [first, ...rest] = items;
+ * // Returns: [
+ * //   { name: 'first', loc: {...}, arrayIndex: 0 },
+ * //   { name: 'rest', loc: {...}, arrayIndex: 1, isRest: true }
+ * // ]
+ */
+export function extractNamesFromPattern(
+  pattern: t.Node | null | undefined,
+  variables: ExtractedVariable[] = [],
+  propertyPath: string[] = [],
+  hasDefault: boolean = false
+): ExtractedVariable[] {
+  if (!pattern) return variables;
+
+  // Base case: Identifier (leaf node)
+  if (t.isIdentifier(pattern)) {
+    variables.push({
+      name: pattern.name,
+      loc: pattern.loc?.start ? { start: pattern.loc.start } : { start: { line: 0, column: 0 } },
+      propertyPath: propertyPath.length > 0 ? [...propertyPath] : undefined,
+      hasDefault: hasDefault || undefined  // Only set if true
+    });
+  }
+  // Object destructuring: { x, y, data: { user } }
+  else if (t.isObjectPattern(pattern)) {
+    pattern.properties.forEach((prop) => {
+      // Rest element: { a, ...rest }
+      if (t.isRestElement(prop)) {
+        const restVars = extractNamesFromPattern(prop.argument, [], [], hasDefault);
+        restVars.forEach(v => {
+          v.isRest = true;
+          v.propertyPath = propertyPath.length > 0 ? [...propertyPath] : undefined;
+          variables.push(v);
+        });
+      }
+      // Regular property: { x } or { data: { user } }
+      else if (t.isObjectProperty(prop) && prop.value) {
+        // Extract property key (name in source object)
+        const key = t.isIdentifier(prop.key) ? prop.key.name :
+                   (t.isStringLiteral(prop.key) || t.isNumericLiteral(prop.key) ? String(prop.key.value) : null);
+
+        if (key !== null) {
+          // Extend property path for nested destructuring
+          const newPath = [...propertyPath, key];
+          extractNamesFromPattern(prop.value, variables, newPath, hasDefault);
+        } else {
+          // Computed property names - skip path tracking
+          extractNamesFromPattern(prop.value, variables, propertyPath, hasDefault);
+        }
+      }
+    });
+  }
+  // Array destructuring: [first, second] or [, , third]
+  else if (t.isArrayPattern(pattern)) {
+    pattern.elements.forEach((element, index) => {
+      if (element) {
+        // Rest element: [first, ...rest]
+        if (t.isRestElement(element)) {
+          const restVars = extractNamesFromPattern(element.argument, [], [], hasDefault);
+          restVars.forEach(v => {
+            v.isRest = true;
+            v.arrayIndex = index;
+            v.propertyPath = propertyPath.length > 0 ? [...propertyPath] : undefined;
+            variables.push(v);
+          });
+        }
+        // Regular element: [first] or [{ x }] (nested)
+        else {
+          const extracted = extractNamesFromPattern(element, [], propertyPath, hasDefault);
+          extracted.forEach(v => {
+            v.arrayIndex = index;
+            variables.push(v);
+          });
+        }
+      }
+      // null/undefined element (sparse array: [, , third])
+      // Skip - no binding
+    });
+  }
+  // Rest element (standalone, handled by parent patterns)
+  else if (t.isRestElement(pattern)) {
+    const restVars = extractNamesFromPattern(pattern.argument, [], propertyPath, hasDefault);
+    restVars.forEach(v => {
+      v.isRest = true;
+      variables.push(v);
+    });
+  }
+  // AssignmentPattern: default values (x = 42, { x } = {}, [x] = [])
+  else if (t.isAssignmentPattern(pattern)) {
+    // Recurse on the left side (the pattern), marking hasDefault=true
+    extractNamesFromPattern(pattern.left, variables, propertyPath, true);
+  }
+
+  return variables;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Extract a human-readable string representation of an AST expression value.
+ *
+ * Used to capture initial values, default values, and prop values
+ * in a readable format for graph metadata.
+ *
+ * @module getExpressionValue
+ */
+import type { Node } from '@babel/types';
+
+/**
+ * @example
+ * // StringLiteral "hello" => '"hello"'
+ * // NumericLiteral 42 => "42"
+ * // Identifier foo => "foo"
+ * // ObjectExpression => "{...}"
+ * // null/undefined => "undefined"
+ *
+ * @param expr - Babel AST expression node (may be undefined)
+ * @returns Human-readable string representation
+ */
+export function getExpressionValue(expr: Node | undefined): string {
+  if (!expr) return 'undefined';
+  if (expr.type === 'StringLiteral') return `"${(expr as { value: string }).value}"`;
+  if (expr.type === 'NumericLiteral') return String((expr as { value: number }).value);
+  if (expr.type === 'BooleanLiteral') return String((expr as { value: boolean }).value);
+  if (expr.type === 'NullLiteral') return 'null';
+  if (expr.type === 'Identifier') return (expr as { name: string }).name;
+  if (expr.type === 'ObjectExpression') return '{...}';
+  if (expr.type === 'ArrayExpression') return '[...]';
+  if (expr.type === 'ArrowFunctionExpression') return '() => {...}';
+  if (expr.type === 'FunctionExpression') return 'function() {...}';
+  return '<expression>';
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Extract full dotted name from a MemberExpression AST node.
+ *
+ * Recursively walks the member expression to build
+ * a dotted string like "localStorage.setItem" or "window.history.pushState".
+ *
+ * Returns the Identifier name for non-MemberExpression nodes,
+ * or '<unknown>' / '<computed>' for unresolvable parts.
+ *
+ * @module getMemberExpressionName
+ */
+import type { Node } from '@babel/types';
+
+/**
+ * @example
+ * // For AST node representing `localStorage.setItem`:
+ * getMemberExpressionName(node) // => "localStorage.setItem"
+ *
+ * // For a plain Identifier node:
+ * getMemberExpressionName(identNode) // => "someVar"
+ *
+ * @param node - Babel AST node (MemberExpression or Identifier)
+ * @returns Dotted name string
+ */
+export function getMemberExpressionName(node: Node): string {
+  if (node.type !== 'MemberExpression') {
+    return (node as { name?: string }).name || '<unknown>';
+  }
+  const memExpr = node as { object: Node; property: { name?: string; value?: string } };
+  const object = getMemberExpressionName(memExpr.object);
+  const property = memExpr.property.name || memExpr.property.value || '<computed>';
+  return `${object}.${property}`;
+}

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

@@ -10,3 +10,5 @@ export {
   UNKNOWN_LOCATION,
   type NodeLocation
 } from './location.js';
+export { getMemberExpressionName } from './getMemberExpressionName.js';
+export { getExpressionValue } from './getExpressionValue.js';