@calmo/task-runner 4.1.0 → 4.2.0

package/src/TaskGraphValidator.ts

@@ -1,7 +1,7 @@
 import { ITaskGraphValidator } from "./contracts/ITaskGraphValidator.js";
 import { ValidationResult } from "./contracts/ValidationResult.js";
 import { ValidationError } from "./contracts/ValidationError.js";
-import { TaskGraph } from "./TaskGraph.js";
+import { TaskGraph, Task } from "./TaskGraph.js";
 import {
   ERROR_CYCLE,
   ERROR_DUPLICATE_TASK,
@@ -22,11 +22,11 @@ export class TaskGraphValidator implements ITaskGraphValidator {
   validate(taskGraph: TaskGraph): ValidationResult {
     const errors: ValidationError[] = [];
 
-    // 1. Check for duplicate tasks
-    const taskIds = this.checkDuplicateTasks(taskGraph, errors);
+    // 1. Build Map and Check Duplicates (Single Pass)
+    const taskMap = this.buildTaskMapAndCheckDuplicates(taskGraph, errors);
 
     // 2. Check for missing dependencies
-    this.checkMissingDependencies(taskGraph, taskIds, errors);
+    this.checkMissingDependencies(taskGraph, taskMap, errors);
 
     // 3. Check for cycles
     // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
@@ -35,7 +35,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     );
 
     if (!hasMissingDependencies) {
-      this.checkCycles(taskGraph, errors);
+      this.checkCycles(taskGraph, taskMap, errors);
     }
 
     return {
@@ -54,33 +54,33 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     return `Task graph validation failed: ${errorDetails.join("; ")}`;
   }
 
-  private checkDuplicateTasks(
+  private buildTaskMapAndCheckDuplicates(
     taskGraph: TaskGraph,
     errors: ValidationError[]
-  ): Set<string> {
-    const taskIds = new Set<string>();
+  ): Map<string, Task> {
+    const taskMap = new Map<string, Task>();
     for (const task of taskGraph.tasks) {
-      if (taskIds.has(task.id)) {
+      if (taskMap.has(task.id)) {
         errors.push({
           type: ERROR_DUPLICATE_TASK,
           message: `Duplicate task detected with ID: ${task.id}`,
           details: { taskId: task.id },
         });
       } else {
-        taskIds.add(task.id);
+        taskMap.set(task.id, task);
       }
     }
-    return taskIds;
+    return taskMap;
   }
 
   private checkMissingDependencies(
     taskGraph: TaskGraph,
-    taskIds: Set<string>,
+    taskMap: Map<string, Task>,
     errors: ValidationError[]
   ): void {
     for (const task of taskGraph.tasks) {
       for (const dependenceId of task.dependencies) {
-        if (!taskIds.has(dependenceId)) {
+        if (!taskMap.has(dependenceId)) {
           errors.push({
             type: ERROR_MISSING_DEPENDENCY,
             message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
@@ -91,13 +91,11 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     }
   }
 
-  private checkCycles(taskGraph: TaskGraph, errors: ValidationError[]): void {
-    // Build adjacency list
-    const adjacencyList = new Map<string, string[]>();
-    for (const task of taskGraph.tasks) {
-      adjacencyList.set(task.id, task.dependencies);
-    }
-
+  private checkCycles(
+    taskGraph: TaskGraph,
+    taskMap: Map<string, Task>,
+    errors: ValidationError[]
+  ): void {
     const visited = new Set<string>();
     const recursionStack = new Set<string>();
 
@@ -108,7 +106,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
 
       const path: string[] = [];
       if (
-        this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
+        this.detectCycle(task.id, path, visited, recursionStack, taskMap)
       ) {
         // Extract the actual cycle from the path
         // The path might look like A -> B -> C -> B (if we started at A and found cycle B-C-B)
@@ -132,7 +130,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     path: string[],
     visited: Set<string>,
     recursionStack: Set<string>,
-    adjacencyList: Map<string, string[]>
+    taskMap: Map<string, Task>
   ): boolean {
     // Use an explicit stack to avoid maximum call stack size exceeded errors
     const stack: { taskId: string; index: number; dependencies: string[] }[] =
@@ -145,7 +143,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     stack.push({
       taskId: startTaskId,
       index: 0,
-      dependencies: adjacencyList.get(startTaskId)!,
+      dependencies: taskMap.get(startTaskId)!.dependencies,
     });
 
     while (stack.length > 0) {
@@ -170,7 +168,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
           stack.push({
             taskId: dependenceId,
             index: 0,
-            dependencies: adjacencyList.get(dependenceId)!,
+            dependencies: taskMap.get(dependenceId)!.dependencies,
           });
         }
       } else {

package/src/TaskRunner.ts

@@ -14,11 +14,10 @@ import { TaskGraphValidationError } from "./TaskGraphValidationError.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 import { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 import { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrategy.js";
+import { Plugin } from "./contracts/Plugin.js";
+import { PluginManager } from "./PluginManager.js";
 import { DryRunExecutionStrategy } from "./strategies/DryRunExecutionStrategy.js";
 
-// Re-export types for backward compatibility
-export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
-
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -30,10 +29,14 @@ export class TaskRunner<TContext> {
   private executionStrategy: IExecutionStrategy<TContext> =
     new RetryingExecutionStrategy(new StandardExecutionStrategy());
 
+  private pluginManager: PluginManager<TContext>;
+
   /**
    * @param context The shared context object to be passed to each task.
    */
-  constructor(private context: TContext) {}
+  constructor(private context: TContext) {
+    this.pluginManager = new PluginManager({ events: this.eventBus });
+  }
 
   /**
    * Subscribe to an event.
@@ -56,17 +59,25 @@ export class TaskRunner<TContext> {
     event: K,
     callback: RunnerEventListener<TContext, K>
   ): void {
-    /* v8 ignore next 1 */
     this.eventBus.off(event, callback);
   }
 
+  /**
+   * Registers a plugin.
+   * @param plugin The plugin to register.
+   * @returns The TaskRunner instance for chaining.
+   */
+  public use(plugin: Plugin<TContext>): this {
+    this.pluginManager.use(plugin);
+    return this;
+  }
+
   /**
    * Sets the execution strategy to be used.
    * @param strategy The execution strategy.
    * @returns The TaskRunner instance for chaining.
    */
   public setExecutionStrategy(strategy: IExecutionStrategy<TContext>): this {
-    /* v8 ignore next 2 */
     this.executionStrategy = strategy;
     return this;
   }
@@ -77,14 +88,15 @@ export class TaskRunner<TContext> {
    * @returns A string containing the Mermaid graph definition.
    */
   public static getMermaidGraph<T>(steps: TaskStep<T>[]): string {
-    const graphLines = ["graph TD"];
+    const graphLines = new Set<string>(["graph TD"]);
     const idMap = new Map<string, string>();
     const usedIds = new Set<string>();
     const baseIdCounters = new Map<string, number>();
 
     const getUniqueId = (name: string) => {
-      if (idMap.has(name)) {
-        return idMap.get(name)!;
+      const existingId = idMap.get(name);
+      if (existingId !== undefined) {
+        return existingId;
       }
 
       const sanitized = this.sanitizeMermaidId(name);
@@ -112,17 +124,15 @@ export class TaskRunner<TContext> {
       return uniqueId;
     };
 
-    // Pre-calculate IDs for all steps to ensure stable generation order
-    // We sort steps by name to ensure deterministic ID generation regardless of input order if names clash
-    // But input order is usually significant in graph definition, so we'll stick to input order.
-    // However, we must process all step NAMES first.
-    for (const step of steps) {
-      getUniqueId(step.name);
-    }
-
+    // We process nodes in input order to ensure deterministic ID generation
+    // (getUniqueId is called for each unique step name in order, populating the cache).
+    const processedNamesForNodes = new Set<string>();
     for (const step of steps) {
-      const stepId = getUniqueId(step.name);
-      graphLines.push(`  ${stepId}[${JSON.stringify(step.name)}]`);
+      if (!processedNamesForNodes.has(step.name)) {
+        const stepId = getUniqueId(step.name);
+        graphLines.add(`  ${stepId}[${JSON.stringify(step.name)}]`);
+        processedNamesForNodes.add(step.name);
+      }
     }
 
     for (const step of steps) {
@@ -130,12 +140,12 @@ export class TaskRunner<TContext> {
         const stepId = getUniqueId(step.name);
         for (const dep of step.dependencies) {
           const depId = getUniqueId(dep);
-          graphLines.push(`  ${depId} --> ${stepId}`);
+          graphLines.add(`  ${depId} --> ${stepId}`);
         }
       }
     }
 
-    return [...new Set(graphLines)].join("\n");
+    return [...graphLines].join("\n");
   }
 
   /**
@@ -159,6 +169,9 @@ export class TaskRunner<TContext> {
     steps: TaskStep<TContext>[],
     config?: TaskRunnerExecutionConfig
   ): Promise<Map<string, TaskResult>> {
+    // Initialize plugins
+    await this.pluginManager.initialize();
+
     // Validate the task graph before execution
     const taskGraph: TaskGraph = {
       tasks: steps.map((step) => ({
@@ -197,9 +210,9 @@ export class TaskRunner<TContext> {
         config.timeout,
         config.signal
       );
-    } else {
-      return executor.execute(steps, config?.signal);
     }
+
+    return executor.execute(steps, config?.signal);
   }
 
   /**

package/src/TaskStateManager.ts

@@ -39,10 +39,12 @@ export class TaskStateManager<TContext> {
         this.readyQueue.push(step);
       } else {
         for (const dep of deps) {
-          if (!this.dependencyGraph.has(dep)) {
-            this.dependencyGraph.set(dep, []);
+          let dependents = this.dependencyGraph.get(dep);
+          if (dependents === undefined) {
+            dependents = [];
+            this.dependencyGraph.set(dep, dependents);
           }
-          this.dependencyGraph.get(dep)!.push(step);
+          dependents.push(step);
         }
       }
     }
@@ -188,11 +190,13 @@ export class TaskStateManager<TContext> {
    */
   private cascadeFailure(failedStepName: string): void {
     const queue = [failedStepName];
+    // Optimization: Use index pointer instead of shift() to avoid O(N) array re-indexing
+    let head = 0;
     // Use a set to track visited nodes in this cascade pass to avoid redundant processing,
     // although checking results.has() in internalMarkSkipped also prevents it.
 
-    while (queue.length > 0) {
-      const currentName = queue.shift()!;
+    while (head < queue.length) {
+      const currentName = queue[head++];
       const dependents = this.dependencyGraph.get(currentName);
 
       if (!dependents) continue;

package/src/WorkflowExecutor.ts

@@ -63,8 +63,22 @@ export class WorkflowExecutor<TContext> {
     }
 
     try {
+      // Create a signal mechanism to wait for any task completion
+      let signalResolver!: () => void;
+      let signalPromise = new Promise<void>((resolve) => {
+        signalResolver = resolve;
+      });
+
+      const signalWork = () => {
+        signalResolver();
+        // Reset the promise for the next wait
+        signalPromise = new Promise<void>((resolve) => {
+          signalResolver = resolve;
+        });
+      };
+
       // Initial pass
-      this.processLoop(executingPromises, signal);
+      this.processLoop(executingPromises, signalWork, signal);
 
       while (
         this.stateManager.hasPendingTasks() ||
@@ -78,16 +92,13 @@ export class WorkflowExecutor<TContext> {
           break;
         } else {
           // Wait for the next task to finish
-          await Promise.race(executingPromises);
+          await signalPromise;
         }
 
         if (signal?.aborted) {
           this.stateManager.cancelAllPending(
             ExecutionConstants.WORKFLOW_CANCELLED
           );
-        } else {
-          // After a task finishes, check for new work
-          this.processLoop(executingPromises, signal);
         }
       }
 
@@ -109,6 +120,7 @@ export class WorkflowExecutor<TContext> {
    */
   private processLoop(
     executingPromises: Set<Promise<void>>,
+    signalWork: () => void,
     signal?: AbortSignal
   ): void {
     const newlyReady = this.stateManager.processDependencies();
@@ -129,12 +141,13 @@ export class WorkflowExecutor<TContext> {
 
       const step = this.readyQueue.pop()!;
 
-      const taskPromise = this.executeTaskStep(step, signal)
-        .finally(() => {
-          executingPromises.delete(taskPromise);
-          // When a task finishes, we try to run more
-          this.processLoop(executingPromises, signal);
-        });
+      const taskPromise = this.executeTaskStep(step, signal).finally(() => {
+        executingPromises.delete(taskPromise);
+        // When a task finishes, we try to run more
+        this.processLoop(executingPromises, signalWork, signal);
+        // Signal that a task has completed
+        signalWork();
+      });
 
       executingPromises.add(taskPromise);
     }

package/src/contracts/Plugin.ts

@@ -0,0 +1,32 @@
+import { EventBus } from "../EventBus.js";
+
+/**
+ * Context provided to a plugin during installation.
+ * exposes capabilities to hook into the runner lifecycle and context.
+ */
+export interface PluginContext<TContext> {
+  /**
+   * The event bus instance to subscribe to runner events.
+   */
+  events: EventBus<TContext>;
+}
+
+/**
+ * Interface that all plugins must implement.
+ */
+export interface Plugin<TContext> {
+  /**
+   * Unique name of the plugin.
+   */
+  name: string;
+  /**
+   * Semantic version of the plugin.
+   */
+  version: string;
+  /**
+   * Called when the plugin is installed into the runner.
+   * This is where the plugin should subscribe to events or perform setup.
+   * @param context The plugin context exposing runner capabilities.
+   */
+  install(context: PluginContext<TContext>): void | Promise<void>;
+}