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

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[] = [];
 

package/src/core/nodes/HttpRequestNode.ts

@@ -6,13 +6,13 @@ import type { BaseNodeRecord } from '@grafema/types';
 
 interface HttpRequestNodeRecord extends BaseNodeRecord {
   type: 'HTTP_REQUEST';
+  column: number;
   url?: string;
   method: string;
   parentScopeId?: string;
 }
 
 interface HttpRequestNodeOptions {
-  column?: number;
   parentScopeId?: string;
   counter?: number;
 }
@@ -20,22 +20,24 @@ interface HttpRequestNodeOptions {
 export class HttpRequestNode {
   static readonly TYPE = 'HTTP_REQUEST' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['url', 'method', 'column', 'parentScopeId'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['url', 'method', 'parentScopeId'] as const;
 
   static create(
     url: string | undefined,
     method: string | undefined,
     file: string,
     line: number,
+    column: number,
     options: HttpRequestNodeOptions = {}
   ): HttpRequestNodeRecord {
     if (!file) throw new Error('HttpRequestNode.create: file is required');
     if (line === undefined) throw new Error('HttpRequestNode.create: line is required');
+    if (column === undefined) throw new Error('HttpRequestNode.create: column is required');
 
     const httpMethod = method || 'GET';
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
-    const id = `${file}:HTTP_REQUEST:${httpMethod}:${line}:${options.column || 0}${counter}`;
+    const id = `${file}:HTTP_REQUEST:${httpMethod}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -45,6 +47,7 @@ export class HttpRequestNode {
       method: httpMethod,
       file,
       line,
+      column,
       parentScopeId: options.parentScopeId
     };
   }

package/src/core/nodes/ImportNode.ts

@@ -4,29 +4,51 @@
 
 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;
+  isDynamic?: boolean;         // true for dynamic import() expressions
+  isResolvable?: boolean;      // true if path is a string literal (statically analyzable)
+  dynamicPath?: string;        // original expression for template/variable paths
+  sideEffect?: boolean;        // REG-273: true for side-effect-only imports
 }
 
 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;
+  isDynamic?: boolean;          // true for dynamic import() expressions
+  isResolvable?: boolean;       // true if path is a string literal (statically analyzable)
+  dynamicPath?: string;         // original expression for template/variable paths
+  sideEffect?: boolean;         // REG-273: true for side-effect-only imports
 }
 
 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 REQUIRED = ['name', 'file', 'line', 'column', 'source'] as const;
+  static readonly OPTIONAL = ['importType', 'importBinding', 'imported', 'local', 'isDynamic', 'isResolvable', 'dynamicPath', 'sideEffect'] 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,21 +59,48 @@ 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 (column === undefined) throw new Error('ImportNode.create: column is required');
     if (!source) throw new Error('ImportNode.create: source is required');
 
-    return {
-      id: `${file}:IMPORT:${name}:${line}`,
+    // 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';
+    }
+
+    const record: ImportNodeRecord = {
+      id: `${file}:IMPORT:${source}:${name}`,  // SEMANTIC ID: no line number
       type: this.TYPE,
       name,
       file,
-      line,
-      column: column || 0,
+      line,      // Stored as field, not in ID
+      column,
       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
     };
+
+    // Add dynamic import fields if provided
+    if (options.isDynamic !== undefined) {
+      record.isDynamic = options.isDynamic;
+    }
+    if (options.isResolvable !== undefined) {
+      record.isResolvable = options.isResolvable;
+    }
+    if (options.dynamicPath !== undefined) {
+      record.dynamicPath = options.dynamicPath;
+    }
+
+    // REG-273: Add sideEffect field if provided
+    if (options.sideEffect !== undefined) {
+      record.sideEffect = options.sideEffect;
+    }
+
+    return record;
   }
 
   static validate(node: ImportNodeRecord): string[] {
@@ -72,4 +121,4 @@ export class ImportNode {
   }
 }
 
-export type { ImportNodeRecord, ImportKind };
+export type { ImportNodeRecord, ImportBinding, ImportType };

package/src/core/nodes/InterfaceNode.ts

@@ -0,0 +1,92 @@
+/**
+ * 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', 'column'] as const;
+  static readonly OPTIONAL = ['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');
+    if (column === undefined) throw new Error('InterfaceNode.create: column is required');
+
+    return {
+      id: `${file}:INTERFACE:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column,
+      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/LiteralNode.ts

@@ -22,8 +22,8 @@ interface LiteralNodeOptions {
 export class LiteralNode {
   static readonly TYPE = 'LITERAL' as const;
 
-  static readonly REQUIRED = ['file', 'line'] as const;
-  static readonly OPTIONAL = ['value', 'valueType', 'column', 'parentCallId', 'argIndex'] as const;
+  static readonly REQUIRED = ['file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['value', 'valueType', 'parentCallId', 'argIndex'] as const;
 
   static create(
     value: unknown,
@@ -34,10 +34,11 @@ export class LiteralNode {
   ): LiteralNodeRecord {
     if (!file) throw new Error('LiteralNode.create: file is required');
     if (line === undefined) throw new Error('LiteralNode.create: line is required');
+    if (column === undefined) throw new Error('LiteralNode.create: column is required');
 
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
     const argIndex = options.argIndex !== undefined ? `arg${options.argIndex}` : 'value';
-    const id = `${file}:LITERAL:${argIndex}:${line}:${column || 0}${counter}`;
+    const id = `${file}:LITERAL:${argIndex}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -47,7 +48,7 @@ export class LiteralNode {
       valueType: typeof value,
       file,
       line,
-      column: column || 0,
+      column,
       parentCallId: options.parentCallId,
       argIndex: options.argIndex
     };