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

package/src/core/nodes/ImportNode.ts

@@ -4,20 +4,23 @@
 
 import type { BaseNodeRecord } from '@grafema/types';
 
-type ImportKind = 'value' | 'type' | 'typeof';
+type ImportBinding = 'value' | 'type' | 'typeof';
+type ImportType = 'default' | 'named' | 'namespace';
 
 interface ImportNodeRecord extends BaseNodeRecord {
   type: 'IMPORT';
   column: number;
   source: string;
-  importKind: ImportKind;
+  importType: ImportType;      // NEW: HOW it's imported (syntax)
+  importBinding: ImportBinding; // RENAMED: WHAT is imported (semantics)
   imported: string;
   local: string;
 }
 
 interface ImportNodeOptions {
-  importKind?: ImportKind;
-  imported?: string;
+  importType?: ImportType;      // Optional - will be auto-detected if not provided
+  importBinding?: ImportBinding;
+  imported?: string;            // Used for auto-detection if importType not provided
   local?: string;
 }
 
@@ -25,8 +28,19 @@ export class ImportNode {
   static readonly TYPE = 'IMPORT' as const;
 
   static readonly REQUIRED = ['name', 'file', 'line', 'source'] as const;
-  static readonly OPTIONAL = ['column', 'importKind', 'imported', 'local'] as const;
+  static readonly OPTIONAL = ['column', 'importType', 'importBinding', 'imported', 'local'] as const;
 
+  /**
+   * Create IMPORT node
+   *
+   * @param name - The local binding name (what the import is called in this module)
+   * @param file - Absolute file path
+   * @param line - Line number (for debugging only, not part of ID)
+   * @param column - Column position (pass 0 if unavailable - JSASTAnalyzer limitation)
+   * @param source - Module source (e.g., 'react', './utils')
+   * @param options - Optional fields
+   * @returns ImportNodeRecord
+   */
   static create(
     name: string,
     file: string,
@@ -37,18 +51,26 @@ export class ImportNode {
   ): ImportNodeRecord {
     if (!name) throw new Error('ImportNode.create: name is required');
     if (!file) throw new Error('ImportNode.create: file is required');
-    if (!line) throw new Error('ImportNode.create: line is required');
+    if (line === undefined) throw new Error('ImportNode.create: line is required');
     if (!source) throw new Error('ImportNode.create: source is required');
 
+    // Auto-detect importType from imported field if not explicitly provided
+    let importType = options.importType;
+    if (!importType && options.imported) {
+      importType = options.imported === 'default' ? 'default' :
+                   options.imported === '*' ? 'namespace' : 'named';
+    }
+
     return {
-      id: `${file}:IMPORT:${name}:${line}`,
+      id: `${file}:IMPORT:${source}:${name}`,  // SEMANTIC ID: no line number
       type: this.TYPE,
       name,
       file,
-      line,
+      line,      // Stored as field, not in ID
       column: column || 0,
       source,
-      importKind: options.importKind || 'value',
+      importType: importType || 'named',           // NEW field with auto-detection
+      importBinding: options.importBinding || 'value',  // RENAMED field
       imported: options.imported || name,
       local: options.local || name
     };
@@ -72,4 +94,4 @@ export class ImportNode {
   }
 }
 
-export type { ImportNodeRecord, ImportKind };
+export type { ImportNodeRecord, ImportBinding, ImportType };

package/src/core/nodes/InterfaceNode.ts

@@ -0,0 +1,91 @@
+/**
+ * InterfaceNode - contract for INTERFACE node
+ *
+ * Represents TypeScript interface declarations.
+ *
+ * ID format: {file}:INTERFACE:{name}:{line}
+ * Example: /src/types.ts:INTERFACE:IUser:5
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface InterfacePropertyRecord {
+  name: string;
+  type?: string;
+  optional?: boolean;
+  readonly?: boolean;
+}
+
+interface InterfaceNodeRecord extends BaseNodeRecord {
+  type: 'INTERFACE';
+  column: number;
+  extends: string[];
+  properties: InterfacePropertyRecord[];
+  isExternal?: boolean;
+}
+
+interface InterfaceNodeOptions {
+  extends?: string[];
+  properties?: InterfacePropertyRecord[];
+  isExternal?: boolean;
+}
+
+export class InterfaceNode {
+  static readonly TYPE = 'INTERFACE' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['column', 'extends', 'properties', 'isExternal'] as const;
+
+  /**
+   * Create INTERFACE node
+   *
+   * @param name - Interface name
+   * @param file - File path
+   * @param line - Line number
+   * @param column - Column position
+   * @param options - Optional interface properties
+   * @returns InterfaceNodeRecord
+   */
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: InterfaceNodeOptions = {}
+  ): InterfaceNodeRecord {
+    if (!name) throw new Error('InterfaceNode.create: name is required');
+    if (!file) throw new Error('InterfaceNode.create: file is required');
+    if (!line) throw new Error('InterfaceNode.create: line is required');
+
+    return {
+      id: `${file}:INTERFACE:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      extends: options.extends || [],
+      properties: options.properties || [],
+      ...(options.isExternal !== undefined && { isExternal: options.isExternal })
+    };
+  }
+
+  static validate(node: InterfaceNodeRecord): 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 { InterfaceNodeRecord, InterfacePropertyRecord };

package/src/core/nodes/IssueNode.ts

@@ -0,0 +1,177 @@
+/**
+ * IssueNode - contract for issue:* nodes
+ *
+ * Types: issue:security, issue:performance, issue:style, issue:smell
+ * ID format: issue:<category>#<hash>
+ *
+ * Issues represent detected problems in the codebase.
+ * They connect to affected code via AFFECTS edges.
+ */
+
+import { createHash } from 'crypto';
+import type { BaseNodeRecord } from '@grafema/types';
+import { getNamespace } from './NodeKind.js';
+
+// Severity type
+export type IssueSeverity = 'error' | 'warning' | 'info';
+
+// Issue types
+export type IssueType = `issue:${string}`;
+
+export interface IssueNodeRecord extends BaseNodeRecord {
+  type: IssueType;
+  severity: IssueSeverity;
+  category: string;
+  message: string;
+  plugin: string;
+  targetNodeId?: string;
+  createdAt: number;
+  context?: Record<string, unknown>;
+}
+
+export interface IssueNodeOptions {
+  context?: Record<string, unknown>;
+}
+
+// Valid severity levels
+const VALID_SEVERITIES = ['error', 'warning', 'info'] as const;
+
+export class IssueNode {
+  static readonly REQUIRED = ['category', 'severity', 'message', 'plugin', 'file'] as const;
+  static readonly OPTIONAL = ['targetNodeId', 'context'] as const;
+
+  /**
+   * Generate deterministic issue ID
+   * Format: issue:<category>#<hash12>
+   *
+   * Hash is based on plugin + file + line + column + message
+   * This ensures same issue = same ID across analysis runs
+   */
+  static generateId(
+    category: string,
+    plugin: string,
+    file: string,
+    line: number,
+    column: number,
+    message: string
+  ): string {
+    const hashInput = `${plugin}|${file}|${line}|${column}|${message}`;
+    const hash = createHash('sha256').update(hashInput).digest('hex').substring(0, 12);
+    return `issue:${category}#${hash}`;
+  }
+
+  /**
+   * Create issue node
+   *
+   * @param category - Issue category (security, performance, style, smell, or custom)
+   * @param severity - error | warning | info
+   * @param message - Human-readable description
+   * @param plugin - Plugin name that detected this issue
+   * @param file - File where issue was detected
+   * @param line - Line number
+   * @param column - Column number (optional, defaults to 0)
+   * @param options - Optional fields (context)
+   */
+  static create(
+    category: string,
+    severity: IssueSeverity,
+    message: string,
+    plugin: string,
+    file: string,
+    line: number,
+    column: number = 0,
+    options: IssueNodeOptions = {}
+  ): IssueNodeRecord {
+    if (!category) throw new Error('IssueNode.create: category is required');
+    if (!severity) throw new Error('IssueNode.create: severity is required');
+    if (!VALID_SEVERITIES.includes(severity)) {
+      throw new Error(`IssueNode.create: invalid severity "${severity}". Valid: ${VALID_SEVERITIES.join(', ')}`);
+    }
+    if (!message) throw new Error('IssueNode.create: message is required');
+    if (!plugin) throw new Error('IssueNode.create: plugin is required');
+    if (!file) throw new Error('IssueNode.create: file is required');
+
+    const type = `issue:${category}` as IssueType;
+    const id = this.generateId(category, plugin, file, line, column, message);
+    const now = Date.now();
+
+    return {
+      id,
+      type,
+      name: message.substring(0, 100), // Truncate for display
+      file,
+      line,
+      column,
+      severity,
+      category,
+      message,
+      plugin,
+      createdAt: now,
+      context: options.context,
+    };
+  }
+
+  /**
+   * Validate issue node
+   * @returns array of error messages, empty if valid
+   */
+  static validate(node: IssueNodeRecord): string[] {
+    const errors: string[] = [];
+
+    if (!IssueNode.isIssueType(node.type)) {
+      errors.push(`Expected issue:* type, got ${node.type}`);
+    }
+
+    if (!node.category) {
+      errors.push('Missing required field: category');
+    }
+
+    if (!node.severity) {
+      errors.push('Missing required field: severity');
+    } else if (!VALID_SEVERITIES.includes(node.severity as IssueSeverity)) {
+      errors.push(`Invalid severity: ${node.severity}. Valid: ${VALID_SEVERITIES.join(', ')}`);
+    }
+
+    if (!node.message) {
+      errors.push('Missing required field: message');
+    }
+
+    if (!node.plugin) {
+      errors.push('Missing required field: plugin');
+    }
+
+    return errors;
+  }
+
+  /**
+   * Parse issue ID into components
+   * @param id - full ID (e.g., 'issue:security#a3f2b1c4d5e6')
+   * @returns { category, hash } or null if invalid
+   */
+  static parseId(id: string): { category: string; hash: string } | null {
+    if (!id) return null;
+
+    const match = id.match(/^issue:([^#]+)#(.+)$/);
+    if (!match) return null;
+
+    return {
+      category: match[1],
+      hash: match[2],
+    };
+  }
+
+  /**
+   * Check if type is an issue type
+   */
+  static isIssueType(type: string): boolean {
+    if (!type) return false;
+    return getNamespace(type) === 'issue';
+  }
+
+  /**
+   * Get all known issue categories
+   */
+  static getCategories(): string[] {
+    return ['security', 'performance', 'style', 'smell'];
+  }
+}

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,6 +27,15 @@ 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;
 
@@ -58,6 +75,53 @@ export class MethodCallNode {
     };
   }
 
+  /**
+   * 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 (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 ?? 0,
+      parentScopeId: options.parentScopeId,
+      args: options.args || []
+    };
+  }
+
   static validate(node: MethodCallNodeRecord): string[] {
     const errors: string[] = [];
 

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,6 +31,16 @@ 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;
 
@@ -57,6 +75,51 @@ export class MethodNode {
     };
   }
 
+  /**
+   * 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');
+
+    // 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,
+      className,
+      async: options.async || false,
+      generator: options.generator || false,
+      static: options.static || false,
+      kind: options.kind || 'method'
+    };
+  }
+
   static validate(node: MethodNodeRecord): string[] {
     const errors: string[] = [];
 

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 };