@grafema/core 0.1.1-alpha → 0.2.0-beta

package/src/core/nodes/BranchNode.ts

@@ -0,0 +1,113 @@
+/**
+ * BranchNode - contract for BRANCH node
+ *
+ * Represents control flow branching (switch statements).
+ * Future: if statements, ternary expressions.
+ *
+ * ID format (legacy): {file}:BRANCH:{branchType}:{line}:{counter}
+ * Semantic ID format: {file}->{scope_path}->BRANCH->switch#N
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
+
+interface BranchNodeRecord extends BaseNodeRecord {
+  type: 'BRANCH';
+  column: number;
+  branchType: 'switch' | 'if' | 'ternary';
+  parentScopeId?: string;
+}
+
+interface BranchNodeOptions {
+  parentScopeId?: string;
+  counter?: number;
+}
+
+interface BranchContextOptions {
+  discriminator: number;
+  parentScopeId?: string;
+}
+
+export class BranchNode {
+  static readonly TYPE = 'BRANCH' as const;
+  static readonly REQUIRED = ['branchType', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['parentScopeId'] as const;
+
+  /**
+   * Create BRANCH node (legacy ID)
+   */
+  static create(
+    branchType: 'switch' | 'if' | 'ternary',
+    file: string,
+    line: number,
+    column: number,
+    options: BranchNodeOptions = {}
+  ): BranchNodeRecord {
+    // Validation
+    if (!branchType) throw new Error('BranchNode.create: branchType is required');
+    if (!file) throw new Error('BranchNode.create: file is required');
+    if (line === undefined) throw new Error('BranchNode.create: line is required');
+    if (column === undefined) throw new Error('BranchNode.create: column is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:BRANCH:${branchType}:${line}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: branchType,
+      file,
+      line,
+      column,
+      branchType,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  /**
+   * Create BRANCH node with semantic ID (NEW API)
+   */
+  static createWithContext(
+    branchType: 'switch' | 'if' | 'ternary',
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: BranchContextOptions
+  ): BranchNodeRecord {
+    if (!branchType) throw new Error('BranchNode.createWithContext: branchType is required');
+    if (!context.file) throw new Error('BranchNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('BranchNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('BranchNode.createWithContext: column is required');
+    if (options.discriminator === undefined) throw new Error('BranchNode.createWithContext: discriminator is required');
+
+    const id = computeSemanticId('BRANCH', branchType, context, {
+      discriminator: options.discriminator
+    });
+
+    return {
+      id,
+      type: this.TYPE,
+      name: `${branchType}#${options.discriminator}`,
+      file: context.file,
+      line: location.line,
+      column: location.column,
+      branchType,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  static validate(node: BranchNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+    if (!node.branchType) {
+      errors.push('Missing required field: branchType');
+    }
+    if (!node.file) {
+      errors.push('Missing required field: file');
+    }
+    return errors;
+  }
+}
+
+export type { BranchNodeRecord };

package/src/core/nodes/CallSiteNode.ts

@@ -35,8 +35,8 @@ interface CallSiteContextOptions {
 export class CallSiteNode {
   static readonly TYPE = 'CALL_SITE' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'parentScopeId', 'targetFunctionName'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['parentScopeId', 'targetFunctionName'] as const;
 
   /**
    * Create CALL_SITE node
@@ -51,9 +51,10 @@ export class CallSiteNode {
     if (!targetName) throw new Error('CallSiteNode.create: targetName is required');
     if (!file) throw new Error('CallSiteNode.create: file is required');
     if (line === undefined) throw new Error('CallSiteNode.create: line is required');
+    if (column === undefined) throw new Error('CallSiteNode.create: column is required');
 
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
-    const id = `${file}:CALL_SITE:${targetName}:${line}:${column || 0}${counter}`;
+    const id = `${file}:CALL_SITE:${targetName}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -61,7 +62,7 @@ export class CallSiteNode {
       name: targetName,
       file,
       line,
-      column: column || 0,
+      column,
       parentScopeId: options.parentScopeId,
       targetFunctionName: targetName
     };
@@ -89,6 +90,7 @@ export class CallSiteNode {
     if (!targetName) throw new Error('CallSiteNode.createWithContext: targetName is required');
     if (!context.file) throw new Error('CallSiteNode.createWithContext: file is required');
     if (location.line === undefined) throw new Error('CallSiteNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('CallSiteNode.createWithContext: column is required');
     if (options.discriminator === undefined) throw new Error('CallSiteNode.createWithContext: discriminator is required');
 
     // Compute semantic ID with discriminator
@@ -103,7 +105,7 @@ export class CallSiteNode {
       name: targetName,
       file: context.file,
       line: location.line,
-      column: location.column ?? 0,
+      column: location.column,
       parentScopeId: options.parentScopeId,
       targetFunctionName: targetName
     };

package/src/core/nodes/CaseNode.ts

@@ -0,0 +1,123 @@
+/**
+ * CaseNode - contract for CASE node
+ *
+ * Represents a case clause in a switch statement.
+ *
+ * ID format (legacy): {file}:CASE:{value}:{line}:{counter}
+ * Semantic ID format: {file}->{scope_path}->CASE->{value}#N
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
+
+interface CaseNodeRecord extends BaseNodeRecord {
+  type: 'CASE';
+  column: number;
+  value: unknown;
+  isDefault: boolean;
+  fallsThrough: boolean;
+  isEmpty: boolean;
+  parentBranchId?: string;
+}
+
+interface CaseNodeOptions {
+  parentBranchId?: string;
+  counter?: number;
+}
+
+interface CaseContextOptions {
+  discriminator: number;
+  parentBranchId?: string;
+}
+
+export class CaseNode {
+  static readonly TYPE = 'CASE' as const;
+  static readonly REQUIRED = ['file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['value', 'isDefault', 'fallsThrough', 'isEmpty', 'parentBranchId'] as const;
+
+  /**
+   * Create CASE node (legacy ID)
+   */
+  static create(
+    value: unknown,
+    isDefault: boolean,
+    fallsThrough: boolean,
+    isEmpty: boolean,
+    file: string,
+    line: number,
+    column: number,
+    options: CaseNodeOptions = {}
+  ): CaseNodeRecord {
+    if (!file) throw new Error('CaseNode.create: file is required');
+    if (line === undefined) throw new Error('CaseNode.create: line is required');
+    if (column === undefined) throw new Error('CaseNode.create: column is required');
+
+    const valueName = isDefault ? 'default' : String(value);
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:CASE:${valueName}:${line}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: isDefault ? 'default' : `case ${String(value)}`,
+      file,
+      line,
+      column,
+      value,
+      isDefault,
+      fallsThrough,
+      isEmpty,
+      parentBranchId: options.parentBranchId
+    };
+  }
+
+  /**
+   * Create CASE node with semantic ID (NEW API)
+   */
+  static createWithContext(
+    value: unknown,
+    isDefault: boolean,
+    fallsThrough: boolean,
+    isEmpty: boolean,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: CaseContextOptions
+  ): CaseNodeRecord {
+    if (!context.file) throw new Error('CaseNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('CaseNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('CaseNode.createWithContext: column is required');
+    if (options.discriminator === undefined) throw new Error('CaseNode.createWithContext: discriminator is required');
+
+    const valueName = isDefault ? 'default' : String(value);
+    const id = computeSemanticId('CASE', valueName, context, {
+      discriminator: options.discriminator
+    });
+
+    return {
+      id,
+      type: this.TYPE,
+      name: isDefault ? 'default' : `case ${String(value)}`,
+      file: context.file,
+      line: location.line,
+      column: location.column,
+      value,
+      isDefault,
+      fallsThrough,
+      isEmpty,
+      parentBranchId: options.parentBranchId
+    };
+  }
+
+  static validate(node: CaseNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+    if (!node.file) {
+      errors.push('Missing required field: file');
+    }
+    return errors;
+  }
+}
+
+export type { CaseNodeRecord };

package/src/core/nodes/ClassNode.ts

@@ -41,8 +41,8 @@ interface ClassContextOptions {
 export class ClassNode {
   static readonly TYPE = 'CLASS' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'exported', 'superClass', 'methods', 'isInstantiationRef'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['exported', 'superClass', 'methods', 'isInstantiationRef'] as const;
 
   static create(
     name: string,
@@ -54,6 +54,7 @@ export class ClassNode {
     if (!name) throw new Error('ClassNode.create: name is required');
     if (!file) throw new Error('ClassNode.create: file is required');
     if (!line) throw new Error('ClassNode.create: line is required');
+    if (column === undefined) throw new Error('ClassNode.create: column is required');
 
     return {
       id: `${file}:CLASS:${name}:${line}`,
@@ -61,7 +62,7 @@ export class ClassNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
       exported: options.exported || false,
       superClass: options.superClass,
       methods: options.methods || [],
@@ -91,6 +92,7 @@ export class ClassNode {
     if (!name) throw new Error('ClassNode.createWithContext: name is required');
     if (!context.file) throw new Error('ClassNode.createWithContext: file is required');
     if (location.line === undefined) throw new Error('ClassNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('ClassNode.createWithContext: column is required');
 
     // Compute semantic ID
     const id = computeSemanticId(this.TYPE, name, context);
@@ -101,7 +103,7 @@ export class ClassNode {
       name,
       file: context.file,
       line: location.line,
-      column: location.column ?? 0,
+      column: location.column,
       exported: options.exported || false,
       superClass: options.superClass,
       methods: options.methods || [],

package/src/core/nodes/ConstantNode.ts

@@ -20,8 +20,8 @@ interface ConstantNodeOptions {
 export class ConstantNode {
   static readonly TYPE = 'CONSTANT' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'value', 'parentScopeId'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['value', 'parentScopeId'] as const;
 
   static create(
     name: string,
@@ -33,9 +33,10 @@ export class ConstantNode {
     if (!name) throw new Error('ConstantNode.create: name is required');
     if (!file) throw new Error('ConstantNode.create: file is required');
     if (line === undefined) throw new Error('ConstantNode.create: line is required');
+    if (column === undefined) throw new Error('ConstantNode.create: column is required');
 
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
-    const id = `${file}:CONSTANT:${name}:${line}:${column || 0}${counter}`;
+    const id = `${file}:CONSTANT:${name}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -43,7 +44,7 @@ export class ConstantNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
       value: options.value,
       parentScopeId: options.parentScopeId
     };

package/src/core/nodes/ConstructorCallNode.ts

@@ -0,0 +1,217 @@
+/**
+ * ConstructorCallNode - contract for CONSTRUCTOR_CALL node
+ *
+ * Represents a `new ClassName()` expression in code.
+ * Used for data flow: VARIABLE --ASSIGNED_FROM--> CONSTRUCTOR_CALL
+ *
+ * ID format: {file}:CONSTRUCTOR_CALL:{className}:{line}:{column}
+ * Example: src/app.js:CONSTRUCTOR_CALL:Date:42:10
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ConstructorCallNodeRecord extends BaseNodeRecord {
+  type: 'CONSTRUCTOR_CALL';
+  className: string;
+  isBuiltin: boolean;
+  column: number;
+}
+
+interface ConstructorCallNodeOptions {
+  counter?: number;
+}
+
+/**
+ * List of built-in JavaScript constructors
+ * These are globally available and don't require imports
+ */
+const BUILTIN_CONSTRUCTORS = new Set([
+  // Fundamental objects
+  'Object',
+  'Function',
+  'Boolean',
+  'Symbol',
+
+  // Error types
+  'Error',
+  'EvalError',
+  'RangeError',
+  'ReferenceError',
+  'SyntaxError',
+  'TypeError',
+  'URIError',
+  'AggregateError',
+
+  // Numbers and dates
+  'Number',
+  'BigInt',
+  'Math',
+  'Date',
+
+  // Text processing
+  'String',
+  'RegExp',
+
+  // Indexed collections
+  'Array',
+  'Int8Array',
+  'Uint8Array',
+  'Uint8ClampedArray',
+  'Int16Array',
+  'Uint16Array',
+  'Int32Array',
+  'Uint32Array',
+  'Float32Array',
+  'Float64Array',
+  'BigInt64Array',
+  'BigUint64Array',
+
+  // Keyed collections
+  'Map',
+  'Set',
+  'WeakMap',
+  'WeakSet',
+  'WeakRef',
+
+  // Structured data
+  'ArrayBuffer',
+  'SharedArrayBuffer',
+  'DataView',
+  'Atomics',
+  'JSON',
+
+  // Control abstraction
+  'Promise',
+  'Generator',
+  'GeneratorFunction',
+  'AsyncFunction',
+  'AsyncGenerator',
+  'AsyncGeneratorFunction',
+
+  // Reflection
+  'Reflect',
+  'Proxy',
+
+  // Internationalization
+  'Intl',
+
+  // Web APIs (commonly used)
+  'URL',
+  'URLSearchParams',
+  'Headers',
+  'Request',
+  'Response',
+  'FormData',
+  'Blob',
+  'File',
+  'FileReader',
+  'AbortController',
+  'TextEncoder',
+  'TextDecoder',
+  'Event',
+  'CustomEvent',
+  'EventTarget',
+  'WebSocket',
+  'Worker',
+  'MessageChannel',
+  'MessagePort',
+  'BroadcastChannel',
+  'ReadableStream',
+  'WritableStream',
+  'TransformStream',
+  'CompressionStream',
+  'DecompressionStream',
+]);
+
+export class ConstructorCallNode {
+  static readonly TYPE = 'CONSTRUCTOR_CALL' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'className', 'isBuiltin'] as const;
+  static readonly OPTIONAL = [] as const;
+
+  /**
+   * Check if a class name is a built-in JavaScript constructor
+   */
+  static isBuiltinConstructor(className: string): boolean {
+    return BUILTIN_CONSTRUCTORS.has(className);
+  }
+
+  /**
+   * Generate ID for CONSTRUCTOR_CALL node
+   *
+   * @param className - Name of the constructor
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional counter for disambiguation
+   */
+  static generateId(
+    className: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ConstructorCallNodeOptions = {}
+  ): string {
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    return `${file}:CONSTRUCTOR_CALL:${className}:${line}:${column}${counter}`;
+  }
+
+  /**
+   * Create CONSTRUCTOR_CALL node
+   *
+   * @param className - Name of the constructor (e.g., 'Date', 'MyClass')
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional counter for disambiguation
+   */
+  static create(
+    className: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ConstructorCallNodeOptions = {}
+  ): ConstructorCallNodeRecord {
+    if (!className) throw new Error('ConstructorCallNode.create: className is required');
+    if (!file) throw new Error('ConstructorCallNode.create: file is required');
+    if (line === undefined) throw new Error('ConstructorCallNode.create: line is required');
+    if (column === undefined) throw new Error('ConstructorCallNode.create: column is required');
+
+    const id = this.generateId(className, file, line, column, options);
+    const isBuiltin = this.isBuiltinConstructor(className);
+
+    return {
+      id,
+      type: this.TYPE,
+      name: `new ${className}()`,
+      className,
+      isBuiltin,
+      file,
+      line,
+      column
+    };
+  }
+
+  static validate(node: ConstructorCallNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined || nodeRecord[field] === null) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    if (typeof node.isBuiltin !== 'boolean') {
+      errors.push('isBuiltin must be a boolean');
+    }
+
+    return errors;
+  }
+}
+
+export type { ConstructorCallNodeRecord };

package/src/core/nodes/DatabaseQueryNode.ts

@@ -6,6 +6,7 @@ import type { BaseNodeRecord } from '@grafema/types';
 
 interface DatabaseQueryNodeRecord extends BaseNodeRecord {
   type: 'DATABASE_QUERY';
+  column: number;
   query?: string;
   operation: string;
   parentScopeId?: string;
@@ -18,7 +19,7 @@ interface DatabaseQueryNodeOptions {
 export class DatabaseQueryNode {
   static readonly TYPE = 'DATABASE_QUERY' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
   static readonly OPTIONAL = ['query', 'operation', 'parentScopeId'] as const;
 
   static create(
@@ -26,10 +27,12 @@ export class DatabaseQueryNode {
     operation: string | undefined,
     file: string,
     line: number,
+    column: number,
     options: DatabaseQueryNodeOptions = {}
   ): DatabaseQueryNodeRecord {
     if (!file) throw new Error('DatabaseQueryNode.create: file is required');
     if (line === undefined) throw new Error('DatabaseQueryNode.create: line is required');
+    if (column === undefined) throw new Error('DatabaseQueryNode.create: column is required');
 
     const name = query || `${operation || 'QUERY'}`;
     const id = `${file}:DATABASE_QUERY:${name}:${line}`;
@@ -42,6 +45,7 @@ export class DatabaseQueryNode {
       operation: operation || 'UNKNOWN',
       file,
       line,
+      column,
       parentScopeId: options.parentScopeId
     };
   }

package/src/core/nodes/DecoratorNode.ts

@@ -27,8 +27,8 @@ interface DecoratorNodeOptions {
 export class DecoratorNode {
   static readonly TYPE = 'DECORATOR' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line', 'targetId', 'targetType'] as const;
-  static readonly OPTIONAL = ['column', 'arguments'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'targetId', 'targetType'] as const;
+  static readonly OPTIONAL = ['arguments'] as const;
 
   /**
    * Create DECORATOR node
@@ -54,6 +54,7 @@ export class DecoratorNode {
     if (!name) throw new Error('DecoratorNode.create: name is required');
     if (!file) throw new Error('DecoratorNode.create: file is required');
     if (!line) throw new Error('DecoratorNode.create: line is required');
+    if (column === undefined) throw new Error('DecoratorNode.create: column is required');
     if (!targetId) throw new Error('DecoratorNode.create: targetId is required');
     if (!targetType) throw new Error('DecoratorNode.create: targetType is required');
 
@@ -63,7 +64,7 @@ export class DecoratorNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
       arguments: options.arguments || [],
       targetId,
       targetType

package/src/core/nodes/EnumNode.ts

@@ -29,8 +29,8 @@ interface EnumNodeOptions {
 export class EnumNode {
   static readonly TYPE = 'ENUM' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'isConst', 'members'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['isConst', 'members'] as const;
 
   /**
    * Create ENUM node
@@ -52,6 +52,7 @@ export class EnumNode {
     if (!name) throw new Error('EnumNode.create: name is required');
     if (!file) throw new Error('EnumNode.create: file is required');
     if (!line) throw new Error('EnumNode.create: line is required');
+    if (column === undefined) throw new Error('EnumNode.create: column is required');
 
     return {
       id: `${file}:ENUM:${name}:${line}`,
@@ -59,7 +60,7 @@ export class EnumNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
       isConst: options.isConst || false,
       members: options.members || []
     };