@calmo/task-runner 3.8.4 → 4.1.0

package/openspec/specs/task-runner/spec.md

@@ -0,0 +1,174 @@
+# task-runner Specification
+
+## Purpose
+
+TBD - created by archiving change add-external-task-cancellation. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: TaskRunner Execution
+
+The `TaskRunner` SHALL execute a sequence of `TaskStep`s based on their dependencies, processing inputs and producing outputs.
+
+#### Scenario: Successful execution
+
+- **WHEN** all `TaskStep`s complete successfully
+- **THEN** the `TaskRunner` returns a successful workflow result.
+
+#### Scenario: Execution with AbortSignal
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal`
+- **THEN** the `TaskRunner` monitors the `AbortSignal` for cancellation requests.
+
+#### Scenario: Execution with Global Timeout
+
+- **WHEN** `TaskRunner.execute` is called with a `timeout` option
+- **THEN** the `TaskRunner` monitors the elapsed time for the workflow.
+
+### Requirement: External Workflow Cancellation
+
+The `TaskRunner` SHALL allow external cancellation of an ongoing workflow.
+
+#### Scenario: Workflow cancelled by AbortSignal
+
+- **WHEN** an `AbortSignal` provided to `TaskRunner.execute` is triggered
+- **THEN** the `TaskRunner` immediately attempts to stop execution of current and pending tasks.
+
+#### Scenario: Workflow cancelled by Global Timeout
+
+- **WHEN** the specified global `timeout` for `TaskRunner.execute` is reached
+- **THEN** the `TaskRunner` immediately attempts to stop execution of current and pending tasks.
+
+#### Scenario: Tasks marked as cancelled
+
+- **WHEN** a workflow is cancelled (by `AbortSignal` or `timeout`)
+- **THEN** all unexecuted `TaskStep`s SHALL be marked with a 'cancelled' status in the final result.
+
+#### Scenario: Pre-aborted workflow
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal` that is already aborted
+- **THEN** the `TaskRunner` SHALL return immediately with all tasks marked as cancelled, without executing any steps.
+
+#### Scenario: Graceful interruption of current task
+
+- **WHEN** a workflow is cancelled and a `TaskStep` is currently executing
+- **THEN** the `TaskStep` SHALL receive the cancellation signal (e.g., via `AbortSignal` context) to allow for graceful interruption.
+
+### Requirement: Cancellation Conflict Resolution
+
+The `TaskRunner` SHALL handle scenarios where both `AbortSignal` and global `timeout` are provided.
+
+#### Scenario: AbortSignal precedes Timeout
+
+- **WHEN** both `AbortSignal` and `timeout` are provided, and `AbortSignal` is triggered first
+- **THEN** the `TaskRunner` SHALL cancel the workflow based on the `AbortSignal`, ignoring the `timeout`.
+
+#### Scenario: Timeout precedes AbortSignal
+
+- **WHEN** both `AbortSignal` and `timeout` are provided, and `timeout` is reached first
+- **THEN** the `TaskRunner` SHALL cancel the workflow based on the `timeout`, ignoring the `AbortSignal`.
+
+### Requirement: Integration Verification
+
+The system's integrity SHALL be verified through comprehensive integration scenarios executed against the real runtime environment without mocks.
+
+#### Scenario: Complex Graph Execution
+
+- **WHEN** a complex task graph (diamonds, sequences, parallel branches) is executed
+- **THEN** the system SHALL respect all dependency constraints and execution orders.
+- **AND** the final state MUST reflect the cumulative side effects of all successful tasks.
+
+#### Scenario: Failure Propagation
+
+- **WHEN** a task fails in a complex graph
+- **THEN** ONLY dependent tasks SHALL be skipped
+- **AND** independent branches SHALL continue to execute to completion.
+
+#### Scenario: Context Integrity
+
+- **WHEN** multiple tasks mutate the shared context
+- **THEN** state changes MUST be propagated correctly to downstream tasks.
+
+### Requirement: Modular Execution Architecture
+
+The system SHALL support pluggable execution strategies and decoupled state management.
+
+#### Scenario: Pluggable Strategy
+
+- **WHEN** configured with a custom execution strategy
+- **THEN** the `TaskRunner` SHALL delegate the execution logic to that strategy.
+
+### Requirement: Dry Run Execution Strategy
+
+The system SHALL provide a `DryRunExecutionStrategy` that implements `IExecutionStrategy`.
+
+#### Scenario: Simulating execution
+
+- **WHEN** `WorkflowExecutor` is configured with `DryRunExecutionStrategy`
+- **AND** `execute` is called
+- **THEN** it SHALL traverse the dependency graph respecting order
+- **AND** it SHALL NOT execute the actual work of the `TaskStep`.
+- **AND** it SHALL return `TaskResult`s with a status indicating successful simulation (e.g., `simulated` or `success`).
+
+### Requirement: Mermaid Visualization
+
+The system SHALL provide a utility to generate a Mermaid.js graph from task steps.
+
+#### Scenario: Generate Mermaid Graph
+
+- **GIVEN** a list of `TaskStep`s with dependencies
+- **WHEN** `generateMermaidGraph` is called
+- **THEN** it SHALL return a valid Mermaid flowchart syntax string.
+- **AND** dependencies SHALL be represented as arrows (`-->`).
+- **AND** independent tasks SHALL appear as nodes.
+
+### Requirement: Task Retry Configuration
+
+The `TaskStep` interface SHALL support an optional `retry` property of type `TaskRetryConfig`.
+
+#### Scenario: Retry Config Structure
+
+- **GIVEN** a `TaskRetryConfig` object
+- **THEN** it SHALL support:
+  - `attempts`: Number of retry attempts (default: 0).
+  - `delay`: Base delay in milliseconds (default: 0).
+  - `backoff`: Backoff strategy ('fixed' | 'exponential') (default: 'fixed').
+
+### Requirement: Retrying Execution Strategy
+
+The system SHALL provide a `RetryingExecutionStrategy` that implements `IExecutionStrategy` and wraps another `IExecutionStrategy`.
+
+#### Scenario: Successful execution
+
+- **WHEN** the inner strategy returns a successful `TaskResult`
+- **THEN** `RetryingExecutionStrategy` SHALL return that result immediately.
+
+#### Scenario: Retry on failure
+
+- **WHEN** the inner strategy throws or returns a failed `TaskResult`
+- **AND** the task has `retry.attempts > 0`
+- **THEN** it SHALL wait for the configured `delay`.
+- **AND** it SHALL re-execute the task using the inner strategy.
+- **AND** it SHALL decrement the remaining attempts.
+
+#### Scenario: Max attempts reached
+
+- **WHEN** the task fails and no attempts remain
+- **THEN** it SHALL return the failed result (or throw).
+
+#### Scenario: Exponential Backoff
+
+- **WHEN** `retry.backoff` is 'exponential'
+- **THEN** the delay SHALL increase for each attempt (e.g., `delay * 2^attempt`).
+
+### Requirement: Task Execution Metrics
+
+The system SHALL record timing metrics for each executed task, including start time, end time, and duration.
+
+#### Scenario: Successful execution
+- **WHEN** a task completes successfully
+- **THEN** the task result contains the start timestamp, end timestamp, and duration in milliseconds
+
+#### Scenario: Failed execution
+- **WHEN** a task fails
+- **THEN** the task result contains the start timestamp, end timestamp, and duration in milliseconds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "3.8.4",
+  "version": "4.1.0",
   "description": "A lightweight, type-safe, and domain-agnostic task orchestration engine. It resolves a Directed Acyclic Graph (DAG) of steps, executes independent tasks in parallel, and manages a shared context across the pipeline.",
   "repository": {
     "type": "git",
@@ -15,16 +15,6 @@
     }
   },
   "type": "module",
-  "scripts": {
-    "build": "tsc",
-    "test": "tsc --noEmit -p tsconfig.test.json && vitest run --coverage",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "all": "pnpm run build && pnpm run test && pnpm run lint",
-    "format": "prettier --write .",
-    "prepare": "husky",
-    "commit": "git add . &&git-cz"
-  },
   "config": {
     "commitizen": {
       "path": "git-cz"
@@ -44,17 +34,10 @@
   ],
   "author": "",
   "license": "ISC",
-  "packageManager": "pnpm@10.28.0",
   "devDependencies": {
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^20.3.1",
     "@eslint/js": "^9.39.2",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.2",
-    "@semantic-release/npm": "^13.1.3",
-    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/node": "^25.0.9",
     "@vitest/coverage-v8": "4.0.17",
     "eslint": "^9.39.2",
@@ -62,9 +45,17 @@
     "git-cz": "^4.9.0",
     "husky": "^9.1.7",
     "prettier": "^3.8.0",
-    "semantic-release": "^25.0.2",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.53.0",
     "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit -p tsconfig.test.json && vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "all": "pnpm run build && pnpm run test && pnpm run lint",
+    "format": "prettier --write .",
+    "commit": "git add . &&git-cz"
   }
-}
+}

package/release-please-config.json

@@ -0,0 +1,9 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@calmo/task-runner"
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

package/src/TaskResult.ts

@@ -12,4 +12,13 @@ export interface TaskResult {
   error?: string;
   /** Optional data produced by the step for later inspection. */
   data?: unknown;
+  /** Optional execution metrics for the task. */
+  metrics?: {
+    /** Start time in milliseconds (performance.now). */
+    startTime: number;
+    /** End time in milliseconds (performance.now). */
+    endTime: number;
+    /** Duration in milliseconds. */
+    duration: number;
+  };
 }

package/src/TaskRunner.ts

@@ -78,19 +78,59 @@ export class TaskRunner<TContext> {
    */
   public static getMermaidGraph<T>(steps: TaskStep<T>[]): string {
     const graphLines = ["graph TD"];
+    const idMap = new Map<string, string>();
+    const usedIds = new Set<string>();
+    const baseIdCounters = new Map<string, number>();
 
-    const sanitize = (name: string) => this.sanitizeMermaidId(name);
+    const getUniqueId = (name: string) => {
+      if (idMap.has(name)) {
+        return idMap.get(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;
+    };
 
+    // 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) {
-      graphLines.push(
-        `  ${sanitize(step.name)}[${JSON.stringify(step.name)}]`
-      );
+      getUniqueId(step.name);
+    }
+
+    for (const step of steps) {
+      const stepId = getUniqueId(step.name);
+      graphLines.push(`  ${stepId}[${JSON.stringify(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.push(`  ${depId} --> ${stepId}`);
         }
       }
     }
@@ -171,37 +211,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,39 @@ 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) {
+          if (!this.dependencyGraph.has(dep)) {
+            this.dependencyGraph.set(dep, []);
+          }
+          this.dependencyGraph.get(dep)!.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 +84,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 +124,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 +163,54 @@ 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];
+    // 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()!;
+      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.
@@ -114,14 +115,11 @@ export class WorkflowExecutor<TContext> {
 
     // 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,7 +127,7 @@ export class WorkflowExecutor<TContext> {
         break;
       }
 
-      const step = this.readyQueue.shift()!;
+      const step = this.readyQueue.pop()!;
 
       const taskPromise = this.executeTaskStep(step, signal)
         .finally(() => {
@@ -194,16 +192,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/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,
     });
   }
 }