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

package/src/core/NodeFactory.ts

@@ -23,15 +23,35 @@ import {
   VariableDeclarationNode,
   ConstantNode,
   LiteralNode,
+  ObjectLiteralNode,
+  ArrayLiteralNode,
   ExternalStdioNode,
+  NetworkRequestNode,
   EventListenerNode,
   HttpRequestNode,
   DatabaseQueryNode,
+  ImportNode,
+  ClassNode,
+  ExportNode,
+  ExternalModuleNode,
+  InterfaceNode,
+  TypeNode,
+  EnumNode,
+  DecoratorNode,
+  ExpressionNode,
+  ArgumentExpressionNode,
+  IssueNode,
   type EntrypointType,
   type EntrypointTrigger,
+  type DecoratorTargetType,
+  type InterfacePropertyRecord,
+  type EnumMemberRecord,
+  type IssueSeverity,
 } from './nodes/index.js';
 
-import type { BaseNodeRecord } from '@grafema/types';
+import type { BaseNodeRecord, BrandedNode } from '@grafema/types';
+import { brandNode } from '@grafema/types';
+import type { ScopeContext } from './SemanticId.js';
 
 interface ServiceOptions {
   version?: string;
@@ -60,6 +80,11 @@ interface ModuleOptions {
   isTest?: boolean;
 }
 
+interface ModuleContextOptions {
+  contentHash?: string;
+  isTest?: boolean;
+}
+
 interface FunctionOptions {
   async?: boolean;
   generator?: boolean;
@@ -109,6 +134,18 @@ interface LiteralOptions {
   counter?: number;
 }
 
+interface ObjectLiteralOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
+interface ArrayLiteralOptions {
+  parentCallId?: string;
+  argIndex?: number;
+  counter?: number;
+}
+
 interface EventListenerOptions {
   column?: number;
   parentScopeId?: string;
@@ -126,6 +163,68 @@ interface DatabaseQueryOptions {
   parentScopeId?: string;
 }
 
+interface ImportOptions {
+  importType?: 'default' | 'named' | 'namespace';
+  importBinding?: 'value' | 'type' | 'typeof';
+  imported?: string;
+  local?: string;
+}
+
+interface ClassOptions {
+  exported?: boolean;
+  superClass?: string;
+  methods?: string[];
+  isInstantiationRef?: boolean;
+}
+
+interface ExportOptions {
+  exportKind?: 'value' | 'type';
+  local?: string;
+  default?: boolean;
+  source?: string;
+  exportType?: 'default' | 'named' | 'all';
+}
+
+interface InterfaceOptions {
+  extends?: string[];
+  properties?: InterfacePropertyRecord[];
+  isExternal?: boolean;
+}
+
+interface TypeOptions {
+  aliasOf?: string;
+}
+
+interface EnumOptions {
+  isConst?: boolean;
+  members?: EnumMemberRecord[];
+}
+
+interface DecoratorOptions {
+  arguments?: unknown[];
+}
+
+interface ExpressionOptions {
+  // MemberExpression
+  object?: string;
+  property?: string;
+  computed?: boolean;
+  computedPropertyVar?: string;
+  // Binary/Logical
+  operator?: string;
+  // Tracking
+  path?: string;
+  baseName?: string;
+  propertyPath?: string[];
+  arrayIndex?: number;
+}
+
+interface ArgumentExpressionOptions extends ExpressionOptions {
+  parentCallId: string;
+  argIndex: number;
+  counter?: number;
+}
+
 // Validator type for node classes
 interface NodeValidator {
   validate(node: BaseNodeRecord): string[];
@@ -136,18 +235,18 @@ export class NodeFactory {
    * Create SERVICE node
    */
   static createService(name: string, projectPath: string, options: ServiceOptions = {}) {
-    return ServiceNode.create(name, projectPath, options);
+    return brandNode(ServiceNode.create(name, projectPath, options));
   }
 
   /**
    * Create ENTRYPOINT node
    */
   static createEntrypoint(file: string, entrypointType: EntrypointType, options: EntrypointOptions = {}) {
-    return EntrypointNode.create(file, entrypointType, options);
+    return brandNode(EntrypointNode.create(file, entrypointType, options));
   }
 
   /**
-   * Create MODULE node
+   * Create MODULE node (LEGACY)
    */
   static createModule(filePath: string, projectPath: string, options: ModuleOptions = {}) {
     if (!filePath) throw new Error('NodeFactory.createModule: filePath is required');
@@ -156,84 +255,351 @@ export class NodeFactory {
     const contentHash = options.contentHash || this._hashFile(filePath);
     const relativePath = relative(projectPath, filePath) || basename(filePath);
 
-    return ModuleNode.create(filePath, relativePath, contentHash, options);
+    return brandNode(ModuleNode.create(filePath, relativePath, contentHash, options));
+  }
+
+  /**
+   * Create MODULE node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext for stable identifiers.
+   *
+   * @param context - Scope context with file path (relative to project root)
+   * @param options - Optional contentHash and isTest flag
+   * @returns ModuleNodeRecord with semantic ID
+   */
+  static createModuleWithContext(context: ScopeContext, options: ModuleContextOptions = {}) {
+    return brandNode(ModuleNode.createWithContext(context, options));
   }
 
   /**
    * Create FUNCTION node
    */
   static createFunction(name: string, file: string, line: number, column: number, options: FunctionOptions = {}) {
-    return FunctionNode.create(name, file, line, column, options);
+    return brandNode(FunctionNode.create(name, file, line, column, options));
   }
 
   /**
    * Create SCOPE node
    */
   static createScope(scopeType: string, file: string, line: number, options: ScopeOptions = {}) {
-    return ScopeNode.create(scopeType, file, line, options);
+    return brandNode(ScopeNode.create(scopeType, file, line, options));
   }
 
   /**
    * Create CALL_SITE node
    */
   static createCallSite(targetName: string, file: string, line: number, column: number, options: CallSiteOptions = {}) {
-    return CallSiteNode.create(targetName, file, line, column, options);
+    return brandNode(CallSiteNode.create(targetName, file, line, column, options));
   }
 
   /**
    * Create METHOD_CALL node
    */
   static createMethodCall(objectName: string | undefined, methodName: string, file: string, line: number, column: number, options: MethodCallOptions = {}) {
-    return MethodCallNode.create(objectName, methodName, file, line, column, options);
+    return brandNode(MethodCallNode.create(objectName, methodName, file, line, column, options));
   }
 
   /**
    * Create VARIABLE_DECLARATION node
    */
   static createVariableDeclaration(name: string, file: string, line: number, column: number, options: VariableOptions = {}) {
-    return VariableDeclarationNode.create(name, file, line, column, options);
+    return brandNode(VariableDeclarationNode.create(name, file, line, column, options));
   }
 
   /**
    * Create CONSTANT node
    */
   static createConstant(name: string, file: string, line: number, column: number, options: ConstantOptions = {}) {
-    return ConstantNode.create(name, file, line, column, options);
+    return brandNode(ConstantNode.create(name, file, line, column, options));
   }
 
   /**
    * Create LITERAL node
    */
   static createLiteral(value: unknown, file: string, line: number, column: number, options: LiteralOptions = {}) {
-    return LiteralNode.create(value, file, line, column, options);
+    return brandNode(LiteralNode.create(value, file, line, column, options));
+  }
+
+  /**
+   * Create OBJECT_LITERAL node
+   */
+  static createObjectLiteral(file: string, line: number, column: number, options: ObjectLiteralOptions = {}) {
+    return brandNode(ObjectLiteralNode.create(file, line, column, options));
+  }
+
+  /**
+   * Create ARRAY_LITERAL node
+   */
+  static createArrayLiteral(file: string, line: number, column: number, options: ArrayLiteralOptions = {}) {
+    return brandNode(ArrayLiteralNode.create(file, line, column, options));
   }
 
   /**
    * Create EXTERNAL_STDIO node (singleton)
    */
   static createExternalStdio() {
-    return ExternalStdioNode.create();
+    return brandNode(ExternalStdioNode.create());
+  }
+
+  /**
+   * Create net:request singleton node
+   *
+   * This node represents the external network as a system resource.
+   * Should be created once per graph.
+   *
+   * All HTTP_REQUEST nodes connect to this singleton via CALLS edges.
+   *
+   * @returns NetworkRequestNodeRecord - singleton node
+   */
+  static createNetworkRequest() {
+    return brandNode(NetworkRequestNode.create());
   }
 
   /**
    * Create EVENT_LISTENER node
    */
   static createEventListener(eventName: string, objectName: string | undefined, file: string, line: number, options: EventListenerOptions = {}) {
-    return EventListenerNode.create(eventName, objectName, file, line, options);
+    return brandNode(EventListenerNode.create(eventName, objectName, file, line, options));
   }
 
   /**
    * Create HTTP_REQUEST node
    */
   static createHttpRequest(url: string | undefined, method: string | undefined, file: string, line: number, options: HttpRequestOptions = {}) {
-    return HttpRequestNode.create(url, method, file, line, options);
+    return brandNode(HttpRequestNode.create(url, method, file, line, options));
   }
 
   /**
    * Create DATABASE_QUERY node
    */
   static createDatabaseQuery(query: string | undefined, operation: string | undefined, file: string, line: number, options: DatabaseQueryOptions = {}) {
-    return DatabaseQueryNode.create(query, operation, file, line, options);
+    return brandNode(DatabaseQueryNode.create(query, operation, file, line, options));
+  }
+
+  /**
+   * Create IMPORT node
+   *
+   * ImportNode automatically detects importType from imported field:
+   * - imported === 'default' → importType: 'default'
+   * - imported === '*' → importType: 'namespace'
+   * - anything else → importType: 'named'
+   *
+   * @param name - Local binding name (how it's used in this file)
+   * @param file - Absolute file path
+   * @param line - Line number (for debugging, not part of ID)
+   * @param column - Column position (0 if unavailable)
+   * @param source - Source module (e.g., 'react', './utils')
+   * @param options - Optional fields
+   * @returns ImportNodeRecord
+   */
+  static createImport(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    source: string,
+    options: ImportOptions = {}
+  ) {
+    return brandNode(ImportNode.create(name, file, line, column, source, options));
+  }
+
+  /**
+   * Create CLASS node
+   */
+  static createClass(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ClassOptions = {}
+  ) {
+    return brandNode(ClassNode.create(name, file, line, column, options));
+  }
+
+  /**
+   * Create EXPORT node
+   */
+  static createExport(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExportOptions = {}
+  ) {
+    return brandNode(ExportNode.create(name, file, line, column, options));
+  }
+
+  /**
+   * Create EXTERNAL_MODULE node
+   *
+   * Represents external npm packages or Node.js built-in modules.
+   * Uses singleton pattern - same source always produces same ID.
+   *
+   * @param source - Module name (e.g., 'lodash', '@tanstack/react-query', 'node:fs')
+   */
+  static createExternalModule(source: string) {
+    return brandNode(ExternalModuleNode.create(source));
+  }
+
+  /**
+   * Create INTERFACE node
+   */
+  static createInterface(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: InterfaceOptions = {}
+  ) {
+    return brandNode(InterfaceNode.create(name, file, line, column, options));
+  }
+
+  /**
+   * Create TYPE node
+   */
+  static createType(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: TypeOptions = {}
+  ) {
+    return brandNode(TypeNode.create(name, file, line, column, options));
+  }
+
+  /**
+   * Create ENUM node
+   */
+  static createEnum(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: EnumOptions = {}
+  ) {
+    return brandNode(EnumNode.create(name, file, line, column, options));
+  }
+
+  /**
+   * Create DECORATOR node
+   */
+  static createDecorator(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    targetId: string,
+    targetType: DecoratorTargetType,
+    options: DecoratorOptions = {}
+  ) {
+    return brandNode(DecoratorNode.create(name, file, line, column, targetId, targetType, options));
+  }
+
+  /**
+   * Create EXPRESSION node
+   */
+  static createExpression(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExpressionOptions = {}
+  ) {
+    return brandNode(ExpressionNode.create(expressionType, file, line, column, options));
+  }
+
+  /**
+   * Generate EXPRESSION node ID without creating the full node
+   *
+   * Used by JSASTAnalyzer when creating assignment metadata.
+   * The full node is created later by GraphBuilder.
+   *
+   * @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 generateExpressionId(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number
+  ): string {
+    return ExpressionNode.generateId(expressionType, file, 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
+   */
+  static createExpressionFromMetadata(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ExpressionOptions & { id: string }
+  ) {
+    return brandNode(ExpressionNode.createFromMetadata(expressionType, file, line, column, options));
+  }
+
+  /**
+   * Create EXPRESSION node with argument context
+   *
+   * Used when EXPRESSION appears as a call argument and we need to track
+   * which call and argument position for data flow analysis.
+   *
+   * @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 createArgumentExpression(
+    expressionType: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ArgumentExpressionOptions
+  ) {
+    return brandNode(ArgumentExpressionNode.create(expressionType, file, line, column, options));
+  }
+
+  /**
+   * Create ISSUE node
+   *
+   * Issues represent detected problems in the codebase.
+   * Used by validation plugins to persist findings in the graph.
+   *
+   * @param category - Issue category (security, performance, style, smell)
+   * @param severity - error | warning | info
+   * @param message - Human-readable description
+   * @param plugin - Name of the plugin that detected this issue
+   * @param file - File path where issue was detected
+   * @param line - Line number
+   * @param column - Column number (optional)
+   * @param options - Optional context data
+   */
+  static createIssue(
+    category: string,
+    severity: IssueSeverity,
+    message: string,
+    plugin: string,
+    file: string,
+    line: number,
+    column: number = 0,
+    options: { context?: Record<string, unknown> } = {}
+  ) {
+    return brandNode(IssueNode.create(category, severity, message, plugin, file, line, column, options));
   }
 
   /**
@@ -251,12 +617,29 @@ export class NodeFactory {
       'VARIABLE_DECLARATION': VariableDeclarationNode,
       'CONSTANT': ConstantNode,
       'LITERAL': LiteralNode,
-      'EXTERNAL_STDIO': ExternalStdioNode,
+      'OBJECT_LITERAL': ObjectLiteralNode,
+      'ARRAY_LITERAL': ArrayLiteralNode,
+      'net:stdio': ExternalStdioNode,
+      'net:request': NetworkRequestNode,
       'EVENT_LISTENER': EventListenerNode,
       'HTTP_REQUEST': HttpRequestNode,
-      'DATABASE_QUERY': DatabaseQueryNode
+      'DATABASE_QUERY': DatabaseQueryNode,
+      'IMPORT': ImportNode,
+      'CLASS': ClassNode,
+      'EXPORT': ExportNode,
+      'EXTERNAL_MODULE': ExternalModuleNode,
+      'INTERFACE': InterfaceNode,
+      'TYPE': TypeNode,
+      'ENUM': EnumNode,
+      'DECORATOR': DecoratorNode,
+      'EXPRESSION': ExpressionNode
     };
 
+    // Handle issue:* types dynamically
+    if (IssueNode.isIssueType(node.type)) {
+      return IssueNode.validate(node as Parameters<typeof IssueNode.validate>[0]);
+    }
+
     const validator = validators[node.type];
     if (!validator) {
       return [`Unknown node type: ${node.type}`];

package/src/core/ScopeTracker.ts

@@ -0,0 +1,154 @@
+/**
+ * ScopeTracker - Track scope hierarchy during AST traversal
+ *
+ * Maintains the current scope path and provides counters for:
+ * - Counted scopes (if#0, try#1, etc.)
+ * - Item counters (CALL, LITERAL, etc.)
+ * - Sibling tracking (anonymous[0], anonymous[1], etc.)
+ *
+ * Used with SemanticId to generate stable identifiers.
+ */
+
+import type { ScopeContext } from './SemanticId.js';
+
+/**
+ * Entry in the scope stack
+ */
+export interface ScopeEntry {
+  name: string;
+  type: string;
+  counter?: number;
+}
+
+/**
+ * Result of entering a counted scope
+ */
+export interface CountedScopeResult {
+  name: string;
+  discriminator: number;
+}
+
+/**
+ * ScopeTracker - Manages scope hierarchy and counters during AST traversal
+ */
+export class ScopeTracker {
+  /** Source file path */
+  readonly file: string;
+
+  /** Current scope stack */
+  private scopeStack: ScopeEntry[] = [];
+
+  /** Counters for various purposes (scoped by scope path) */
+  private counters: Map<string, number> = new Map();
+
+  constructor(file: string) {
+    this.file = file;
+  }
+
+  // === Scope Management ===
+
+  /**
+   * Enter a named scope (function, class, etc.)
+   */
+  enterScope(name: string, type: string): void {
+    this.scopeStack.push({ name, type });
+  }
+
+  /**
+   * Enter a counted scope (if, try, for, etc.)
+   * Automatically assigns a discriminator.
+   */
+  enterCountedScope(type: string): CountedScopeResult {
+    const key = this.counterKey(type);
+    const n = this.counters.get(key) || 0;
+    this.counters.set(key, n + 1);
+
+    const name = `${type}#${n}`;
+    this.scopeStack.push({ name, type, counter: n });
+    return { name, discriminator: n };
+  }
+
+  /**
+   * Exit the current scope
+   */
+  exitScope(): void {
+    this.scopeStack.pop();
+  }
+
+  // === ID Generation ===
+
+  /**
+   * Get current scope context for semantic ID generation
+   */
+  getContext(): ScopeContext {
+    return {
+      file: this.file,
+      scopePath: this.scopeStack.map(s => s.name)
+    };
+  }
+
+  /**
+   * Get scope path as string (for display/debugging)
+   */
+  getScopePath(): string {
+    if (this.scopeStack.length === 0) return 'global';
+    return this.scopeStack.map(s => s.name).join('->');
+  }
+
+  /**
+   * Get the innermost enclosing scope of a specific type.
+   * Searches from innermost to outermost.
+   *
+   * @param scopeType - Type to search for ('CLASS', 'FUNCTION', etc.)
+   * @returns The scope entry name if found, undefined otherwise
+   */
+  getEnclosingScope(scopeType: string): string | undefined {
+    // Search from end (innermost) to start (outermost)
+    for (let i = this.scopeStack.length - 1; i >= 0; i--) {
+      if (this.scopeStack[i].type === scopeType) {
+        return this.scopeStack[i].name;
+      }
+    }
+    return undefined;
+  }
+
+  // === Counter Management ===
+
+  /**
+   * Get next counter for item type within current scope.
+   * Used for CALL, LITERAL, etc. that need #N discriminators.
+   */
+  getItemCounter(itemType: string): number {
+    const key = this.counterKey(itemType);
+    const n = this.counters.get(key) || 0;
+    this.counters.set(key, n + 1);
+    return n;
+  }
+
+  /**
+   * Get current count without incrementing.
+   * Used to check for collisions.
+   */
+  peekItemCounter(itemType: string): number {
+    return this.counters.get(this.counterKey(itemType)) || 0;
+  }
+
+  // === Sibling Tracking ===
+
+  /**
+   * Track siblings by name within current scope.
+   * Used for anonymous functions: anonymous[0], anonymous[1]
+   */
+  getSiblingIndex(name: string): number {
+    const key = `${this.getScopePath()}:sibling:${name}`;
+    const n = this.counters.get(key) || 0;
+    this.counters.set(key, n + 1);
+    return n;
+  }
+
+  // === Private ===
+
+  private counterKey(itemType: string): string {
+    return `${this.getScopePath()}:${itemType}`;
+  }
+}