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

package/src/core/nodes/VariableDeclarationNode.ts

@@ -1,8 +1,16 @@
 /**
  * VariableDeclarationNode - contract for VARIABLE_DECLARATION 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}->VARIABLE->{name}
+ * Example: src/app.js->handler->VARIABLE->result
  */
 
 import type { BaseNodeRecord } from '@grafema/types';
+import { computeSemanticId, type ScopeContext, type Location } from '../SemanticId.js';
 
 interface VariableDeclarationNodeRecord extends BaseNodeRecord {
   type: 'VARIABLE_DECLARATION';
@@ -15,11 +23,18 @@ interface VariableDeclarationNodeOptions {
   counter?: number;
 }
 
+/**
+ * Options for createWithContext
+ */
+interface VariableContextOptions {
+  parentScopeId?: string;
+}
+
 export class VariableDeclarationNode {
   static readonly TYPE = 'VARIABLE_DECLARATION' as const;
 
-  static readonly REQUIRED = ['name', 'file', 'line'] as const;
-  static readonly OPTIONAL = ['column', 'parentScopeId'] as const;
+  static readonly REQUIRED = ['name', 'file', 'line', 'column'] as const;
+  static readonly OPTIONAL = ['parentScopeId'] as const;
 
   static create(
     name: string,
@@ -31,9 +46,10 @@ export class VariableDeclarationNode {
     if (!name) throw new Error('VariableDeclarationNode.create: name is required');
     if (!file) throw new Error('VariableDeclarationNode.create: file is required');
     if (line === undefined) throw new Error('VariableDeclarationNode.create: line is required');
+    if (column === undefined) throw new Error('VariableDeclarationNode.create: column is required');
 
     const counter = options.counter !== undefined ? `:${options.counter}` : '';
-    const id = `${file}:VARIABLE_DECLARATION:${name}:${line}:${column || 0}${counter}`;
+    const id = `${file}:VARIABLE_DECLARATION:${name}:${line}:${column}${counter}`;
 
     return {
       id,
@@ -41,7 +57,45 @@ export class VariableDeclarationNode {
       name,
       file,
       line,
-      column: column || 0,
+      column,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  /**
+   * Create VARIABLE_DECLARATION node with semantic ID (NEW API)
+   *
+   * Uses ScopeContext from ScopeTracker for stable identifiers.
+   * Variable names are unique within scope (handles shadowing naturally).
+   *
+   * @param name - Variable name
+   * @param context - Scope context from ScopeTracker.getContext()
+   * @param location - Source location { line, column }
+   * @param options - Optional variable properties
+   * @returns VariableDeclarationNodeRecord with semantic ID
+   */
+  static createWithContext(
+    name: string,
+    context: ScopeContext,
+    location: Partial<Location>,
+    options: VariableContextOptions = {}
+  ): VariableDeclarationNodeRecord {
+    // Validate required fields
+    if (!name) throw new Error('VariableDeclarationNode.createWithContext: name is required');
+    if (!context.file) throw new Error('VariableDeclarationNode.createWithContext: file is required');
+    if (location.line === undefined) throw new Error('VariableDeclarationNode.createWithContext: line is required');
+    if (location.column === undefined) throw new Error('VariableDeclarationNode.createWithContext: column is required');
+
+    // Compute semantic ID using 'VARIABLE' type for cleaner IDs
+    const id = computeSemanticId('VARIABLE', name, context);
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      file: context.file,
+      line: location.line,
+      column: location.column,
       parentScopeId: options.parentScopeId
     };
   }

package/src/core/nodes/index.ts

@@ -11,20 +11,37 @@ export { ClassNode, type ClassNodeRecord } from './ClassNode.js';
 export { MethodNode, type MethodNodeRecord, type MethodKind } from './MethodNode.js';
 export { ParameterNode, type ParameterNodeRecord } from './ParameterNode.js';
 export { ScopeNode, type ScopeNodeRecord } from './ScopeNode.js';
+export { BranchNode, type BranchNodeRecord } from './BranchNode.js';
+export { CaseNode, type CaseNodeRecord } from './CaseNode.js';
 
 // Call/reference nodes
 export { CallSiteNode, type CallSiteNodeRecord } from './CallSiteNode.js';
 export { MethodCallNode, type MethodCallNodeRecord } from './MethodCallNode.js';
+export { ConstructorCallNode, type ConstructorCallNodeRecord } from './ConstructorCallNode.js';
 export { VariableDeclarationNode, type VariableDeclarationNodeRecord } from './VariableDeclarationNode.js';
 export { ConstantNode, type ConstantNodeRecord } from './ConstantNode.js';
 export { LiteralNode, type LiteralNodeRecord } from './LiteralNode.js';
+export { ObjectLiteralNode, type ObjectLiteralNodeRecord, type ObjectLiteralNodeOptions } from './ObjectLiteralNode.js';
+export { ArrayLiteralNode, type ArrayLiteralNodeRecord, type ArrayLiteralNodeOptions } from './ArrayLiteralNode.js';
 
 // Import/Export nodes
-export { ImportNode, type ImportNodeRecord, type ImportKind } from './ImportNode.js';
+export { ImportNode, type ImportNodeRecord, type ImportBinding, type ImportType } from './ImportNode.js';
 export { ExportNode, type ExportNodeRecord, type ExportKind } from './ExportNode.js';
+export { ExternalModuleNode, type ExternalModuleNodeRecord } from './ExternalModuleNode.js';
+
+// TypeScript declaration nodes
+export { InterfaceNode, type InterfaceNodeRecord, type InterfacePropertyRecord } from './InterfaceNode.js';
+export { TypeNode, type TypeNodeRecord } from './TypeNode.js';
+export { EnumNode, type EnumNodeRecord, type EnumMemberRecord } from './EnumNode.js';
+export { DecoratorNode, type DecoratorNodeRecord, type DecoratorTargetType } from './DecoratorNode.js';
+
+// Expression nodes
+export { ExpressionNode, type ExpressionNodeRecord, type ExpressionNodeOptions } from './ExpressionNode.js';
+export { ArgumentExpressionNode, type ArgumentExpressionNodeRecord, type ArgumentExpressionNodeOptions } from './ArgumentExpressionNode.js';
 
 // External/IO nodes
 export { ExternalStdioNode, type ExternalStdioNodeRecord } from './ExternalStdioNode.js';
+export { NetworkRequestNode, type NetworkRequestNodeRecord } from './NetworkRequestNode.js';
 export { EventListenerNode, type EventListenerNodeRecord } from './EventListenerNode.js';
 export { HttpRequestNode, type HttpRequestNodeRecord } from './HttpRequestNode.js';
 export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQueryNode.js';
@@ -32,6 +49,9 @@ export { DatabaseQueryNode, type DatabaseQueryNodeRecord } from './DatabaseQuery
 // Guarantee nodes (contract-based)
 export { GuaranteeNode, type GuaranteeNodeRecord, type GuaranteePriority, type GuaranteeStatus, type GuaranteeType } from './GuaranteeNode.js';
 
+// Issue nodes (detected problems)
+export { IssueNode, type IssueNodeRecord, type IssueSeverity, type IssueType } from './IssueNode.js';
+
 // Node type constants and helpers
 export {
   NODE_TYPE,

package/src/data/builtins/BuiltinRegistry.ts

@@ -0,0 +1,124 @@
+/**
+ * BuiltinRegistry - Registry for Node.js builtin functions (REG-218)
+ *
+ * Provides lookup for Node.js builtin modules and functions.
+ * Used by NodejsBuiltinsResolver for lazy EXTERNAL_FUNCTION node creation.
+ *
+ * Usage:
+ *   const registry = new BuiltinRegistry();
+ *   if (registry.isBuiltinModule('fs')) {
+ *     const funcDef = registry.getFunction('fs', 'readFile');
+ *     if (funcDef) {
+ *       // Create EXTERNAL_FUNCTION node with metadata
+ *     }
+ *   }
+ */
+
+import type { BuiltinFunctionDef, BuiltinModuleDef } from './types.js';
+import { ALL_BUILTIN_MODULES } from './definitions.js';
+
+export class BuiltinRegistry {
+  /** Map of module name to module definition */
+  private modules: Map<string, BuiltinModuleDef>;
+
+  /** Map of "module:funcName" to function definition for fast lookup */
+  private functions: Map<string, BuiltinFunctionDef>;
+
+  constructor(modules: BuiltinModuleDef[] = ALL_BUILTIN_MODULES) {
+    this.modules = new Map();
+    this.functions = new Map();
+
+    for (const mod of modules) {
+      this.modules.set(mod.name, mod);
+
+      for (const func of mod.functions) {
+        const key = `${mod.name}:${func.name}`;
+        this.functions.set(key, func);
+      }
+    }
+  }
+
+  /**
+   * Check if module is a Node.js builtin module.
+   * Handles node: prefix automatically.
+   *
+   * @param moduleName - Module name (e.g., 'fs', 'node:fs', 'fs/promises')
+   * @returns true if module is a known builtin
+   */
+  isBuiltinModule(moduleName: string): boolean {
+    const normalized = this.normalizeModule(moduleName);
+    return this.modules.has(normalized);
+  }
+
+  /**
+   * Normalize module name by stripping node: prefix.
+   *
+   * @param moduleName - Module name (e.g., 'node:fs', 'fs')
+   * @returns Normalized module name (e.g., 'fs')
+   */
+  normalizeModule(moduleName: string): string {
+    if (moduleName.startsWith('node:')) {
+      return moduleName.slice(5); // Remove 'node:' prefix
+    }
+    return moduleName;
+  }
+
+  /**
+   * Get function definition by module and function name.
+   *
+   * @param module - Module name (e.g., 'fs', 'node:fs')
+   * @param funcName - Function name (e.g., 'readFile')
+   * @returns Function definition or null if not found
+   */
+  getFunction(module: string, funcName: string): BuiltinFunctionDef | null {
+    const normalizedModule = this.normalizeModule(module);
+    const key = `${normalizedModule}:${funcName}`;
+    return this.functions.get(key) || null;
+  }
+
+  /**
+   * Check if function is a known builtin function.
+   *
+   * @param module - Module name
+   * @param funcName - Function name
+   * @returns true if function is known
+   */
+  isKnownFunction(module: string, funcName: string): boolean {
+    return this.getFunction(module, funcName) !== null;
+  }
+
+  /**
+   * Get all functions for a module.
+   *
+   * @param module - Module name
+   * @returns Array of function definitions (empty if module not found)
+   */
+  getAllFunctions(module: string): BuiltinFunctionDef[] {
+    const normalizedModule = this.normalizeModule(module);
+    const mod = this.modules.get(normalizedModule);
+    return mod ? mod.functions : [];
+  }
+
+  /**
+   * List all supported builtin module names.
+   *
+   * @returns Array of module names
+   */
+  listModules(): string[] {
+    return Array.from(this.modules.keys());
+  }
+
+  /**
+   * Create node ID for EXTERNAL_FUNCTION node.
+   *
+   * Format: EXTERNAL_FUNCTION:{module}.{funcName}
+   *
+   * @param module - Module name (will be normalized)
+   * @param funcName - Function name
+   * @returns Node ID string
+   */
+  createNodeId(module: string, funcName: string): string {
+    const normalizedModule = this.normalizeModule(module);
+    return `EXTERNAL_FUNCTION:${normalizedModule}.${funcName}`;
+  }
+}

package/src/data/builtins/definitions.ts

@@ -0,0 +1,267 @@
+/**
+ * Node.js Builtin Definitions (REG-218)
+ *
+ * Tier 1 builtin module definitions:
+ * - fs (filesystem)
+ * - fs/promises (async filesystem)
+ * - path (path manipulation)
+ * - http/https (network)
+ * - crypto (cryptography)
+ * - child_process (process execution)
+ *
+ * Additional modules (Tier 2):
+ * - url, util, os, events, stream, buffer, worker_threads
+ */
+
+import type { BuiltinModuleDef } from './types.js';
+
+/**
+ * Tier 1: Core Node.js modules (most commonly used)
+ */
+export const TIER_1_MODULES: BuiltinModuleDef[] = [
+  // fs - Filesystem operations
+  {
+    name: 'fs',
+    functions: [
+      { name: 'readFile', module: 'fs', security: 'file-io', pure: false },
+      { name: 'readFileSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'writeFile', module: 'fs', security: 'file-io', pure: false },
+      { name: 'writeFileSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'appendFile', module: 'fs', security: 'file-io', pure: false },
+      { name: 'appendFileSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'readdir', module: 'fs', security: 'file-io', pure: false },
+      { name: 'readdirSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'mkdir', module: 'fs', security: 'file-io', pure: false },
+      { name: 'mkdirSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'rmdir', module: 'fs', security: 'file-io', pure: false },
+      { name: 'rmdirSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'rm', module: 'fs', security: 'file-io', pure: false },
+      { name: 'rmSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'unlink', module: 'fs', security: 'file-io', pure: false },
+      { name: 'unlinkSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'stat', module: 'fs', security: 'file-io', pure: false },
+      { name: 'statSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'lstat', module: 'fs', security: 'file-io', pure: false },
+      { name: 'lstatSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'access', module: 'fs', security: 'file-io', pure: false },
+      { name: 'accessSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'chmod', module: 'fs', security: 'file-io', pure: false },
+      { name: 'chmodSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'chown', module: 'fs', security: 'file-io', pure: false },
+      { name: 'chownSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'rename', module: 'fs', security: 'file-io', pure: false },
+      { name: 'renameSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'copyFile', module: 'fs', security: 'file-io', pure: false },
+      { name: 'copyFileSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'createReadStream', module: 'fs', security: 'file-io', pure: false },
+      { name: 'createWriteStream', module: 'fs', security: 'file-io', pure: false },
+      { name: 'watch', module: 'fs', security: 'file-io', pure: false },
+      { name: 'watchFile', module: 'fs', security: 'file-io', pure: false },
+      { name: 'existsSync', module: 'fs', security: 'file-io', pure: false },
+      { name: 'truncate', module: 'fs', security: 'file-io', pure: false },
+      { name: 'truncateSync', module: 'fs', security: 'file-io', pure: false },
+    ]
+  },
+
+  // fs/promises - Async filesystem operations
+  {
+    name: 'fs/promises',
+    functions: [
+      { name: 'readFile', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'writeFile', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'appendFile', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'readdir', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'mkdir', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'rmdir', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'rm', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'unlink', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'stat', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'lstat', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'access', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'chmod', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'chown', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'rename', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'copyFile', module: 'fs/promises', security: 'file-io', pure: false },
+      { name: 'truncate', module: 'fs/promises', security: 'file-io', pure: false },
+    ]
+  },
+
+  // path - Path manipulation (pure functions)
+  {
+    name: 'path',
+    functions: [
+      { name: 'join', module: 'path', pure: true },
+      { name: 'resolve', module: 'path', pure: true },
+      { name: 'normalize', module: 'path', pure: true },
+      { name: 'basename', module: 'path', pure: true },
+      { name: 'dirname', module: 'path', pure: true },
+      { name: 'extname', module: 'path', pure: true },
+      { name: 'parse', module: 'path', pure: true },
+      { name: 'format', module: 'path', pure: true },
+      { name: 'relative', module: 'path', pure: true },
+      { name: 'isAbsolute', module: 'path', pure: true },
+      { name: 'sep', module: 'path', pure: true },
+      { name: 'delimiter', module: 'path', pure: true },
+    ]
+  },
+
+  // http - HTTP server/client
+  {
+    name: 'http',
+    functions: [
+      { name: 'createServer', module: 'http', security: 'net', pure: false },
+      { name: 'request', module: 'http', security: 'net', pure: false },
+      { name: 'get', module: 'http', security: 'net', pure: false },
+    ]
+  },
+
+  // https - HTTPS server/client
+  {
+    name: 'https',
+    functions: [
+      { name: 'createServer', module: 'https', security: 'net', pure: false },
+      { name: 'request', module: 'https', security: 'net', pure: false },
+      { name: 'get', module: 'https', security: 'net', pure: false },
+    ]
+  },
+
+  // crypto - Cryptographic operations
+  {
+    name: 'crypto',
+    functions: [
+      { name: 'createHash', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'createHmac', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'createCipher', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'createDecipher', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'createCipheriv', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'createDecipheriv', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'randomBytes', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'randomFill', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'randomFillSync', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'randomUUID', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'pbkdf2', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'pbkdf2Sync', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'scrypt', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'scryptSync', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'generateKey', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'generateKeyPair', module: 'crypto', security: 'crypto', pure: false },
+      { name: 'generateKeyPairSync', module: 'crypto', security: 'crypto', pure: false },
+    ]
+  },
+
+  // child_process - Process execution (SECURITY SENSITIVE)
+  {
+    name: 'child_process',
+    functions: [
+      { name: 'exec', module: 'child_process', security: 'exec', pure: false },
+      { name: 'execSync', module: 'child_process', security: 'exec', pure: false },
+      { name: 'execFile', module: 'child_process', security: 'exec', pure: false },
+      { name: 'execFileSync', module: 'child_process', security: 'exec', pure: false },
+      { name: 'spawn', module: 'child_process', security: 'exec', pure: false },
+      { name: 'spawnSync', module: 'child_process', security: 'exec', pure: false },
+      { name: 'fork', module: 'child_process', security: 'exec', pure: false },
+    ]
+  },
+];
+
+/**
+ * Tier 2: Additional commonly used modules
+ */
+export const TIER_2_MODULES: BuiltinModuleDef[] = [
+  // url - URL parsing
+  {
+    name: 'url',
+    functions: [
+      { name: 'parse', module: 'url', pure: true },
+      { name: 'format', module: 'url', pure: true },
+      { name: 'resolve', module: 'url', pure: true },
+      { name: 'fileURLToPath', module: 'url', pure: true },
+      { name: 'pathToFileURL', module: 'url', pure: true },
+    ]
+  },
+
+  // util - Utilities
+  {
+    name: 'util',
+    functions: [
+      { name: 'promisify', module: 'util', pure: true },
+      { name: 'callbackify', module: 'util', pure: true },
+      { name: 'inspect', module: 'util', pure: true },
+      { name: 'format', module: 'util', pure: true },
+      { name: 'deprecate', module: 'util', pure: false },
+      { name: 'inherits', module: 'util', pure: false },
+    ]
+  },
+
+  // os - Operating system info
+  {
+    name: 'os',
+    functions: [
+      { name: 'platform', module: 'os', pure: true },
+      { name: 'arch', module: 'os', pure: true },
+      { name: 'cpus', module: 'os', pure: false },
+      { name: 'hostname', module: 'os', pure: false },
+      { name: 'homedir', module: 'os', pure: false },
+      { name: 'tmpdir', module: 'os', pure: false },
+      { name: 'type', module: 'os', pure: true },
+      { name: 'release', module: 'os', pure: true },
+      { name: 'totalmem', module: 'os', pure: false },
+      { name: 'freemem', module: 'os', pure: false },
+    ]
+  },
+
+  // events - Event emitter
+  {
+    name: 'events',
+    functions: [
+      { name: 'EventEmitter', module: 'events', pure: false },
+      { name: 'once', module: 'events', pure: false },
+      { name: 'on', module: 'events', pure: false },
+    ]
+  },
+
+  // stream - Streams
+  {
+    name: 'stream',
+    functions: [
+      { name: 'Readable', module: 'stream', pure: false },
+      { name: 'Writable', module: 'stream', pure: false },
+      { name: 'Duplex', module: 'stream', pure: false },
+      { name: 'Transform', module: 'stream', pure: false },
+      { name: 'pipeline', module: 'stream', pure: false },
+      { name: 'finished', module: 'stream', pure: false },
+    ]
+  },
+
+  // buffer - Buffer operations
+  {
+    name: 'buffer',
+    functions: [
+      { name: 'Buffer', module: 'buffer', pure: false },
+      { name: 'alloc', module: 'buffer', pure: true },
+      { name: 'allocUnsafe', module: 'buffer', pure: true },
+      { name: 'from', module: 'buffer', pure: true },
+      { name: 'concat', module: 'buffer', pure: true },
+      { name: 'isBuffer', module: 'buffer', pure: true },
+    ]
+  },
+
+  // worker_threads - Worker threads
+  {
+    name: 'worker_threads',
+    functions: [
+      { name: 'Worker', module: 'worker_threads', pure: false },
+      { name: 'isMainThread', module: 'worker_threads', pure: true },
+      { name: 'parentPort', module: 'worker_threads', pure: false },
+      { name: 'workerData', module: 'worker_threads', pure: false },
+    ]
+  },
+];
+
+/**
+ * All builtin modules combined
+ */
+export const ALL_BUILTIN_MODULES: BuiltinModuleDef[] = [
+  ...TIER_1_MODULES,
+  ...TIER_2_MODULES,
+];

package/src/data/builtins/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Node.js Builtins Registry (REG-218)
+ *
+ * Exports for builtin function registry.
+ */
+
+export { BuiltinRegistry } from './BuiltinRegistry.js';
+export type { BuiltinFunctionDef, BuiltinModuleDef, SecurityCategory } from './types.js';
+export { ALL_BUILTIN_MODULES, TIER_1_MODULES, TIER_2_MODULES } from './definitions.js';
+export { JS_GLOBAL_FUNCTIONS } from './jsGlobals.js';

package/src/data/builtins/jsGlobals.ts

@@ -0,0 +1,28 @@
+/**
+ * JavaScript Global Functions (REG-227)
+ *
+ * These are functions intrinsic to the JS runtime that don't need CALLS edges.
+ * They're available in all JS environments (browser, Node.js, etc.) and aren't
+ * "callable definitions" in the code sense.
+ *
+ * What is NOT included:
+ * - Constructors (Array, Object, Error) - handled as constructor calls
+ * - Objects with methods (Math, JSON) - method calls go through MethodCallResolver
+ * - Environment globals (window, document) - not functions, they're objects
+ *
+ * Used by:
+ * - ExternalCallResolver: skips these when resolving external calls
+ * - CallResolverValidator: recognizes these as resolved (no violation)
+ */
+export const JS_GLOBAL_FUNCTIONS = new Set([
+  // Global functions (truly called as standalone functions)
+  'parseInt', 'parseFloat', 'isNaN', 'isFinite', 'eval',
+  'encodeURI', 'decodeURI', 'encodeURIComponent', 'decodeURIComponent',
+
+  // Timers (global functions in browser & Node.js)
+  'setTimeout', 'setInterval', 'setImmediate',
+  'clearTimeout', 'clearInterval', 'clearImmediate',
+
+  // CommonJS (special case - global in CJS environments)
+  'require'
+]);

package/src/data/builtins/types.ts

@@ -0,0 +1,36 @@
+/**
+ * BuiltinRegistry Types (REG-218)
+ *
+ * Type definitions for Node.js builtin function registry.
+ * Used for lazy EXTERNAL_FUNCTION node creation.
+ */
+
+/**
+ * Security category for builtin functions.
+ * Used for security analysis and auditing.
+ */
+export type SecurityCategory = 'file-io' | 'exec' | 'net' | 'crypto';
+
+/**
+ * Definition of a single builtin function.
+ */
+export interface BuiltinFunctionDef {
+  /** Function name (e.g., 'readFile') */
+  name: string;
+  /** Module name (e.g., 'fs', 'path', 'fs/promises') */
+  module: string;
+  /** Security category (for dangerous functions) */
+  security?: SecurityCategory;
+  /** Whether function is pure (no side effects) */
+  pure?: boolean;
+}
+
+/**
+ * Definition of a builtin module with its functions.
+ */
+export interface BuiltinModuleDef {
+  /** Module name (e.g., 'fs', 'path') */
+  name: string;
+  /** List of functions in this module */
+  functions: BuiltinFunctionDef[];
+}