@grafema/core 0.1.0-alpha.5 → 0.1.1-alpha

package/src/core/nodes/EnumNode.ts

@@ -0,0 +1,86 @@
+/**
+ * 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'] as const;
+  static readonly OPTIONAL = ['column', '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');
+
+    return {
+      id: `${file}:ENUM:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      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/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 OPTIONAL = ['column', 'exportKind', 'local', 'default', 'source', 'exportType'] as const;
 
   static create(
     name: string,
@@ -46,7 +71,50 @@ export class ExportNode {
       column: column || 0,
       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 })
+    };
+  }
+
+  /**
+   * 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');
+
+    // 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 ?? 0,
+      exportKind: options.exportKind || 'value',
+      local: options.local || name,
+      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,231 @@
+/**
+ * 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'] as const;
+  static readonly OPTIONAL = [
+    'column', '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');
+
+    const node: ExpressionNodeRecord = {
+      id: `${file}:EXPRESSION:${expressionType}:${line}:${column}`,
+      type: this.TYPE,
+      name: this._computeName(expressionType, options),
+      file,
+      line,
+      column: column || 0,
+      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: column || 0,
+      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,56 @@
+/**
+ * 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
+   *
+   * @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');
+
+    return {
+      id: `EXTERNAL_MODULE:${source}`,
+      type: this.TYPE,
+      name: source,
+      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;
   }
 }

package/src/core/nodes/FunctionNode.ts

@@ -1,9 +1,20 @@
 /**
  * FunctionNode - contract for FUNCTION 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}->FUNCTION->{name}
+ * Example: src/app.js->global->FUNCTION->processData
  */
 
 import type { FunctionNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
+/**
+ * Options for function node creation
+ */
 interface FunctionNodeOptions {
   async?: boolean;
   generator?: boolean;
@@ -16,6 +27,19 @@ interface FunctionNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options specific to createWithContext
+ */
+interface FunctionNodeContextOptions {
+  async?: boolean;
+  generator?: boolean;
+  exported?: boolean;
+  arrowFunction?: boolean;
+  isClassMethod?: boolean;
+  className?: string;
+  params?: string[];
+}
+
 export class FunctionNode {
   static readonly TYPE = 'FUNCTION' as const;
 
@@ -42,7 +66,6 @@ export class FunctionNode {
 
     return {
       id,
-      stableId: id,
       type: this.TYPE,
       name,
       file,
@@ -59,6 +82,83 @@ export class FunctionNode {
     };
   }
 
+  /**
+   * Create FUNCTION node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers that
+   * don't change when unrelated code is added/removed.
+   *
+   * @param name - Function name (or 'anonymous[N]' for anonymous functions)
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Optional function properties
+   * @returns FunctionNodeRecord with semantic ID
+   */
+  static createWithContext(
+    name: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: FunctionNodeContextOptions = {}
+  ): FunctionNodeRecord {
+    // Validate required fields
+    if (!name) throw new Error('FunctionNode.createWithContext: name is required');
+    if (!context.file) throw new Error('FunctionNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('FunctionNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('FunctionNode.createWithContext: column is required');
+
+    // Compute semantic ID
+    const id = computeSemanticId(this.TYPE, name, context);
+
+    // Compute parentScopeId from context
+    // If we have a scope path, the parent is the last scope in the path
+    let parentScopeId: string | undefined;
+    if (context.scopePath.length > 0) {
+      // Find the most recent function/method scope to use as parent
+      // For now, we construct the parent's semantic ID from the scope path
+      const parentContext = {
+        file: context.file,
+        scopePath: context.scopePath.slice(0, -1) // Remove last scope
+      };
+      const parentScopeName = context.scopePath[context.scopePath.length - 1];
+
+      // Check if parent is a function/method scope (not a control flow scope)
+      if (!parentScopeName.includes('#')) {
+        // Named scope - likely a function or class
+        parentScopeId = computeSemanticId('FUNCTION', parentScopeName, parentContext);
+      } else {
+        // Control flow scope - find the nearest function ancestor
+        // For simplicity, take the first non-control-flow scope from the path
+        const nonControlFlowScopes = context.scopePath.filter(s => !s.includes('#'));
+        if (nonControlFlowScopes.length > 0) {
+          const parentName = nonControlFlowScopes[nonControlFlowScopes.length - 1];
+          const idx = context.scopePath.indexOf(parentName);
+          const ancestorContext = {
+            file: context.file,
+            scopePath: context.scopePath.slice(0, idx)
+          };
+          parentScopeId = computeSemanticId('FUNCTION', parentName, ancestorContext);
+        }
+      }
+    }
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      file: context.file,
+      line: location.line,
+      column: location.column,
+      async: options.async || false,
+      generator: options.generator || false,
+      exported: options.exported || false,
+      arrowFunction: options.arrowFunction || false,
+      parentScopeId,
+      isClassMethod: options.isClassMethod || false,
+      className: options.className,
+      params: options.params || []
+    };
+  }
+
   static validate(node: FunctionNodeRecord): string[] {
     const errors: string[] = [];