@calmo/task-runner 4.0.4 → 4.2.0

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,25 +88,64 @@ 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) => {
+      const existingId = idMap.get(name);
+      if (existingId !== undefined) {
+        return existingId;
+      }
 
-    const sanitize = (name: string) => this.sanitizeMermaidId(name);
+      const sanitized = this.sanitizeMermaidId(name);
+      let uniqueId = sanitized;
 
+      // First check if the base sanitized ID is available
+      if (!usedIds.has(uniqueId)) {
+        usedIds.add(uniqueId);
+        idMap.set(name, uniqueId);
+        return uniqueId;
+      }
+
+      // If not, use the counter for this base ID
+      let counter = baseIdCounters.get(sanitized) || 1;
+
+      while (usedIds.has(uniqueId)) {
+        uniqueId = `${sanitized}_${counter}`;
+        counter++;
+      }
+
+      baseIdCounters.set(sanitized, counter);
+
+      usedIds.add(uniqueId);
+      idMap.set(name, uniqueId);
+      return uniqueId;
+    };
+
+    // 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) {
-      graphLines.push(
-        `  ${sanitize(step.name)}[${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) {
       if (step.dependencies) {
+        const stepId = getUniqueId(step.name);
         for (const dep of step.dependencies) {
-          graphLines.push(`  ${sanitize(dep)} --> ${sanitize(step.name)}`);
+          const depId = getUniqueId(dep);
+          graphLines.add(`  ${depId} --> ${stepId}`);
         }
       }
     }
 
-    return [...new Set(graphLines)].join("\n");
+    return [...graphLines].join("\n");
   }
 
   /**
@@ -119,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) => ({
@@ -157,9 +210,9 @@ export class TaskRunner<TContext> {
         config.timeout,
         config.signal
       );
-    } else {
-      return executor.execute(steps, config?.signal);
     }
+
+    return executor.execute(steps, config?.signal);
   }
 
   /**
@@ -171,37 +224,16 @@ export class TaskRunner<TContext> {
     timeout: number,
     signal?: AbortSignal
   ): Promise<Map<string, TaskResult>> {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => {
-      controller.abort(new Error(`Workflow timed out after ${timeout}ms`));
-    }, timeout);
-
-    let effectiveSignal = controller.signal;
-    let onAbort: (() => void) | undefined;
-
-    // Handle combination of signals if user provided one
-    if (signal) {
-      if (signal.aborted) {
-        // If already aborted, use it directly (WorkflowExecutor handles early abort)
-        // We can cancel timeout immediately
-        clearTimeout(timeoutId);
-        effectiveSignal = signal;
-      } else {
-        // Listen to user signal to abort our controller
-        onAbort = () => {
-          controller.abort(signal.reason);
-        };
-        signal.addEventListener("abort", onAbort);
-      }
-    }
+    // Create a timeout signal that aborts after the specified time
+    const timeoutSignal = AbortSignal.timeout(timeout);
 
-    try {
-      return await executor.execute(steps, effectiveSignal);
-    } finally {
-      clearTimeout(timeoutId);
-      if (signal && onAbort) {
-        signal.removeEventListener("abort", onAbort);
-      }
-    }
+    // If there's a user-provided signal, combine them.
+    // Otherwise, use the timeout signal directly.
+    const effectiveSignal = signal
+      ? AbortSignal.any([signal, timeoutSignal])
+      : timeoutSignal;
+
+    return executor.execute(steps, effectiveSignal);
+    // No explicit clean up needed for AbortSignal.timeout as it is handled by the platform
   }
 }

package/src/TaskStateManager.ts

@@ -11,6 +11,11 @@ export class TaskStateManager<TContext> {
   private pendingSteps = new Set<TaskStep<TContext>>();
   private running = new Set<string>();
 
+  // Optimization structures
+  private dependencyGraph = new Map<string, TaskStep<TContext>[]>();
+  private dependencyCounts = new Map<string, number>();
+  private readyQueue: TaskStep<TContext>[] = [];
+
   constructor(private eventBus: EventBus<TContext>) {}
 
   /**
@@ -21,50 +26,41 @@ export class TaskStateManager<TContext> {
     this.pendingSteps = new Set(steps);
     this.results.clear();
     this.running.clear();
-  }
+    this.readyQueue = [];
 
-  /**
-   * Processes the pending steps to identify tasks that can be started or must be skipped.
-   * Emits `taskSkipped` for skipped tasks.
-   * @returns An array of tasks that are ready to run.
-   */
-  processDependencies(): TaskStep<TContext>[] {
-    const toRemove: TaskStep<TContext>[] = [];
-    const toRun: TaskStep<TContext>[] = [];
+    this.dependencyGraph.clear();
+    this.dependencyCounts.clear();
 
-    for (const step of this.pendingSteps) {
+    for (const step of steps) {
       const deps = step.dependencies ?? [];
-      let blocked = false;
-      let failedDep: string | undefined;
-
-      for (const dep of deps) {
-        const depResult = this.results.get(dep);
-        if (!depResult) {
-          // Dependency not finished yet
-          blocked = true;
-        } else if (depResult.status !== "success") {
-          failedDep = dep;
-          break;
+      this.dependencyCounts.set(step.name, deps.length);
+
+      if (deps.length === 0) {
+        this.readyQueue.push(step);
+      } else {
+        for (const dep of deps) {
+          let dependents = this.dependencyGraph.get(dep);
+          if (dependents === undefined) {
+            dependents = [];
+            this.dependencyGraph.set(dep, dependents);
+          }
+          dependents.push(step);
         }
       }
-
-      if (failedDep) {
-        const depResult = this.results.get(failedDep);
-        const depError = depResult?.error ? `: ${depResult.error}` : "";
-        const result: TaskResult = {
-          status: "skipped",
-          message: `Skipped because dependency '${failedDep}' failed${depError}`,
-        };
-        this.markSkipped(step, result);
-        toRemove.push(step);
-      } else if (!blocked) {
-        toRun.push(step);
-        toRemove.push(step);
-      }
     }
+  }
+
+  /**
+   * Processes the pending steps to identify tasks that can be started.
+   * Emits `taskSkipped` for skipped tasks (handled during cascade).
+   * @returns An array of tasks that are ready to run.
+   */
+  processDependencies(): TaskStep<TContext>[] {
+    const toRun = [...this.readyQueue];
+    this.readyQueue = [];
 
-    // Cleanup pending set
-    for (const step of toRemove) {
+    // Remove them from pendingSteps as they are now handed off to the executor
+    for (const step of toRun) {
       this.pendingSteps.delete(step);
     }
 
@@ -90,6 +86,39 @@ export class TaskStateManager<TContext> {
     this.running.delete(step.name);
     this.results.set(step.name, result);
     this.eventBus.emit("taskEnd", { step, result });
+
+    if (result.status === "success") {
+      this.handleSuccess(step.name);
+    } else {
+      this.cascadeFailure(step.name);
+    }
+  }
+
+  /**
+   * Marks a task as skipped and emits `taskSkipped`.
+   * @param step The task that was skipped.
+   * @param result The result object (status: skipped).
+   */
+  markSkipped(step: TaskStep<TContext>, result: TaskResult): void {
+    if (this.internalMarkSkipped(step, result)) {
+      this.cascadeFailure(step.name);
+    }
+  }
+
+  /**
+   * Internal method to mark skipped without triggering cascade (to be used inside cascade loop).
+   * Returns true if the task was actually marked skipped (was not already finished).
+   */
+  private internalMarkSkipped(step: TaskStep<TContext>, result: TaskResult): boolean {
+    if (this.results.has(step.name)) {
+      return false;
+    }
+
+    this.running.delete(step.name);
+    this.results.set(step.name, result);
+    this.pendingSteps.delete(step);
+    this.eventBus.emit("taskSkipped", { step, result });
+    return true;
   }
 
   /**
@@ -97,10 +126,10 @@ export class TaskStateManager<TContext> {
    * @param message The cancellation message.
    */
   cancelAllPending(message: string): void {
+    this.readyQueue = []; // Clear ready queue
+
     // Iterate over pendingSteps to cancel them
     for (const step of this.pendingSteps) {
-      // Also check running? No, running tasks are handled by AbortSignal in Executor.
-      // We only cancel what is pending and hasn't started.
       if (!this.results.has(step.name) && !this.running.has(step.name)) {
         const result: TaskResult = {
           status: "cancelled",
@@ -136,13 +165,56 @@ export class TaskStateManager<TContext> {
   }
 
   /**
-   * Marks a task as skipped and emits `taskSkipped`.
-   * @param step The task that was skipped.
-   * @param result The result object (status: skipped).
+   * Handles successful completion of a task by updating dependents.
    */
-  markSkipped(step: TaskStep<TContext>, result: TaskResult): void {
-    this.running.delete(step.name);
-    this.results.set(step.name, result);
-    this.eventBus.emit("taskSkipped", { step, result });
+  private handleSuccess(stepName: string): void {
+    const dependents = this.dependencyGraph.get(stepName);
+    if (!dependents) return;
+
+    for (const dependent of dependents) {
+      const currentCount = this.dependencyCounts.get(dependent.name)!;
+      const newCount = currentCount - 1;
+      this.dependencyCounts.set(dependent.name, newCount);
+
+      if (newCount === 0) {
+        // Task is ready. Ensure it's still pending.
+        if (this.pendingSteps.has(dependent)) {
+          this.readyQueue.push(dependent);
+        }
+      }
+    }
+  }
+
+  /**
+   * Cascades failure/skipping to dependents.
+   */
+  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 (head < queue.length) {
+      const currentName = queue[head++];
+      const dependents = this.dependencyGraph.get(currentName);
+
+      if (!dependents) continue;
+
+      // Get the result of the failed/skipped dependency to propagate error info if available
+      const currentResult = this.results.get(currentName);
+      const depError = currentResult?.error ? `: ${currentResult.error}` : "";
+
+      for (const dependent of dependents) {
+        const result: TaskResult = {
+          status: "skipped",
+          message: `Skipped because dependency '${currentName}' failed${depError}`,
+        };
+
+        if (this.internalMarkSkipped(dependent, result)) {
+          queue.push(dependent.name);
+        }
+      }
+    }
   }
 }

package/src/WorkflowExecutor.ts

@@ -4,13 +4,14 @@ import { EventBus } from "./EventBus.js";
 import { TaskStateManager } from "./TaskStateManager.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 import { ExecutionConstants } from "./ExecutionConstants.js";
+import { PriorityQueue } from "./utils/PriorityQueue.js";
 
 /**
  * Handles the execution of the workflow steps.
  * @template TContext The shape of the shared context object.
  */
 export class WorkflowExecutor<TContext> {
-  private readyQueue: TaskStep<TContext>[] = [];
+  private readyQueue = new PriorityQueue<TaskStep<TContext>>();
 
   /**
    * @param context The shared context object.
@@ -62,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() ||
@@ -77,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);
         }
       }
 
@@ -108,20 +120,18 @@ export class WorkflowExecutor<TContext> {
    */
   private processLoop(
     executingPromises: Set<Promise<void>>,
+    signalWork: () => void,
     signal?: AbortSignal
   ): void {
     const newlyReady = this.stateManager.processDependencies();
 
     // Add newly ready tasks to the queue
     for (const task of newlyReady) {
-      this.readyQueue.push(task);
+      this.readyQueue.push(task, task.priority ?? 0);
     }
 
-    // Sort by priority (descending) once after adding new tasks
-    this.readyQueue.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
-
     // Execute ready tasks while respecting concurrency limit
-    while (this.readyQueue.length > 0) {
+    while (!this.readyQueue.isEmpty()) {
       if (
         this.concurrency !== undefined &&
         executingPromises.size >= this.concurrency
@@ -129,14 +139,15 @@ export class WorkflowExecutor<TContext> {
         break;
       }
 
-      const step = this.readyQueue.shift()!;
+      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);
     }
@@ -194,16 +205,28 @@ export class WorkflowExecutor<TContext> {
 
     this.stateManager.markRunning(step);
 
+    const startTime = performance.now();
+    let result: TaskResult;
+
     try {
-      const result = await this.strategy.execute(step, this.context, signal);
-      this.stateManager.markCompleted(step, result);
+      result = await this.strategy.execute(step, this.context, signal);
     } catch (error) {
-      const result: TaskResult = {
+      result = {
         status: "failure",
         message: ExecutionConstants.EXECUTION_STRATEGY_FAILED,
         error: error instanceof Error ? error.message : String(error),
       };
-      this.stateManager.markCompleted(step, result);
     }
+
+    const endTime = performance.now();
+
+    // Always inject metrics to ensure accuracy
+    result.metrics = {
+      startTime,
+      endTime,
+      duration: endTime - startTime,
+    };
+
+    this.stateManager.markCompleted(step, result);
   }
 }

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

package/src/strategies/DryRunExecutionStrategy.ts

@@ -16,8 +16,7 @@ export class DryRunExecutionStrategy<
    * @returns A promise resolving to a success result.
    */
   async execute(
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    _step: TaskStep<TContext>,
+    step: TaskStep<TContext>,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _context: TContext,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -25,7 +24,7 @@ export class DryRunExecutionStrategy<
   ): Promise<TaskResult> {
     return Promise.resolve({
       status: "success",
-      message: "Dry run: simulated success",
+      message: "Dry run: simulated success " + step.name,
     });
   }
 }

package/src/utils/PriorityQueue.ts

@@ -0,0 +1,101 @@
+export class PriorityQueue<T> {
+  private heap: { item: T; priority: number; sequenceId: number }[] = [];
+  private sequenceCounter = 0;
+
+  push(item: T, priority: number): void {
+    const node = { item, priority, sequenceId: this.sequenceCounter++ };
+    this.heap.push(node);
+    this.bubbleUp();
+  }
+
+  pop(): T | undefined {
+    if (this.heap.length === 0) return undefined;
+    if (this.heap.length === 1) return this.heap.pop()!.item;
+
+    const top = this.heap[0];
+    this.heap[0] = this.heap.pop()!;
+    this.sinkDown();
+    return top.item;
+  }
+
+  peek(): T | undefined {
+    return this.heap[0]?.item;
+  }
+
+  size(): number {
+    return this.heap.length;
+  }
+
+  isEmpty(): boolean {
+    return this.heap.length === 0;
+  }
+
+  clear(): void {
+    this.heap = [];
+    this.sequenceCounter = 0;
+  }
+
+  private bubbleUp(): void {
+    let index = this.heap.length - 1;
+    const element = this.heap[index];
+
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      const parent = this.heap[parentIndex];
+
+      if (this.compare(element, parent) <= 0) break;
+
+      this.heap[index] = parent;
+      this.heap[parentIndex] = element;
+      index = parentIndex;
+    }
+  }
+
+  private sinkDown(): void {
+    let index = 0;
+    const length = this.heap.length;
+    const element = this.heap[0];
+
+    while (true) {
+      const leftChildIndex = 2 * index + 1;
+      const rightChildIndex = 2 * index + 2;
+      let swapIndex: number | null = null;
+
+      if (leftChildIndex < length) {
+        if (this.compare(this.heap[leftChildIndex], element) > 0) {
+          swapIndex = leftChildIndex;
+        }
+      }
+
+      if (rightChildIndex < length) {
+        const rightChild = this.heap[rightChildIndex];
+        const leftChild = this.heap[leftChildIndex];
+
+        if (
+          (swapIndex === null && this.compare(rightChild, element) > 0) ||
+          (swapIndex !== null && this.compare(rightChild, leftChild) > 0)
+        ) {
+          swapIndex = rightChildIndex;
+        }
+      }
+
+      if (swapIndex === null) break;
+
+      this.heap[index] = this.heap[swapIndex];
+      this.heap[swapIndex] = element;
+      index = swapIndex;
+    }
+  }
+
+  // Returns positive if a > b (a should come before b)
+  private compare(
+    a: { priority: number; sequenceId: number },
+    b: { priority: number; sequenceId: number }
+  ): number {
+    if (a.priority !== b.priority) {
+      return a.priority - b.priority;
+    }
+    // Lower sequenceId means earlier insertion, so it has higher priority
+    return b.sequenceId - a.sequenceId;
+  }
+}