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

package/src/core/nodes/DecoratorNode.ts

@@ -0,0 +1,92 @@
+/**
+ * DecoratorNode - contract for DECORATOR node
+ *
+ * Represents TypeScript/JavaScript decorators applied to
+ * classes, methods, properties, or parameters.
+ *
+ * ID format: {file}:DECORATOR:{name}:{line}:{column}
+ * Example: /src/services/UserService.ts:DECORATOR:Injectable:5:0
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+type DecoratorTargetType = 'CLASS' | 'METHOD' | 'PROPERTY' | 'PARAMETER';
+
+interface DecoratorNodeRecord extends BaseNodeRecord {
+  type: 'DECORATOR';
+  column: number;
+  arguments: unknown[];
+  targetId: string;
+  targetType: DecoratorTargetType;
+}
+
+interface DecoratorNodeOptions {
+  arguments?: unknown[];
+}
+
+export class DecoratorNode {
+  static readonly TYPE = 'DECORATOR' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column', 'targetId', 'targetType'] as const;
+  static readonly OPTIONAL = ['arguments'] as const;
+
+  /**
+   * Create DECORATOR node
+   *
+   * @param name - Decorator name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param targetId - ID of decorated element
+   * @param targetType - Type of decorated element
+   * @param options - Optional decorator properties
+   * @returns DecoratorNodeRecord
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    targetId: string,
+    targetType: DecoratorTargetType,
+    options: DecoratorNodeOptions = {}
+  ): DecoratorNodeRecord {
+    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');
+
+    return {
+      id: `${file}:DECORATOR:${name}:${line}:${column}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      arguments: options.arguments || [],
+      targetId,
+      targetType
+    };
+  }
+
+  static validate(node: DecoratorNodeRecord): 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 { DecoratorNodeRecord, DecoratorTargetType };

package/src/core/nodes/EnumNode.ts

@@ -0,0 +1,87 @@
+/**
+ * EnumNode - contract for ENUM node
+ *
+ * Represents TypeScript enum declarations.
+ *
+ * ID format: {file}:ENUM:{name}:{line}
+ * Example: /src/types.ts:ENUM:Status:20
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface EnumMemberRecord {
+  name: string;
+  value?: string | number;
+}
+
+interface EnumNodeRecord extends BaseNodeRecord {
+  type: 'ENUM';
+  column: number;
+  isConst: boolean;
+  members: EnumMemberRecord[];
+}
+
+interface EnumNodeOptions {
+  isConst?: boolean;
+  members?: EnumMemberRecord[];
+}
+
+export class EnumNode {
+  static readonly TYPE = 'ENUM' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['isConst', 'members'] as const;
+
+  /**
+   * Create ENUM node
+   *
+   * @param name - Enum name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional enum properties
+   * @returns EnumNodeRecord
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: EnumNodeOptions = {}
+  ): EnumNodeRecord {
+    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}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      isConst: options.isConst || false,
+      members: options.members || []
+    };
+  }
+
+  static validate(node: EnumNodeRecord): 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 { EnumNodeRecord, EnumMemberRecord };

package/src/core/nodes/EventListenerNode.ts

@@ -6,13 +6,13 @@ import type { BaseNodeRecord } from '@grafema/types';
 
 interface EventListenerNodeRecord extends BaseNodeRecord {
   type: 'EVENT_LISTENER';
+  column: number;
   object?: string;
   parentScopeId?: string;
   callbackArg?: string;
 }
 
 interface EventListenerNodeOptions {
-  column?: number;
   parentScopeId?: string;
   callbackArg?: string;
   counter?: number;
@@ -21,22 +21,24 @@ interface EventListenerNodeOptions {
 export class EventListenerNode {
   static readonly TYPE = 'EVENT_LISTENER' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['object', 'column', 'parentScopeId', 'callbackArg'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['object', 'parentScopeId', 'callbackArg'] as const;
 
   static create(
     eventName: string,
     objectName: string | undefined,
     file: string,
     line: number,
+    column: number,
     options: EventListenerNodeOptions = {}
   ): EventListenerNodeRecord {
     if (!eventName) throw new Error('EventListenerNode.create: eventName is required');
     if (!file) throw new Error('EventListenerNode.create: file is required');
     if (line === undefined) throw new Error('EventListenerNode.create: line is required');
+    if (column === undefined) throw new Error('EventListenerNode.create: column is required');
 
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
-    const id = `${file}:EVENT_LISTENER:${eventName}:${line}:${options.column || 0}${counter}`;
+    const id = `${file}:EVENT_LISTENER:${eventName}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -45,6 +47,7 @@ export class EventListenerNode {
       object: objectName,
       file,
       line,
+      column,
       parentScopeId: options.parentScopeId,
       callbackArg: options.callbackArg
     };

package/src/core/nodes/ExportNode.ts

@@ -1,30 +1,55 @@
 /**
  * ExportNode - contract for EXPORT 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}->global->EXPORT->{exportedName}
+ * Example: src/utils.js->global->EXPORT->formatDate
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 type ExportKind = 'value' | 'type';
 
+type ExportType = 'default' | 'named' | 'all';
+
 interface ExportNodeRecord extends BaseNodeRecord {
   type: 'EXPORT';
   column: number;
   exportKind: ExportKind;
   local: string;
   default: boolean;
+  source?: string;
+  exportType?: ExportType;
 }
 
 interface ExportNodeOptions {
   exportKind?: ExportKind;
   local?: string;
   default?: boolean;
+  source?: string;
+  exportType?: ExportType;
+}
+
+/**
+ * Options for createWithContext
+ */
+interface ExportContextOptions {
+  exportKind?: ExportKind;
+  local?: string;
+  default?: boolean;
+  source?: string;
+  exportType?: ExportType;
 }
 
 export class ExportNode {
   static readonly TYPE = 'EXPORT' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'exportKind', 'local', 'default'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['exportKind', 'local', 'default', 'source', 'exportType'] as const;
 
   static create(
     name: string,
@@ -36,6 +61,7 @@ export class ExportNode {
     if (!name) throw new Error('ExportNode.create: name is required');
     if (!file) throw new Error('ExportNode.create: file is required');
     if (!line) throw new Error('ExportNode.create: line is required');
+    if (column === undefined) throw new Error('ExportNode.create: column is required');
 
     return {
       id: `${file}:EXPORT:${name}:${line}`,
@@ -43,10 +69,54 @@ export class ExportNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
+      exportKind: options.exportKind || 'value',
+      local: options.local || name,
+      default: options.default || false,
+      ...(options.source !== undefined && { source: options.source }),
+      ...(options.exportType !== undefined && { exportType: options.exportType })
+    };
+  }
+
+  /**
+   * Create EXPORT node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Export names are unique within module, so no discriminator needed.
+   *
+   * @param name - Exported name (as visible to importers)
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Optional export properties
+   * @returns ExportNodeRecord with semantic ID
+   */
+  static createWithContext(
+    name: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: ExportContextOptions = {}
+  ): ExportNodeRecord {
+    // Validate required fields
+    if (!name) throw new Error('ExportNode.createWithContext: name is required');
+    if (!context.file) throw new Error('ExportNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('ExportNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('ExportNode.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,
       exportKind: options.exportKind || 'value',
       local: options.local || name,
-      default: options.default || false
+      default: options.default || false,
+      ...(options.source !== undefined && { source: options.source }),
+      ...(options.exportType !== undefined && { exportType: options.exportType })
     };
   }
 

package/src/core/nodes/ExpressionNode.ts

@@ -0,0 +1,232 @@
+/**
+ * ExpressionNode - contract for EXPRESSION node
+ *
+ * Represents complex expressions for data flow tracking
+ * (MemberExpression, BinaryExpression, LogicalExpression, etc.)
+ *
+ * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+ * Example: /src/app.ts:EXPRESSION:MemberExpression:25:10
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ExpressionNodeRecord extends BaseNodeRecord {
+  type: 'EXPRESSION';
+  column: number;
+  expressionType: string;
+  // MemberExpression fields
+  object?: string;
+  property?: string;
+  computed?: boolean;
+  computedPropertyVar?: string;
+  // Binary/Logical expression fields
+  operator?: string;
+  // Tracking fields
+  path?: string;
+  baseName?: string;
+  propertyPath?: string[];
+  arrayIndex?: number;
+}
+
+interface ExpressionNodeOptions {
+  // MemberExpression
+  object?: string;
+  property?: string;
+  computed?: boolean;
+  computedPropertyVar?: string;
+  // Binary/Logical
+  operator?: string;
+  // Tracking
+  path?: string;
+  baseName?: string;
+  propertyPath?: string[];
+  arrayIndex?: number;
+}
+
+export class ExpressionNode {
+  static readonly TYPE = 'EXPRESSION' as const;
+
+  static readonly REQUIRED = ['expressionType', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = [
+    'object', 'property', 'computed', 'computedPropertyVar',
+    'operator', 'path', 'baseName', 'propertyPath', 'arrayIndex'
+  ] as const;
+
+  /**
+   * Create EXPRESSION node
+   *
+   * @param expressionType - Type of expression (MemberExpression, BinaryExpression, etc.)
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional expression properties
+   * @returns ExpressionNodeRecord
+   */
+  static create(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExpressionNodeOptions = {}
+  ): ExpressionNodeRecord {
+    if (!expressionType) throw new Error('ExpressionNode.create: expressionType is required');
+    if (!file) throw new Error('ExpressionNode.create: file is required');
+    if (!line) throw new Error('ExpressionNode.create: line is required');
+    if (column === undefined) throw new Error('ExpressionNode.create: column is required');
+
+    const node: ExpressionNodeRecord = {
+      id: `${file}:EXPRESSION:${expressionType}:${line}:${column}`,
+      type: this.TYPE,
+      name: this._computeName(expressionType, options),
+      file,
+      line,
+      column,
+      expressionType
+    };
+
+    // Add optional fields if present
+    if (options.object !== undefined) node.object = options.object;
+    if (options.property !== undefined) node.property = options.property;
+    if (options.computed !== undefined) node.computed = options.computed;
+    if (options.computedPropertyVar !== undefined) node.computedPropertyVar = options.computedPropertyVar;
+    if (options.operator !== undefined) node.operator = options.operator;
+    if (options.path !== undefined) node.path = options.path;
+    if (options.baseName !== undefined) node.baseName = options.baseName;
+    if (options.propertyPath !== undefined) node.propertyPath = options.propertyPath;
+    if (options.arrayIndex !== undefined) node.arrayIndex = options.arrayIndex;
+
+    return node;
+  }
+
+  /**
+   * Compute name from expression properties
+   *
+   * Naming conventions:
+   * - MemberExpression: "object.property"
+   * - BinaryExpression: "<BinaryExpression>"
+   * - LogicalExpression: "<LogicalExpression>"
+   * - ConditionalExpression: "<ternary>"
+   * - TemplateLiteral: "<template>"
+   * - Other: expressionType
+   */
+  private static _computeName(expressionType: string, options: ExpressionNodeOptions): string {
+    if (options.path) {
+      return options.path;
+    }
+    if (options.object && options.property) {
+      return `${options.object}.${options.property}`;
+    }
+    // Special naming for non-MemberExpression types
+    switch (expressionType) {
+      case 'BinaryExpression':
+      case 'LogicalExpression':
+        return `<${expressionType}>`;
+      case 'ConditionalExpression':
+        return '<ternary>';
+      case 'TemplateLiteral':
+        return '<template>';
+      default:
+        return expressionType;
+    }
+  }
+
+  /**
+   * Generate EXPRESSION node ID without creating the full node
+   *
+   * Used by JSASTAnalyzer when creating assignment metadata.
+   * The full node is created later by GraphBuilder.
+   *
+   * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+   *
+   * @param expressionType - Type of expression (MemberExpression, BinaryExpression, etc.)
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @returns Generated ID string in colon format
+   */
+  static generateId(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number
+  ): string {
+    return `${file}:EXPRESSION:${expressionType}:${line}:${column}`;
+  }
+
+  /**
+   * Create EXPRESSION node from assignment metadata
+   *
+   * Used by GraphBuilder when processing variableAssignments.
+   * The ID is provided from upstream (generated by JSASTAnalyzer).
+   *
+   * @param expressionType - Type of expression
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Must include id; optional: expression properties
+   * @returns ExpressionNodeRecord
+   */
+  static createFromMetadata(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExpressionNodeOptions & { id: string }
+  ): ExpressionNodeRecord {
+    if (!options.id) {
+      throw new Error('ExpressionNode.createFromMetadata: id is required');
+    }
+
+    // Validate ID format - must use colon format
+    if (!options.id.includes(':EXPRESSION:')) {
+      throw new Error(
+        `ExpressionNode.createFromMetadata: Invalid ID format "${options.id}". ` +
+        `Expected format: {file}:EXPRESSION:{type}:{line}:{column}`
+      );
+    }
+
+    // Create base node structure
+    const node: ExpressionNodeRecord = {
+      id: options.id,  // Use provided ID (from upstream)
+      type: this.TYPE,
+      name: this._computeName(expressionType, options),
+      file,
+      line,
+      column,
+      expressionType
+    };
+
+    // Add optional fields if present (same logic as create())
+    if (options.object !== undefined) node.object = options.object;
+    if (options.property !== undefined) node.property = options.property;
+    if (options.computed !== undefined) node.computed = options.computed;
+    if (options.computedPropertyVar !== undefined) node.computedPropertyVar = options.computedPropertyVar;
+    if (options.operator !== undefined) node.operator = options.operator;
+    if (options.path !== undefined) node.path = options.path;
+    if (options.baseName !== undefined) node.baseName = options.baseName;
+    if (options.propertyPath !== undefined) node.propertyPath = options.propertyPath;
+    if (options.arrayIndex !== undefined) node.arrayIndex = options.arrayIndex;
+
+    return node;
+  }
+
+  static validate(node: ExpressionNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    if (!node.expressionType) {
+      errors.push('Missing required field: expressionType');
+    }
+
+    if (!node.file) {
+      errors.push('Missing required field: file');
+    }
+
+    return errors;
+  }
+}
+
+export type { ExpressionNodeRecord, ExpressionNodeOptions };

package/src/core/nodes/ExternalModuleNode.ts

@@ -0,0 +1,65 @@
+/**
+ * ExternalModuleNode - contract for EXTERNAL_MODULE node
+ *
+ * Represents external npm packages or Node.js built-in modules
+ * that are imported but not analyzed.
+ *
+ * ID format: EXTERNAL_MODULE:{source}
+ * Example: EXTERNAL_MODULE:lodash, EXTERNAL_MODULE:@tanstack/react-query
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ExternalModuleNodeRecord extends BaseNodeRecord {
+  type: 'EXTERNAL_MODULE';
+}
+
+export class ExternalModuleNode {
+  static readonly TYPE = 'EXTERNAL_MODULE' as const;
+
+  static readonly REQUIRED = ['name'] as const;
+  static readonly OPTIONAL = [] as const;
+
+  /**
+   * Create EXTERNAL_MODULE node
+   *
+   * Normalizes node: prefix for Node.js builtins:
+   * - 'node:fs' -> 'fs'
+   * - 'node:path' -> 'path'
+   *
+   * @param source - Module name (e.g., 'lodash', '@tanstack/react-query', 'node:fs')
+   * @returns ExternalModuleNodeRecord
+   */
+  static create(source: string): ExternalModuleNodeRecord {
+    if (!source) throw new Error('ExternalModuleNode.create: source is required');
+
+    // Normalize node: prefix for Node.js builtins
+    const normalizedSource = source.startsWith('node:')
+      ? source.slice(5)
+      : source;
+
+    return {
+      id: `EXTERNAL_MODULE:${normalizedSource}`,
+      type: this.TYPE,
+      name: normalizedSource,
+      file: '',
+      line: 0
+    };
+  }
+
+  static validate(node: ExternalModuleNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (node.type !== this.TYPE) {
+      errors.push(`Expected type ${this.TYPE}, got ${node.type}`);
+    }
+
+    if (!node.name) {
+      errors.push('Missing required field: name');
+    }
+
+    return errors;
+  }
+}
+
+export type { ExternalModuleNodeRecord };

package/src/core/nodes/ExternalStdioNode.ts

@@ -1,19 +1,26 @@
 /**
- * ExternalStdioNode - contract for EXTERNAL_STDIO node (singleton)
+ * ExternalStdioNode - contract for net:stdio node (singleton)
+ *
+ * Represents standard I/O streams (console.log, console.error, etc.)
+ * Singleton node - only one instance per graph.
+ *
+ * Uses namespaced type 'net:stdio' for semantic grouping - AI agents
+ * can query all I/O-related nodes via 'net:*' pattern.
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
 
 interface ExternalStdioNodeRecord extends BaseNodeRecord {
-  type: 'EXTERNAL_STDIO';
+  type: 'net:stdio';
+  description?: string;
 }
 
 export class ExternalStdioNode {
-  static readonly TYPE = 'EXTERNAL_STDIO' as const;
-  static readonly SINGLETON_ID = 'EXTERNAL_STDIO:__stdio__';
+  static readonly TYPE = 'net:stdio' as const;
+  static readonly SINGLETON_ID = 'net:stdio#__stdio__';
 
-  static readonly REQUIRED = ['name', 'file'] as const;
-  static readonly OPTIONAL = [] as const;
+  static readonly REQUIRED = ['name'] as const;
+  static readonly OPTIONAL = ['description'] as const;
 
   static create(): ExternalStdioNodeRecord {
     return {
@@ -21,14 +28,15 @@ export class ExternalStdioNode {
       type: this.TYPE,
       name: '__stdio__',
       file: '__builtin__',
-      line: 0
+      line: 0,
+      description: 'Standard input/output stream'
     };
   }
 
   static validate(node: ExternalStdioNodeRecord): string[] {
     const errors: string[] = [];
-    if (node.type !== this.TYPE) errors.push(`Expected type ${this.TYPE}`);
-    if (node.id !== this.SINGLETON_ID) errors.push(`Invalid singleton ID`);
+    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: ${node.id}, expected ${this.SINGLETON_ID}`);
     return errors;
   }
 }