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

package/src/core/nodes/MethodCallNode.ts

@@ -1,8 +1,16 @@
 /**
  * MethodCallNode - contract for METHOD_CALL 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->{object.method}#N
+ * Example: src/app.js->handler->CALL->db.query#0
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface MethodCallNodeRecord extends BaseNodeRecord {
   type: 'METHOD_CALL';
@@ -19,11 +27,20 @@ interface MethodCallNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface MethodCallContextOptions {
+  discriminator: number;
+  parentScopeId?: string;
+  args?: unknown[];
+}
+
 export class MethodCallNode {
   static readonly TYPE = 'METHOD_CALL' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line', 'args'] as const;
-  static readonly OPTIONAL = ['object', 'method', 'column', 'parentScopeId'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'args'] as const;
+  static readonly OPTIONAL = ['object', 'method', 'parentScopeId'] as const;
 
   /**
    * Create METHOD_CALL node
@@ -39,10 +56,11 @@ export class MethodCallNode {
     if (!methodName) throw new Error('MethodCallNode.create: methodName is required');
     if (!file) throw new Error('MethodCallNode.create: file is required');
     if (line === undefined) throw new Error('MethodCallNode.create: line is required');
+    if (column === undefined) throw new Error('MethodCallNode.create: column is required');
 
     const fullName = objectName ? `${objectName}.${methodName}` : methodName;
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
-    const id = `${file}:METHOD_CALL:${fullName}:${line}:${column || 0}${counter}`;
+    const id = `${file}:METHOD_CALL:${fullName}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -52,7 +70,55 @@ export class MethodCallNode {
       method: methodName,
       file,
       line,
-      column: column || 0,
+      column,
+      parentScopeId: options.parentScopeId,
+      args: options.args || []
+    };
+  }
+
+  /**
+   * Create METHOD_CALL node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Requires discriminator for multiple calls to same method within scope.
+   *
+   * @param objectName - Object name (can be undefined for bare function calls)
+   * @param methodName - Method name
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Options including required discriminator
+   * @returns MethodCallNodeRecord with semantic ID
+   */
+  static createWithContext(
+    objectName: string | undefined,
+    methodName: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: MethodCallContextOptions
+  ): MethodCallNodeRecord {
+    // Validate required fields
+    if (!methodName) throw new Error('MethodCallNode.createWithContext: methodName is required');
+    if (!context.file) throw new Error('MethodCallNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('MethodCallNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('MethodCallNode.createWithContext: column is required');
+    if (options.discriminator === undefined) throw new Error('MethodCallNode.createWithContext: discriminator is required');
+
+    const fullName = objectName ? `${objectName}.${methodName}` : methodName;
+
+    // Compute semantic ID with discriminator
+    const id = computeSemanticId('CALL', fullName, context, {
+      discriminator: options.discriminator
+    });
+
+    return {
+      id,
+      type: this.TYPE,
+      name: fullName,
+      object: objectName,
+      method: methodName,
+      file: context.file,
+      line: location.line,
+      column: location.column,
       parentScopeId: options.parentScopeId,
       args: options.args || []
     };

package/src/core/nodes/MethodNode.ts

@@ -1,8 +1,16 @@
 /**
  * MethodNode - contract for METHOD node (class method)
+ *
+ * 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}->{className}->METHOD->{name}
+ * Example: src/services/UserService.js->UserService->METHOD->login
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 type MethodKind = 'method' | 'get' | 'set' | 'constructor';
 
@@ -23,11 +31,21 @@ interface MethodNodeOptions {
   kind?: MethodKind;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface MethodContextOptions {
+  async?: boolean;
+  generator?: boolean;
+  static?: boolean;
+  kind?: MethodKind;
+}
+
 export class MethodNode {
   static readonly TYPE = 'METHOD' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line', 'className'] as const;
-  static readonly OPTIONAL = ['column', 'async', 'generator', 'static', 'kind'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'className'] as const;
+  static readonly OPTIONAL = ['async', 'generator', 'static', 'kind'] as const;
 
   static create(
     name: string,
@@ -40,6 +58,7 @@ export class MethodNode {
     if (!name) throw new Error('MethodNode.create: name is required');
     if (!file) throw new Error('MethodNode.create: file is required');
     if (!line) throw new Error('MethodNode.create: line is required');
+    if (column === undefined) throw new Error('MethodNode.create: column is required');
     if (!className) throw new Error('MethodNode.create: className is required');
 
     return {
@@ -48,7 +67,53 @@ export class MethodNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
+      className,
+      async: options.async || false,
+      generator: options.generator || false,
+      static: options.static || false,
+      kind: options.kind || 'method'
+    };
+  }
+
+  /**
+   * Create METHOD node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Method names are unique within class, so no discriminator needed.
+   * Context should include the class in scopePath.
+   *
+   * @param name - Method name
+   * @param className - Name of the class containing this method
+   * @param context - Scope context from ScopeTracker.getContext() (should be inside class)
+   * @param location - Source location { line, column }
+   * @param options - Optional method properties
+   * @returns MethodNodeRecord with semantic ID
+   */
+  static createWithContext(
+    name: string,
+    className: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: MethodContextOptions = {}
+  ): MethodNodeRecord {
+    // Validate required fields
+    if (!name) throw new Error('MethodNode.createWithContext: name is required');
+    if (!className) throw new Error('MethodNode.createWithContext: className is required');
+    if (!context.file) throw new Error('MethodNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('MethodNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('MethodNode.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,
       className,
       async: options.async || false,
       generator: options.generator || false,

package/src/core/nodes/ModuleNode.ts

@@ -1,9 +1,19 @@
 /**
  * ModuleNode - contract for MODULE node
+ *
+ * Supports two creation modes:
+ * 1. createWithContext() - NEW: Uses ScopeContext for semantic IDs
+ * 2. create() - LEGACY: Uses hash-based IDs for backward compatibility
+ *
+ * Semantic ID format: {file}->global->MODULE->module
+ * Example: src/index.js->global->MODULE->module
+ *
+ * Each file has exactly one MODULE node. The name in the ID is always "module".
  */
 
 import { createHash } from 'crypto';
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext } from '../SemanticId.js';
 
 interface ModuleNodeRecord extends BaseNodeRecord {
   type: 'MODULE';
@@ -15,6 +25,14 @@ interface ModuleNodeOptions {
   isTest?: boolean;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface ModuleContextOptions {
+  contentHash?: string;
+  isTest?: boolean;
+}
+
 export class ModuleNode {
   static readonly TYPE = 'MODULE' as const;
 
@@ -49,6 +67,38 @@ export class ModuleNode {
     };
   }
 
+  /**
+   * Create MODULE node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext for stable identifiers that don't change
+   * when file content changes (unlike hash-based IDs).
+   *
+   * Each file has exactly one MODULE node.
+   * The name in the semantic ID is always "module".
+   *
+   * @param context - Scope context with file path (relative to project root)
+   * @param options - Optional contentHash and isTest flag
+   * @returns ModuleNodeRecord with semantic ID
+   */
+  static createWithContext(
+    context: ScopeContext,
+    options: ModuleContextOptions = {}
+  ): ModuleNodeRecord {
+    if (!context.file) throw new Error('ModuleNode.createWithContext: file is required in context');
+
+    const id = computeSemanticId(this.TYPE, 'module', context);
+
+    return {
+      id,
+      type: this.TYPE,
+      name: context.file,
+      file: context.file,
+      line: 0,
+      contentHash: options.contentHash || '',
+      isTest: options.isTest || false
+    };
+  }
+
   static _hashPath(path: string): string {
     return createHash('md5').update(path).digest('hex').substring(0, 12);
   }

package/src/core/nodes/NetworkRequestNode.ts

@@ -0,0 +1,77 @@
+/**
+ * NetworkRequestNode - contract for net:request singleton node
+ *
+ * Represents the external network as a system resource.
+ * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+ *
+ * This is NOT the same as HttpRequestNode (type: HTTP_REQUEST), which represents
+ * individual HTTP request call sites in source code.
+ *
+ * Architectural role:
+ * - net:request is a singleton representing external network (like net:stdio for console I/O)
+ * - HTTP_REQUEST nodes are call sites that connect to this singleton via CALLS edges
+ *
+ * Example graph structure:
+ * ```
+ * /app/api.ts:HTTP_REQUEST:GET:15:0 --CALLS--> net:request#__network__
+ * /app/service.ts:HTTP_REQUEST:POST:42:0 --CALLS--> net:request#__network__
+ * ```
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface NetworkRequestNodeRecord extends BaseNodeRecord {
+  type: 'net:request';
+}
+
+export class NetworkRequestNode {
+  static readonly TYPE = 'net:request' as const;
+  static readonly SINGLETON_ID = 'net:request#__network__';
+
+  static readonly REQUIRED = ['name', 'file'] as const;
+  static readonly OPTIONAL = [] as const;
+
+  /**
+   * Create net:request singleton node
+   *
+   * This node represents the external network as a system resource.
+   * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+   *
+   * Should be created once per graph. GraphBuilder and ExpressAnalyzer
+   * use singleton deduplication to ensure only one instance exists.
+   *
+   * @returns NetworkRequestNodeRecord - singleton node
+   */
+  static create(): NetworkRequestNodeRecord {
+    return {
+      id: this.SINGLETON_ID,
+      type: this.TYPE,
+      name: '__network__',
+      file: '__builtin__',
+      line: 0
+    };
+  }
+
+  /**
+   * Validate net:request node structure
+   *
+   * Ensures:
+   * - type is net:request (NOT NET_REQUEST)
+   * - id matches SINGLETON_ID
+   *
+   * @param node - Node to validate
+   * @returns Array of error messages (empty if valid)
+   */
+  static validate(node: NetworkRequestNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+    if (node.id !== this.SINGLETON_ID) {
+      errors.push(`Invalid singleton ID: expected ${this.SINGLETON_ID}, got ${node.id}`);
+    }
+    return errors;
+  }
+}
+
+export type { NetworkRequestNodeRecord };

package/src/core/nodes/ObjectLiteralNode.ts

@@ -0,0 +1,66 @@
+/**
+ * ObjectLiteralNode - contract for OBJECT_LITERAL node
+ *
+ * Represents an object literal expression: { key: value, ... }
+ * Used for tracking data flow through object construction.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ObjectLiteralNodeRecord extends BaseNodeRecord {
+  type: 'OBJECT_LITERAL';
+  column: number;
+  parentCallId?: string;
+  argIndex?: number;
+}
+
+interface ObjectLiteralNodeOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
+export class ObjectLiteralNode {
+  static readonly TYPE = 'OBJECT_LITERAL' as const;
+
+  static readonly REQUIRED = ['file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['parentCallId', 'argIndex'] as const;
+
+  static create(
+    file: string,
+    line: number,
+    column: number,
+    options: ObjectLiteralNodeOptions = {}
+  ): ObjectLiteralNodeRecord {
+    if (!file) throw new Error('ObjectLiteralNode.create: file is required');
+    if (line === undefined) throw new Error('ObjectLiteralNode.create: line is required');
+    if (column === undefined) throw new Error('ObjectLiteralNode.create: column is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const argSuffix = options.argIndex !== undefined ? `arg${options.argIndex}` : 'obj';
+    const id = `OBJECT_LITERAL#${argSuffix}#${file}#${line}:${column}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: `<object>`,
+      file,
+      line,
+      column,
+      parentCallId: options.parentCallId,
+      argIndex: options.argIndex
+    };
+  }
+
+  static validate(node: ObjectLiteralNodeRecord): string[] {
+    const errors: string[] = [];
+    if (node.type !== this.TYPE) errors.push(`Expected type ${this.TYPE}`);
+    const nodeRecord = node as unknown as Record<string, unknown>;
+    for (const field of this.REQUIRED) {
+      if (nodeRecord[field] === undefined) errors.push(`Missing: ${field}`);
+    }
+    return errors;
+  }
+}
+
+export type { ObjectLiteralNodeRecord, ObjectLiteralNodeOptions };

package/src/core/nodes/ParameterNode.ts

@@ -22,8 +22,8 @@ interface ParameterNodeOptions {
 export class ParameterNode {
   static readonly TYPE = 'PARAMETER' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line', 'functionId'] as const;
-  static readonly OPTIONAL = ['column', 'index', 'defaultValue', 'rest'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'functionId'] as const;
+  static readonly OPTIONAL = ['index', 'defaultValue', 'rest'] as const;
 
   static create(
     name: string,
@@ -36,6 +36,7 @@ export class ParameterNode {
     if (!name) throw new Error('ParameterNode.create: name is required');
     if (!file) throw new Error('ParameterNode.create: file is required');
     if (!line) throw new Error('ParameterNode.create: line is required');
+    if (column === undefined) throw new Error('ParameterNode.create: column is required');
     if (!functionId) throw new Error('ParameterNode.create: functionId is required');
 
     return {
@@ -44,7 +45,7 @@ export class ParameterNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
       functionId,
       index: options.index || 0,
       defaultValue: options.defaultValue,

package/src/core/nodes/ScopeNode.ts

@@ -1,8 +1,16 @@
 /**
  * ScopeNode - contract for SCOPE 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}->SCOPE->{scopeType}#N
+ * Example: src/app.js->handler->SCOPE->if#0
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface ScopeNodeRecord extends BaseNodeRecord {
   type: 'SCOPE';
@@ -22,6 +30,17 @@ interface ScopeNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface ScopeContextOptions {
+  discriminator: number;
+  conditional?: boolean;
+  parentScopeId?: string;
+  parentFunctionId?: string;
+  capturesFrom?: string[];
+}
+
 export class ScopeNode {
   static readonly TYPE = 'SCOPE' as const;
 
@@ -59,6 +78,52 @@ export class ScopeNode {
     };
   }
 
+  /**
+   * Create SCOPE node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Requires discriminator for multiple scopes of same type within parent scope.
+   *
+   * @param scopeType - Type of scope (if, else, try, catch, finally, for, while, switch)
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line }
+   * @param options - Options including required discriminator
+   * @returns ScopeNodeRecord with semantic ID
+   */
+  static createWithContext(
+    scopeType: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: ScopeContextOptions
+  ): ScopeNodeRecord {
+    // Validate required fields
+    if (!scopeType) throw new Error('ScopeNode.createWithContext: scopeType is required');
+    if (!context.file) throw new Error('ScopeNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('ScopeNode.createWithContext: line is required');
+    if (options.discriminator === undefined) throw new Error('ScopeNode.createWithContext: discriminator is required');
+
+    // Compute semantic ID with discriminator
+    const id = computeSemanticId('SCOPE', scopeType, context, {
+      discriminator: options.discriminator
+    });
+
+    // Name includes the discriminator for display purposes
+    const name = `${scopeType}#${options.discriminator}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      scopeType,
+      name,
+      file: context.file,
+      line: location.line,
+      conditional: options.conditional || false,
+      parentScopeId: options.parentScopeId,
+      parentFunctionId: options.parentFunctionId,
+      capturesFrom: options.capturesFrom
+    };
+  }
+
   static validate(node: ScopeNodeRecord): string[] {
     const errors: string[] = [];
 

package/src/core/nodes/TypeNode.ts

@@ -0,0 +1,79 @@
+/**
+ * TypeNode - contract for TYPE node
+ *
+ * Represents TypeScript type alias declarations.
+ *
+ * ID format: {file}:TYPE:{name}:{line}
+ * Example: /src/types.ts:TYPE:UserId:10
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface TypeNodeRecord extends BaseNodeRecord {
+  type: 'TYPE';
+  column: number;
+  aliasOf?: string;
+}
+
+interface TypeNodeOptions {
+  aliasOf?: string;
+}
+
+export class TypeNode {
+  static readonly TYPE = 'TYPE' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['aliasOf'] as const;
+
+  /**
+   * Create TYPE node
+   *
+   * @param name - Type alias name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional type properties
+   * @returns TypeNodeRecord
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: TypeNodeOptions = {}
+  ): TypeNodeRecord {
+    if (!name) throw new Error('TypeNode.create: name is required');
+    if (!file) throw new Error('TypeNode.create: file is required');
+    if (!line) throw new Error('TypeNode.create: line is required');
+    if (column === undefined) throw new Error('TypeNode.create: column is required');
+
+    return {
+      id: `${file}:TYPE:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      aliasOf: options.aliasOf
+    };
+  }
+
+  static validate(node: TypeNodeRecord): 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]) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { TypeNodeRecord };