@grafema/core 0.1.0-alpha.1

package/src/core/WorkerPool.ts

@@ -0,0 +1,180 @@
+/**
+ * WorkerPool - worker pool for parallel task execution
+ *
+ * Key property: HORIZONTAL SCALING
+ * More workers = faster processing (up to CPU/IO limit)
+ */
+
+import { EventEmitter } from 'events';
+import type { Task, QueueStats } from './PriorityQueue.js';
+
+/**
+ * Task handler function type
+ */
+export type TaskHandler = (task: Task) => Promise<unknown>;
+
+/**
+ * Handler registry
+ */
+export interface TaskHandlers {
+  [taskType: string]: TaskHandler;
+}
+
+/**
+ * Queue interface for WorkerPool
+ */
+export interface WorkerQueue {
+  isEmpty: boolean;
+  next(): Task | null;
+  complete(taskId: string, result: unknown): void;
+  fail(taskId: string, error: Error): void;
+  getStats(): QueueStats;
+}
+
+/**
+ * Worker pool statistics
+ */
+export interface WorkerPoolStats {
+  workerCount: number;
+  activeWorkers: number;
+  running: boolean;
+}
+
+// === EVENT PAYLOADS ===
+
+export interface WorkerTaskStartEvent {
+  workerId: number;
+  task: Task;
+}
+
+export interface WorkerTaskCompletedEvent {
+  workerId: number;
+  task: Task;
+  result: unknown;
+}
+
+export interface WorkerTaskFailedEvent {
+  workerId: number;
+  task: Task;
+  error: unknown;
+}
+
+export class WorkerPool extends EventEmitter {
+  private workerCount: number;
+  private handlers: TaskHandlers;
+  private activeWorkers: number;
+  private running: boolean;
+
+  constructor(workerCount: number = 10, handlers: TaskHandlers = {}) {
+    super();
+    this.workerCount = workerCount;
+    this.handlers = handlers;
+    this.activeWorkers = 0;
+    this.running = false;
+  }
+
+  /**
+   * Register handler for task type
+   */
+  registerHandler(taskType: string, handler: TaskHandler): void {
+    this.handlers[taskType] = handler;
+  }
+
+  /**
+   * Start queue processing
+   */
+  async processQueue(queue: WorkerQueue): Promise<void> {
+    this.running = true;
+    this.emit('pool:started', { workerCount: this.workerCount });
+
+    // Create workers
+    const workers: Promise<void>[] = [];
+    for (let i = 0; i < this.workerCount; i++) {
+      workers.push(this._worker(i, queue));
+    }
+
+    // Wait for all workers to complete
+    await Promise.all(workers);
+
+    this.running = false;
+    this.emit('pool:finished', queue.getStats());
+  }
+
+  /**
+   * Worker - picks task from queue and executes
+   */
+  private async _worker(workerId: number, queue: WorkerQueue): Promise<void> {
+    while (true) {
+      // If queue is empty AND no active workers - exit
+      if (queue.isEmpty && this.activeWorkers === 0) {
+        break;
+      }
+
+      // Get next task
+      const task = queue.next();
+
+      if (!task) {
+        // No ready tasks, wait a bit
+        await this._sleep(10);
+        continue;
+      }
+
+      this.activeWorkers++;
+      this.emit('worker:task:start', { workerId, task });
+      this.emit('worker:task:started', task); // For progress tracking
+
+      try {
+        // Execute task
+        const handler = task.type ? this.handlers[task.type] : undefined;
+        if (!handler) {
+          throw new Error(`No handler for task type: ${task.type}`);
+        }
+
+        task.start();
+        const result = await handler(task);
+
+        queue.complete(task.id, result);
+        this.emit('worker:task:completed', { workerId, task, result });
+      } catch (error) {
+        queue.fail(task.id, error as Error);
+        this.emit('worker:task:failed', { workerId, task, error });
+      } finally {
+        this.activeWorkers--;
+      }
+    }
+
+    this.emit('worker:stopped', { workerId });
+  }
+
+  /**
+   * Sleep helper
+   */
+  private _sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Stop pool (graceful shutdown)
+   */
+  async stop(): Promise<void> {
+    this.running = false;
+
+    // Wait for all active workers to complete current tasks
+    while (this.activeWorkers > 0) {
+      await this._sleep(100);
+    }
+
+    this.emit('pool:stopped');
+  }
+
+  /**
+   * Statistics
+   */
+  getStats(): WorkerPoolStats {
+    return {
+      workerCount: this.workerCount,
+      activeWorkers: this.activeWorkers,
+      running: this.running
+    };
+  }
+}

package/src/core/nodes/CallSiteNode.ts

@@ -0,0 +1,72 @@
+/**
+ * CallSiteNode - contract for CALL_SITE node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface CallSiteNodeRecord extends BaseNodeRecord {
+  type: 'CALL_SITE';
+  column: number;
+  parentScopeId?: string;
+  targetFunctionName: string;
+}
+
+interface CallSiteNodeOptions {
+  parentScopeId?: string;
+  counter?: number;
+}
+
+export class CallSiteNode {
+  static readonly TYPE = 'CALL_SITE' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['column', 'parentScopeId', 'targetFunctionName'] as const;
+
+  /**
+   * Create CALL_SITE node
+   */
+  static create(
+    targetName: string,
+    file: string,
+    line: number,
+    column: number,
+    options: CallSiteNodeOptions = {}
+  ): CallSiteNodeRecord {
+    if (!targetName) throw new Error('CallSiteNode.create: targetName is required');
+    if (!file) throw new Error('CallSiteNode.create: file is required');
+    if (line === undefined) throw new Error('CallSiteNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:CALL_SITE:${targetName}:${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: targetName,
+      file,
+      line,
+      column: column || 0,
+      parentScopeId: options.parentScopeId,
+      targetFunctionName: targetName
+    };
+  }
+
+  static validate(node: CallSiteNodeRecord): 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] === undefined || nodeRecord[field] === null) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+
+    return errors;
+  }
+}
+
+export type { CallSiteNodeRecord };

package/src/core/nodes/ClassNode.ts

@@ -0,0 +1,69 @@
+/**
+ * ClassNode - contract for CLASS node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ClassNodeRecord extends BaseNodeRecord {
+  type: 'CLASS';
+  column: number;
+  exported: boolean;
+  superClass?: string;
+  methods: string[];
+}
+
+interface ClassNodeOptions {
+  exported?: boolean;
+  superClass?: string;
+  methods?: string[];
+}
+
+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 create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ClassNodeOptions = {}
+  ): ClassNodeRecord {
+    if (!name) throw new Error('ClassNode.create: name is required');
+    if (!file) throw new Error('ClassNode.create: file is required');
+    if (!line) throw new Error('ClassNode.create: line is required');
+
+    return {
+      id: `${file}:CLASS:${name}:${line}`,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      exported: options.exported || false,
+      superClass: options.superClass,
+      methods: options.methods || []
+    };
+  }
+
+  static validate(node: ClassNodeRecord): 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 { ClassNodeRecord };

package/src/core/nodes/ConstantNode.ts

@@ -0,0 +1,63 @@
+/**
+ * ConstantNode - contract for CONSTANT node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface ConstantNodeRecord extends BaseNodeRecord {
+  type: 'CONSTANT';
+  column: number;
+  value?: unknown;
+  parentScopeId?: string;
+}
+
+interface ConstantNodeOptions {
+  value?: unknown;
+  parentScopeId?: string;
+  counter?: number;
+}
+
+export class ConstantNode {
+  static readonly TYPE = 'CONSTANT' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['column', 'value', 'parentScopeId'] as const;
+
+  static create(
+    name: string,
+    file: string,
+    line: number,
+    column: number,
+    options: ConstantNodeOptions = {}
+  ): ConstantNodeRecord {
+    if (!name) throw new Error('ConstantNode.create: name is required');
+    if (!file) throw new Error('ConstantNode.create: file is required');
+    if (line === undefined) throw new Error('ConstantNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:CONSTANT:${name}:${line}:${column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      file,
+      line,
+      column: column || 0,
+      value: options.value,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  static validate(node: ConstantNodeRecord): 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 { ConstantNodeRecord };

package/src/core/nodes/DatabaseQueryNode.ts

@@ -0,0 +1,60 @@
+/**
+ * DatabaseQueryNode - contract for DATABASE_QUERY node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface DatabaseQueryNodeRecord extends BaseNodeRecord {
+  type: 'DATABASE_QUERY';
+  query?: string;
+  operation: string;
+  parentScopeId?: string;
+}
+
+interface DatabaseQueryNodeOptions {
+  parentScopeId?: string;
+}
+
+export class DatabaseQueryNode {
+  static readonly TYPE = 'DATABASE_QUERY' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['query', 'operation', 'parentScopeId'] as const;
+
+  static create(
+    query: string | undefined,
+    operation: string | undefined,
+    file: string,
+    line: number,
+    options: DatabaseQueryNodeOptions = {}
+  ): DatabaseQueryNodeRecord {
+    if (!file) throw new Error('DatabaseQueryNode.create: file is required');
+    if (line === undefined) throw new Error('DatabaseQueryNode.create: line is required');
+
+    const name = query || `${operation || 'QUERY'}`;
+    const id = `${file}:DATABASE_QUERY:${name}:${line}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name,
+      query,
+      operation: operation || 'UNKNOWN',
+      file,
+      line,
+      parentScopeId: options.parentScopeId
+    };
+  }
+
+  static validate(node: DatabaseQueryNodeRecord): 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 { DatabaseQueryNodeRecord };

package/src/core/nodes/EntrypointNode.ts

@@ -0,0 +1,164 @@
+/**
+ * EntrypointNode - represents an executable entry point
+ *
+ * An ENTRYPOINT is any file that can be executed directly:
+ * - service: main app entrypoint (package.json main/bin)
+ * - cli: command-line tool
+ * - test: test file
+ * - script: dev/build script (package.json scripts)
+ * - hook: git/tool hook (.husky/*, hooks/*.mjs)
+ * - config: build config (*.config.js)
+ */
+
+import { createHash } from 'crypto';
+import type { BaseNodeRecord } from '@grafema/types';
+
+// Entrypoint types
+export const ENTRYPOINT_TYPES = {
+  SERVICE: 'service',     // Main app entrypoint
+  CLI: 'cli',             // Command-line tool
+  TEST: 'test',           // Test file
+  SCRIPT: 'script',       // Dev/build script
+  HOOK: 'hook',           // Git/tool hook
+  CONFIG: 'config'        // Build config file
+} as const;
+
+export type EntrypointType = typeof ENTRYPOINT_TYPES[keyof typeof ENTRYPOINT_TYPES];
+
+// What triggers execution
+export const ENTRYPOINT_TRIGGERS = {
+  RUNTIME: 'runtime',     // Production runtime
+  BUILD: 'build',         // Build process
+  DEV: 'dev',             // Development
+  CI: 'ci',               // CI/CD pipeline
+  MANUAL: 'manual'        // Manual execution
+} as const;
+
+export type EntrypointTrigger = typeof ENTRYPOINT_TRIGGERS[keyof typeof ENTRYPOINT_TRIGGERS];
+
+// How entrypoint was discovered
+export const ENTRYPOINT_SOURCES = {
+  PACKAGE_MAIN: 'package.json:main',
+  PACKAGE_BIN: 'package.json:bin',
+  PACKAGE_SCRIPT: 'package.json:scripts',
+  CONVENTION: 'convention',
+  CONFIG: 'config',
+  MANUAL: 'manual'
+} as const;
+
+export type EntrypointSource = typeof ENTRYPOINT_SOURCES[keyof typeof ENTRYPOINT_SOURCES];
+
+interface EntrypointNodeRecord extends BaseNodeRecord {
+  type: 'ENTRYPOINT';
+  entrypointType: EntrypointType;
+  trigger: EntrypointTrigger;
+  source: string;
+  serviceId: string | null;
+}
+
+interface EntrypointNodeOptions {
+  id?: string;
+  name?: string;
+  trigger?: EntrypointTrigger;
+  source?: string;
+  serviceId?: string;
+}
+
+export class EntrypointNode {
+  static readonly TYPE = 'ENTRYPOINT' as const;
+
+  static readonly REQUIRED = ['file', 'entrypointType'] as const;
+  static readonly OPTIONAL = ['trigger', 'source', 'serviceId', 'name'] as const;
+
+  static readonly TYPES = ENTRYPOINT_TYPES;
+  static readonly TRIGGERS = ENTRYPOINT_TRIGGERS;
+  static readonly SOURCES = ENTRYPOINT_SOURCES;
+
+  /**
+   * Create ENTRYPOINT node
+   */
+  static create(
+    file: string,
+    entrypointType: EntrypointType,
+    options: EntrypointNodeOptions = {}
+  ): EntrypointNodeRecord {
+    if (!file) throw new Error('EntrypointNode.create: file is required');
+    if (!entrypointType) throw new Error('EntrypointNode.create: entrypointType is required');
+
+    const id = options.id || this.generateId(file, entrypointType);
+
+    return {
+      id,
+      type: this.TYPE,
+      file,
+      line: 0,
+      name: options.name || this.extractName(file),
+      entrypointType,
+      trigger: options.trigger || this.inferTrigger(entrypointType),
+      source: options.source || 'unknown',
+      serviceId: options.serviceId || null
+    };
+  }
+
+  /**
+   * Generate stable ID for entrypoint
+   */
+  static generateId(file: string, type: string): string {
+    const hash = createHash('md5').update(file).digest('hex').substring(0, 8);
+    return `ENTRYPOINT:${type}:${hash}`;
+  }
+
+  /**
+   * Extract name from file path
+   */
+  static extractName(file: string): string {
+    const parts = file.split('/');
+    return parts[parts.length - 1];
+  }
+
+  /**
+   * Infer trigger from entrypoint type
+   */
+  static inferTrigger(entrypointType: EntrypointType): EntrypointTrigger {
+    switch (entrypointType) {
+      case this.TYPES.SERVICE:
+      case this.TYPES.CLI:
+        return this.TRIGGERS.RUNTIME;
+      case this.TYPES.TEST:
+        return this.TRIGGERS.CI;
+      case this.TYPES.CONFIG:
+        return this.TRIGGERS.BUILD;
+      case this.TYPES.SCRIPT:
+      case this.TYPES.HOOK:
+        return this.TRIGGERS.DEV;
+      default:
+        return this.TRIGGERS.MANUAL;
+    }
+  }
+
+  /**
+   * Validate ENTRYPOINT node
+   */
+  static validate(node: EntrypointNodeRecord): 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}`);
+      }
+    }
+
+    if (node.entrypointType && !Object.values(this.TYPES).includes(node.entrypointType)) {
+      errors.push(`Invalid entrypointType: ${node.entrypointType}`);
+    }
+
+    return errors;
+  }
+}
+
+export type { EntrypointNodeRecord };

package/src/core/nodes/EventListenerNode.ts

@@ -0,0 +1,64 @@
+/**
+ * EventListenerNode - contract for EVENT_LISTENER node
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+
+interface EventListenerNodeRecord extends BaseNodeRecord {
+  type: 'EVENT_LISTENER';
+  object?: string;
+  parentScopeId?: string;
+  callbackArg?: string;
+}
+
+interface EventListenerNodeOptions {
+  column?: number;
+  parentScopeId?: string;
+  callbackArg?: string;
+  counter?: number;
+}
+
+export class EventListenerNode {
+  static readonly TYPE = 'EVENT_LISTENER' as const;
+
+  static readonly REQUIRED = ['name', 'file', 'line'] as const;
+  static readonly OPTIONAL = ['object', 'column', 'parentScopeId', 'callbackArg'] as const;
+
+  static create(
+    eventName: string,
+    objectName: string | undefined,
+    file: string,
+    line: number,
+    options: EventListenerNodeOptions = {}
+  ): EventListenerNodeRecord {
+    if (!eventName) throw new Error('EventListenerNode.create: eventName is required');
+    if (!file) throw new Error('EventListenerNode.create: file is required');
+    if (line === undefined) throw new Error('EventListenerNode.create: line is required');
+
+    const counter = options.counter !== undefined ? `:${options.counter}` : '';
+    const id = `${file}:EVENT_LISTENER:${eventName}:${line}:${options.column || 0}${counter}`;
+
+    return {
+      id,
+      type: this.TYPE,
+      name: eventName,
+      object: objectName,
+      file,
+      line,
+      parentScopeId: options.parentScopeId,
+      callbackArg: options.callbackArg
+    };
+  }
+
+  static validate(node: EventListenerNodeRecord): 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 { EventListenerNodeRecord };