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

package/src/core/SemanticId.ts

@@ -0,0 +1,192 @@
+/**
+ * SemanticId - Stable identifiers for code elements
+ *
+ * Semantic IDs provide stable identifiers for code elements that don't change
+ * when unrelated code is added/removed (no line numbers in IDs).
+ *
+ * Format: {file}->{scope_path}->{type}->{name}[#discriminator]
+ *
+ * Examples:
+ *   src/app.js->global->FUNCTION->processData
+ *   src/app.js->UserService->METHOD->login
+ *   src/app.js->getUser->if#0->CALL->console.log#0
+ *
+ * Special formats:
+ *   Singletons: net:stdio->__stdio__
+ *   External modules: EXTERNAL_MODULE->lodash
+ */
+
+/**
+ * Location in source file
+ */
+export interface Location {
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+/**
+ * Scope context for semantic ID generation
+ */
+export interface ScopeContext {
+  /** Source file path */
+  file: string;
+  /** Array of scope names, e.g. ['MyClass', 'myMethod', 'if#1'] */
+  scopePath: string[];
+}
+
+/**
+ * Options for semantic ID generation
+ */
+export interface SemanticIdOptions {
+  /** Counter for disambiguation (#N) */
+  discriminator?: number;
+  /** Context string for special cases ([context]) */
+  context?: string;
+}
+
+/**
+ * Parsed semantic ID components
+ */
+export interface ParsedSemanticId {
+  file: string;
+  scopePath: string[];
+  type: string;
+  name: string;
+  discriminator?: number;
+  context?: string;
+}
+
+/**
+ * Item with name and location for discriminator computation
+ */
+export interface LocatedItem {
+  name: string;
+  location: Location;
+}
+
+/**
+ * Compute semantic ID for any node type.
+ *
+ * @param type - Node type (FUNCTION, CALL, VARIABLE, etc.)
+ * @param name - Node name
+ * @param context - Scope context from ScopeTracker
+ * @param options - Optional discriminator or context
+ * @returns Semantic ID string
+ */
+export function computeSemanticId(
+  type: string,
+  name: string,
+  context: ScopeContext,
+  options?: SemanticIdOptions
+): string {
+  const { file, scopePath } = context;
+  const scope = scopePath.length > 0 ? scopePath.join('->') : 'global';
+
+  let id = `${file}->${scope}->${type}->${name}`;
+
+  if (options?.discriminator !== undefined) {
+    id += `#${options.discriminator}`;
+  } else if (options?.context) {
+    id += `[${options.context}]`;
+  }
+
+  return id;
+}
+
+/**
+ * Parse semantic ID back to components.
+ *
+ * @param id - Semantic ID to parse
+ * @returns Parsed components or null if invalid
+ */
+export function parseSemanticId(id: string): ParsedSemanticId | null {
+  // Handle singletons
+  if (id.startsWith('net:stdio') || id.startsWith('net:request')) {
+    const [prefix, name] = id.split('->');
+    return {
+      file: '',
+      scopePath: [prefix],
+      type: 'SINGLETON',
+      name,
+      discriminator: undefined
+    };
+  }
+
+  if (id.startsWith('EXTERNAL_MODULE')) {
+    const [, name] = id.split('->');
+    return {
+      file: '',
+      scopePath: [],
+      type: 'EXTERNAL_MODULE',
+      name,
+      discriminator: undefined
+    };
+  }
+
+  const parts = id.split('->');
+  if (parts.length < 4) return null;
+
+  const file = parts[0];
+  const type = parts[parts.length - 2];
+  let name = parts[parts.length - 1];
+  const scopePath = parts.slice(1, -2);
+
+  // Parse discriminator or context
+  let discriminator: number | undefined;
+  let context: string | undefined;
+
+  const hashMatch = name.match(/^(.+)#(\d+)$/);
+  if (hashMatch) {
+    name = hashMatch[1];
+    discriminator = parseInt(hashMatch[2], 10);
+  }
+
+  const bracketMatch = name.match(/^(.+)\[(.+)\]$/);
+  if (bracketMatch) {
+    name = bracketMatch[1];
+    context = bracketMatch[2];
+  }
+
+  return { file, scopePath, type, name, discriminator, context };
+}
+
+/**
+ * Compute discriminator for items with same name in same scope.
+ * Uses line/column for stable ordering.
+ *
+ * @param items - All items in scope
+ * @param targetName - Name to find discriminator for
+ * @param targetLocation - Location of target item
+ * @returns Discriminator (0-based index among same-named items)
+ */
+export function computeDiscriminator(
+  items: LocatedItem[],
+  targetName: string,
+  targetLocation: Location
+): number {
+  // Filter items with same name
+  const sameNameItems = items.filter(item => item.name === targetName);
+
+  if (sameNameItems.length <= 1) {
+    return 0;
+  }
+
+  // Sort by line, then by column for stable ordering
+  sameNameItems.sort((a, b) => {
+    if (a.location.line !== b.location.line) {
+      return a.location.line - b.location.line;
+    }
+    return a.location.column - b.location.column;
+  });
+
+  // Find index of target
+  const index = sameNameItems.findIndex(
+    item =>
+      item.location.line === targetLocation.line &&
+      item.location.column === targetLocation.column
+  );
+
+  return index >= 0 ? index : 0;
+}

package/src/core/VersionManager.ts

@@ -170,9 +170,10 @@ export class VersionManager {
       return `${type}:${name}:${file}:${line || 0}`;
     }
 
-    // Для MODULE - только file
+    // Для MODULE - use semantic ID format with name (relative path)
     if (type === 'MODULE') {
-      return `MODULE:${file}`;
+      // name stores the relative path for MODULE nodes
+      return `${name}->global->MODULE->module`;
     }
 
     // Для SERVICE - используем имя или file

package/src/core/nodes/ArgumentExpressionNode.ts

@@ -0,0 +1,89 @@
+/**
+ * ArgumentExpressionNode - EXPRESSION node with call argument context
+ *
+ * Extends ExpressionNode with fields tracking which call and argument position
+ * this expression appears in. Used for argument data flow tracking.
+ *
+ * ID format: {file}:EXPRESSION:{expressionType}:{line}:{column}
+ * With counter: {file}:EXPRESSION:{expressionType}:{line}:{column}:{counter}
+ *
+ * Example: /src/app.ts:EXPRESSION:BinaryExpression:25:10
+ *
+ * Note: Uses counter suffix since same expression at same position can appear
+ * multiple times in different argument contexts.
+ */
+
+import { ExpressionNode, type ExpressionNodeRecord, type ExpressionNodeOptions } from './ExpressionNode.js';
+
+interface ArgumentExpressionNodeRecord extends ExpressionNodeRecord {
+  parentCallId: string;
+  argIndex: number;
+}
+
+interface ArgumentExpressionNodeOptions extends ExpressionNodeOptions {
+  parentCallId: string;
+  argIndex: number;
+  counter?: number;
+}
+
+export class ArgumentExpressionNode {
+  // Inherit TYPE from ExpressionNode
+  static readonly TYPE = ExpressionNode.TYPE;
+  static readonly REQUIRED: readonly string[] = [...ExpressionNode.REQUIRED, 'parentCallId', 'argIndex'];
+  static readonly OPTIONAL: readonly string[] = [...ExpressionNode.OPTIONAL, 'counter'];
+
+  /**
+   * Create EXPRESSION node with argument context
+   *
+   * @param expressionType - Type of expression (BinaryExpression, LogicalExpression, etc.)
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Required: parentCallId, argIndex; Optional: expression properties, counter
+   * @returns ArgumentExpressionNodeRecord
+   */
+  static create(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ArgumentExpressionNodeOptions
+  ): ArgumentExpressionNodeRecord {
+    if (!options.parentCallId) {
+      throw new Error('ArgumentExpressionNode.create: parentCallId is required');
+    }
+    if (options.argIndex === undefined) {
+      throw new Error('ArgumentExpressionNode.create: argIndex is required');
+    }
+
+    // Create base EXPRESSION node using parent class
+    const baseNode = ExpressionNode.create(expressionType, file, line, column, options);
+
+    // Override ID with counter suffix (since same location can have multiple expressions)
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:EXPRESSION:${expressionType}:${line}:${column}${counter}`;
+
+    return {
+      ...baseNode,
+      id,
+      parentCallId: options.parentCallId,
+      argIndex: options.argIndex
+    };
+  }
+
+  static validate(node: ArgumentExpressionNodeRecord): string[] {
+    const errors = ExpressionNode.validate(node);
+
+    if (!node.parentCallId) {
+      errors.push('Missing required field: parentCallId');
+    }
+
+    if (node.argIndex === undefined) {
+      errors.push('Missing required field: argIndex');
+    }
+
+    return errors;
+  }
+}
+
+export type { ArgumentExpressionNodeRecord, ArgumentExpressionNodeOptions };

package/src/core/nodes/ArrayLiteralNode.ts

@@ -0,0 +1,65 @@
+/**
+ * ArrayLiteralNode - contract for ARRAY_LITERAL node
+ *
+ * Represents an array literal expression: [elem1, elem2, ...]
+ * Used for tracking data flow through array construction.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ArrayLiteralNodeRecord extends BaseNodeRecord {
+  type: 'ARRAY_LITERAL';
+  column: number;
+  parentCallId?: string;
+  argIndex?: number;
+}
+
+interface ArrayLiteralNodeOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
+export class ArrayLiteralNode {
+  static readonly TYPE = 'ARRAY_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: ArrayLiteralNodeOptions = {}
+  ): ArrayLiteralNodeRecord {
+    if (!file) throw new Error('ArrayLiteralNode.create: file is required');
+    if (line === undefined) throw new Error('ArrayLiteralNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const argSuffix = options.argIndex !== undefined ? `arg${options.argIndex}` : 'arr';
+    const id = `ARRAY_LITERAL#${argSuffix}#${file}#${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: `<array>`,
+      file,
+      line,
+      column: column || 0,
+      parentCallId: options.parentCallId,
+      argIndex: options.argIndex
+    };
+  }
+
+  static validate(node: ArrayLiteralNodeRecord): 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 { ArrayLiteralNodeRecord, ArrayLiteralNodeOptions };

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,6 +24,14 @@ interface CallSiteNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface CallSiteContextOptions {
+  discriminator: number;
+  parentScopeId?: string;
+}
+
 export class CallSiteNode {
   static readonly TYPE = 'CALL_SITE' as const;
 
@@ -51,6 +67,48 @@ export class CallSiteNode {
     };
   }
 
+  /**
+   * 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 (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 ?? 0,
+      parentScopeId: options.parentScopeId,
+      targetFunctionName: targetName
+    };
+  }
+
   static validate(node: CallSiteNodeRecord): string[] {
     const errors: string[] = [];
 

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 OPTIONAL = ['column', 'exported', 'superClass', 'methods', 'isInstantiationRef'] as const;
 
   static create(
     name: string,
@@ -44,7 +64,48 @@ export class ClassNode {
       column: column || 0,
       exported: options.exported || false,
       superClass: options.superClass,
-      methods: options.methods || []
+      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');
+
+    // 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,
+      exported: options.exported || false,
+      superClass: options.superClass,
+      methods: options.methods || [],
+      ...(options.isInstantiationRef !== undefined && { isInstantiationRef: options.isInstantiationRef })
     };
   }
 

package/src/core/nodes/DecoratorNode.ts

@@ -0,0 +1,91 @@
+/**
+ * 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', 'targetId', 'targetType'] as const;
+  static readonly OPTIONAL = ['column', '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 (!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: column || 0,
+      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 };