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

package/src/core/nodes/CallSiteNode.ts

@@ -1,8 +1,16 @@
 /**
  * CallSiteNode - contract for CALL_SITE node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{scope_path}->CALL->{calleeName}#N
+ * Example: src/app.js->handler->CALL->console.log#0
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface CallSiteNodeRecord extends BaseNodeRecord {
   type: 'CALL_SITE';
@@ -16,11 +24,19 @@ interface CallSiteNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface CallSiteContextOptions {
+  discriminator: number;
+  parentScopeId?: string;
+}
+
 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
@@ -35,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,
@@ -45,7 +62,50 @@ export class CallSiteNode {
       name: targetName,
       file,
       line,
-      column: column || 0,
+      column,
+      parentScopeId: options.parentScopeId,
+      targetFunctionName: targetName
+    };
+  }
+
+  /**
+   * Create CALL_SITE node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Requires discriminator for multiple calls to same function within scope.
+   *
+   * @param targetName - Name of called function (e.g., 'console.log', 'db.query')
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Options including required discriminator
+   * @returns CallSiteNodeRecord with semantic ID
+   */
+  static createWithContext(
+    targetName: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: CallSiteContextOptions
+  ): CallSiteNodeRecord {
+    // Validate required fields
+    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
+    // Use 'CALL' as the type for cleaner IDs (matches spec)
+    const id = computeSemanticId('CALL', targetName, context, {
+      discriminator: options.discriminator
+    });
+
+    return {
+      id,
+      type: this.TYPE,
+      name: targetName,
+      file: context.file,
+      line: location.line,
+      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

@@ -1,8 +1,16 @@
 /**
  * ClassNode - contract for CLASS node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext + Location for semantic IDs
+ * 2. create() - LEGACY: Uses line-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->{scope_path}->CLASS->{name}
+ * Example: src/models/User.js->global->CLASS->User
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface ClassNodeRecord extends BaseNodeRecord {
   type: 'CLASS';
@@ -10,19 +18,31 @@ interface ClassNodeRecord extends BaseNodeRecord {
   exported: boolean;
   superClass?: string;
   methods: string[];
+  isInstantiationRef?: boolean;
 }
 
 interface ClassNodeOptions {
   exported?: boolean;
   superClass?: string;
   methods?: string[];
+  isInstantiationRef?: boolean;
+}
+
+/**
+ * Options for createWithContext
+ */
+interface ClassContextOptions {
+  exported?: boolean;
+  superClass?: string;
+  methods?: string[];
+  isInstantiationRef?: boolean;
 }
 
 export class ClassNode {
   static readonly TYPE = 'CLASS' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'exported', 'superClass', 'methods'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['exported', 'superClass', 'methods', 'isInstantiationRef'] as const;
 
   static create(
     name: string,
@@ -34,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}`,
@@ -41,10 +62,52 @@ export class ClassNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
+      exported: options.exported || false,
+      superClass: options.superClass,
+      methods: options.methods || [],
+      ...(options.isInstantiationRef !== undefined && { isInstantiationRef: options.isInstantiationRef })
+    };
+  }
+
+  /**
+   * Create CLASS node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Class names are unique within scope, so no discriminator needed.
+   *
+   * @param name - Class name
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Optional class properties
+   * @returns ClassNodeRecord with semantic ID
+   */
+  static createWithContext(
+    name: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: ClassContextOptions = {}
+  ): ClassNodeRecord {
+    // Validate required fields
+    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);
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      file: context.file,
+      line: location.line,
+      column: location.column,
       exported: options.exported || false,
       superClass: options.superClass,
-      methods: options.methods || []
+      methods: options.methods || [],
+      ...(options.isInstantiationRef !== undefined && { isInstantiationRef: options.isInstantiationRef })
     };
   }
 

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