@calmo/task-runner 3.4.0 → 3.5.0

package/openspec/project.md

@@ -1,32 +1,38 @@
 # Project: Task Runner
 
 ## Overview
+
 The 'task-runner' project is a TypeScript-based utility designed to manage and execute tasks. It incorporates features such as task cancellation, pre-execution validation, and concurrency control, providing a robust framework for workflow automation.
 
 ## Tech Stack
+
 - **Languages:** TypeScript 5.9.3
 - **Testing:** Vitest 4.0.17
 - **Core APIs:** AbortSignal/AbortController (Standard Web APIs for cancellation)
 - **Package Manager:** pnpm
 
 ## Architecture
+
 The project follows a modular architecture with distinct components for managing different aspects of task execution:
--   `EventBus.ts`: Handles event propagation within the system.
--   `TaskGraph.ts`: Represents the structure and dependencies of tasks.
--   `TaskGraphValidator.ts`: Ensures the validity of task graphs before execution.
--   `TaskRunner.ts`: Orchestrates the execution of tasks.
--   `WorkflowExecutor.ts`: Manages the overall workflow.
--   `contracts/`: Defines interfaces and types for various components, promoting loose coupling and clear API boundaries.
+
+- `EventBus.ts`: Handles event propagation within the system.
+- `TaskGraph.ts`: Represents the structure and dependencies of tasks.
+- `TaskGraphValidator.ts`: Ensures the validity of task graphs before execution.
+- `TaskRunner.ts`: Orchestrates the execution of tasks.
+- `WorkflowExecutor.ts`: Manages the overall workflow.
+- `contracts/`: Defines interfaces and types for various components, promoting loose coupling and clear API boundaries.
 
 ## Conventions
--   **Coding Style:** Adheres to standard TypeScript conventions, enforced by ESLint and Prettier.
--   **Commit Messages:** Follows conventional commits enforced by Commitlint.
--   **Git Hooks:** Utilizes Husky for pre-commit and commit-msg hooks.
--   **Testing:** Uses Vitest for unit and integration testing.
--   **Atomic Commits:** When working on complex multi-task features, commit after each distinct task, ensuring build, lint, and test success to establish safe rollback points.
+
+- **Coding Style:** Adheres to standard TypeScript conventions, enforced by ESLint and Prettier.
+- **Commit Messages:** Follows conventional commits enforced by Commitlint.
+- **Git Hooks:** Utilizes Husky for pre-commit and commit-msg hooks.
+- **Testing:** Uses Vitest for unit and integration testing.
+- **Atomic Commits:** When working on complex multi-task features, commit after each distinct task, ensuring build, lint, and test success to establish safe rollback points.
 
 ## Build/Test/Run Commands
--   **Install Dependencies:** `pnpm install`
--   **Build Project:** `pnpm build`
--   **Run Tests:** `pnpm test`
--   **Lint Code:** `pnpm lint`
+
+- **Install Dependencies:** `pnpm install`
+- **Build Project:** `pnpm build`
+- **Run Tests:** `pnpm test`
+- **Lint Code:** `pnpm lint`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
     "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"

package/src/EventBus.ts

@@ -61,23 +61,25 @@ export class EventBus<TContext> {
       | undefined;
     if (listeners) {
       for (const listener of listeners) {
-        try {
-          const result = listener(data);
-          if (result instanceof Promise) {
-            result.catch((error) => {
-              console.error(
-                `Error in event listener for ${String(event)}:`,
-                error
-              );
-            });
+        Promise.resolve().then(() => {
+          try {
+            const result = listener(data);
+            if (result instanceof Promise) {
+              result.catch((error) => {
+                console.error(
+                  `Error in event listener for ${String(event)}:`,
+                  error
+                );
+              });
+            }
+          } catch (error) {
+            // Prevent listener errors from bubbling up
+            console.error(
+              `Error in event listener for ${String(event)}:`,
+              error
+            );
           }
-        } catch (error) {
-          // Prevent listener errors from bubbling up
-          console.error(
-            `Error in event listener for ${String(event)}:`,
-            error
-          );
-        }
+        });
       }
     }
   }

package/src/TaskGraph.ts

@@ -2,18 +2,18 @@
  * Represents a single task in the task graph.
  */
 export interface Task {
-    /** Unique identifier for the task. */
-    id: string;
-    /** An array of task IDs that this task directly depends on. */
-    dependencies: string[];
-    /** Allows for any other properties specific to the task's payload or configuration. */
-    [key: string]: unknown;
+  /** Unique identifier for the task. */
+  id: string;
+  /** An array of task IDs that this task directly depends on. */
+  dependencies: string[];
+  /** Allows for any other properties specific to the task's payload or configuration. */
+  [key: string]: unknown;
 }
 
 /**
  * Represents the entire collection of tasks and their interdependencies.
  */
 export interface TaskGraph {
-    /** An array of tasks that make up the graph. */
-    tasks: Task[];
+  /** An array of tasks that make up the graph. */
+  tasks: Task[];
 }

package/src/TaskGraphValidationError.ts

@@ -5,7 +5,10 @@ import { ValidationResult } from "./contracts/ValidationResult.js";
  * Contains the validation result with detailed error information.
  */
 export class TaskGraphValidationError extends Error {
-  constructor(public result: ValidationResult, message: string) {
+  constructor(
+    public result: ValidationResult,
+    message: string
+  ) {
     super(message);
     this.name = "TaskGraphValidationError";
   }

package/src/TaskGraphValidator.ts

@@ -4,160 +4,165 @@ import { ValidationError } from "./contracts/ValidationError.js";
 import { TaskGraph } from "./TaskGraph.js";
 
 export class TaskGraphValidator implements ITaskGraphValidator {
-    /**
-     * Validates a given task graph for structural integrity.
-     * Checks for:
-     * 1. Duplicate task IDs.
-     * 2. Missing dependencies (tasks that depend on non-existent IDs).
-     * 3. Circular dependencies (cycles in the graph).
-     *
-     * @param taskGraph The task graph to validate.
-     * @returns A ValidationResult object indicating the outcome of the validation.
-     */
-    validate(taskGraph: TaskGraph): ValidationResult {
-        const errors: ValidationError[] = [];
-
-        // 1. Check for duplicate tasks
-        const taskIds = new Set<string>();
-        for (const task of taskGraph.tasks) {
-            if (taskIds.has(task.id)) {
-                errors.push({
-                    type: "duplicate_task",
-                    message: `Duplicate task detected with ID: ${task.id}`,
-                    details: { taskId: task.id }
-                });
-            } else {
-                taskIds.add(task.id);
-            }
-        }
+  /**
+   * Validates a given task graph for structural integrity.
+   * Checks for:
+   * 1. Duplicate task IDs.
+   * 2. Missing dependencies (tasks that depend on non-existent IDs).
+   * 3. Circular dependencies (cycles in the graph).
+   *
+   * @param taskGraph The task graph to validate.
+   * @returns A ValidationResult object indicating the outcome of the validation.
+   */
+  validate(taskGraph: TaskGraph): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    // 1. Check for duplicate tasks
+    const taskIds = new Set<string>();
+    for (const task of taskGraph.tasks) {
+      if (taskIds.has(task.id)) {
+        errors.push({
+          type: "duplicate_task",
+          message: `Duplicate task detected with ID: ${task.id}`,
+          details: { taskId: task.id },
+        });
+      } else {
+        taskIds.add(task.id);
+      }
+    }
 
-        // 2. Check for missing dependencies
-        for (const task of taskGraph.tasks) {
-            for (const dependenceId of task.dependencies) {
-                if (!taskIds.has(dependenceId)) {
-                    errors.push({
-                        type: "missing_dependency",
-                        message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
-                        details: { taskId: task.id, missingDependencyId: dependenceId }
-                    });
-                }
-            }
+    // 2. Check for missing dependencies
+    for (const task of taskGraph.tasks) {
+      for (const dependenceId of task.dependencies) {
+        if (!taskIds.has(dependenceId)) {
+          errors.push({
+            type: "missing_dependency",
+            message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
+            details: { taskId: task.id, missingDependencyId: dependenceId },
+          });
         }
+      }
+    }
 
-        // 3. Check for cycles
-        // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
-        const hasMissingDependencies = errors.some(e => e.type === "missing_dependency");
+    // 3. Check for cycles
+    // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
+    const hasMissingDependencies = errors.some(
+      (e) => e.type === "missing_dependency"
+    );
+
+    if (hasMissingDependencies) {
+      return {
+        isValid: errors.length === 0,
+        errors,
+      };
+    }
 
-        if (hasMissingDependencies) {
-            return {
-                isValid: errors.length === 0,
-                errors
-            };
-        }
+    // Build adjacency list
+    const adjacencyList = new Map<string, string[]>();
+    for (const task of taskGraph.tasks) {
+      adjacencyList.set(task.id, task.dependencies);
+    }
 
-        // Build adjacency list
-        const adjacencyList = new Map<string, string[]>();
-        for (const task of taskGraph.tasks) {
-            adjacencyList.set(task.id, task.dependencies);
-        }
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    for (const task of taskGraph.tasks) {
+      if (visited.has(task.id)) {
+        continue;
+      }
+
+      const path: string[] = [];
+      if (
+        this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
+      ) {
+        // 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)
+        const cycleStart = path[path.length - 1];
+        const cycleStartIndex = path.indexOf(cycleStart);
+        const cyclePath = path.slice(cycleStartIndex);
+
+        errors.push({
+          type: "cycle",
+          message: `Cycle detected: ${cyclePath.join(" -> ")}`,
+          details: { cyclePath },
+        });
+        // Break after first cycle found to avoid spamming similar errors
+        break;
+      }
+    }
 
-        const visited = new Set<string>();
-        const recursionStack = new Set<string>();
-
-        for (const task of taskGraph.tasks) {
-            if (visited.has(task.id)) {
-                continue;
-            }
-
-            const path: string[] = [];
-            if (this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)) {
-                // 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)
-                const cycleStart = path[path.length - 1];
-                const cycleStartIndex = path.indexOf(cycleStart);
-                const cyclePath = path.slice(cycleStartIndex);
-
-                errors.push({
-                    type: "cycle",
-                    message: `Cycle detected: ${cyclePath.join(" -> ")}`,
-                    details: { cyclePath }
-                });
-                // Break after first cycle found to avoid spamming similar errors
-                break;
-            }
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Creates a human-readable error message from a validation result.
+   * @param result The validation result containing errors.
+   * @returns A formatted error string.
+   */
+  createErrorMessage(result: ValidationResult): string {
+    const errorDetails = result.errors.map((e) => e.message);
+    return `Task graph validation failed: ${errorDetails.join("; ")}`;
+  }
+
+  private detectCycle(
+    startTaskId: string,
+    path: string[],
+    visited: Set<string>,
+    recursionStack: Set<string>,
+    adjacencyList: Map<string, string[]>
+  ): boolean {
+    // Use an explicit stack to avoid maximum call stack size exceeded errors
+    const stack: { taskId: string; index: number; dependencies: string[] }[] =
+      [];
+
+    visited.add(startTaskId);
+    recursionStack.add(startTaskId);
+    path.push(startTaskId);
+
+    stack.push({
+      taskId: startTaskId,
+      index: 0,
+      /* v8 ignore next */
+      dependencies: adjacencyList.get(startTaskId) ?? [],
+    });
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const { taskId, dependencies } = frame;
+
+      if (frame.index < dependencies.length) {
+        const dependenceId = dependencies[frame.index];
+        frame.index++;
+
+        if (recursionStack.has(dependenceId)) {
+          // Cycle detected
+          path.push(dependenceId);
+          return true;
         }
 
-        return {
-            isValid: errors.length === 0,
-            errors
-        };
-    }
-
-    /**
-     * Creates a human-readable error message from a validation result.
-     * @param result The validation result containing errors.
-     * @returns A formatted error string.
-     */
-    createErrorMessage(result: ValidationResult): string {
-        const errorDetails = result.errors.map(e => e.message);
-        return `Task graph validation failed: ${errorDetails.join("; ")}`;
-    }
+        if (!visited.has(dependenceId)) {
+          visited.add(dependenceId);
+          recursionStack.add(dependenceId);
+          path.push(dependenceId);
 
-    private detectCycle(
-        startTaskId: string,
-        path: string[],
-        visited: Set<string>,
-        recursionStack: Set<string>,
-        adjacencyList: Map<string, string[]>
-    ): boolean {
-        // Use an explicit stack to avoid maximum call stack size exceeded errors
-        const stack: { taskId: string; index: number; dependencies: string[] }[] = [];
-
-        visited.add(startTaskId);
-        recursionStack.add(startTaskId);
-        path.push(startTaskId);
-
-        stack.push({
-            taskId: startTaskId,
+          stack.push({
+            taskId: dependenceId,
             index: 0,
             /* v8 ignore next */
-            dependencies: adjacencyList.get(startTaskId) ?? []
-        });
-
-        while (stack.length > 0) {
-            const frame = stack[stack.length - 1];
-            const { taskId, dependencies } = frame;
-
-            if (frame.index < dependencies.length) {
-                const dependenceId = dependencies[frame.index];
-                frame.index++;
-
-                if (recursionStack.has(dependenceId)) {
-                    // Cycle detected
-                    path.push(dependenceId);
-                    return true;
-                }
-
-                if (!visited.has(dependenceId)) {
-                    visited.add(dependenceId);
-                    recursionStack.add(dependenceId);
-                    path.push(dependenceId);
-
-                    stack.push({
-                        taskId: dependenceId,
-                        index: 0,
-                        /* v8 ignore next */
-                        dependencies: adjacencyList.get(dependenceId) ?? []
-                    });
-                }
-            } else {
-                // Finished all dependencies for this node
-                recursionStack.delete(taskId);
-                path.pop();
-                stack.pop();
-            }
+            dependencies: adjacencyList.get(dependenceId) ?? [],
+          });
         }
-
-        return false;
+      } else {
+        // Finished all dependencies for this node
+        recursionStack.delete(taskId);
+        path.pop();
+        stack.pop();
+      }
     }
+
+    return false;
+  }
 }

package/src/TaskRunner.ts

@@ -2,7 +2,10 @@ import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
 import { TaskGraphValidator } from "./TaskGraphValidator.js";
 import { TaskGraph } from "./TaskGraph.js";
-import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
+import {
+  RunnerEventPayloads,
+  RunnerEventListener,
+} from "./contracts/RunnerEvents.js";
 import { EventBus } from "./EventBus.js";
 import { WorkflowExecutor } from "./WorkflowExecutor.js";
 import { TaskRunnerExecutionConfig } from "./TaskRunnerExecutionConfig.js";
@@ -24,9 +27,8 @@ export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
 export class TaskRunner<TContext> {
   private eventBus = new EventBus<TContext>();
   private validator = new TaskGraphValidator();
-  private executionStrategy: IExecutionStrategy<TContext> = new RetryingExecutionStrategy(
-    new StandardExecutionStrategy()
-  );
+  private executionStrategy: IExecutionStrategy<TContext> =
+    new RetryingExecutionStrategy(new StandardExecutionStrategy());
 
   /**
    * @param context The shared context object to be passed to each task.
@@ -85,7 +87,6 @@ export class TaskRunner<TContext> {
     const safeId = (name: string) => JSON.stringify(name);
     const sanitize = (name: string) => this.sanitizeMermaidId(name);
 
-
     // Add all nodes first to ensure they exist
     for (const step of steps) {
       // Using the name as both ID and Label for simplicity
@@ -98,9 +99,7 @@ export class TaskRunner<TContext> {
     for (const step of steps) {
       if (step.dependencies) {
         for (const dep of step.dependencies) {
-          graphLines.push(
-            `  ${sanitize(dep)} --> ${sanitize(step.name)}`
-          );
+          graphLines.push(`  ${sanitize(dep)} --> ${sanitize(step.name)}`);
         }
       }
     }
@@ -162,40 +161,42 @@ export class TaskRunner<TContext> {
 
     // We need to handle the timeout cleanup properly.
     if (config?.timeout !== undefined) {
-       const controller = new AbortController();
-       const timeoutId = setTimeout(() => {
-         controller.abort(new Error(`Workflow timed out after ${config.timeout}ms`));
-       }, config.timeout);
-
-       let effectiveSignal = controller.signal;
-       let onAbort: (() => void) | undefined;
-
-       // Handle combination of signals if user provided one
-       if (config.signal) {
-          if (config.signal.aborted) {
-             // If already aborted, use it directly (WorkflowExecutor handles early abort)
-             // We can cancel timeout immediately
-             clearTimeout(timeoutId);
-             effectiveSignal = config.signal;
-          } else {
-             // Listen to user signal to abort our controller
-             onAbort = () => {
-                controller.abort(config.signal?.reason);
-             };
-             config.signal.addEventListener("abort", onAbort);
-          }
-       }
-
-       try {
-         return await executor.execute(steps, effectiveSignal);
-       } finally {
-         clearTimeout(timeoutId);
-         if (config.signal && onAbort) {
-            config.signal.removeEventListener("abort", onAbort);
-         }
-       }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort(
+          new Error(`Workflow timed out after ${config.timeout}ms`)
+        );
+      }, config.timeout);
+
+      let effectiveSignal = controller.signal;
+      let onAbort: (() => void) | undefined;
+
+      // Handle combination of signals if user provided one
+      if (config.signal) {
+        if (config.signal.aborted) {
+          // If already aborted, use it directly (WorkflowExecutor handles early abort)
+          // We can cancel timeout immediately
+          clearTimeout(timeoutId);
+          effectiveSignal = config.signal;
+        } else {
+          // Listen to user signal to abort our controller
+          onAbort = () => {
+            controller.abort(config.signal?.reason);
+          };
+          config.signal.addEventListener("abort", onAbort);
+        }
+      }
+
+      try {
+        return await executor.execute(steps, effectiveSignal);
+      } finally {
+        clearTimeout(timeoutId);
+        if (config.signal && onAbort) {
+          config.signal.removeEventListener("abort", onAbort);
+        }
+      }
     } else {
-       return executor.execute(steps, config?.signal);
+      return executor.execute(steps, config?.signal);
     }
   }
 }

package/src/TaskRunnerBuilder.ts

@@ -1,5 +1,8 @@
 import { TaskRunner } from "./TaskRunner.js";
-import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
+import {
+  RunnerEventPayloads,
+  RunnerEventListener,
+} from "./contracts/RunnerEvents.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 
 /**
@@ -9,7 +12,10 @@ export class TaskRunnerBuilder<TContext> {
   private context: TContext;
   private strategy?: IExecutionStrategy<TContext>;
   private listeners: {
-    [K in keyof RunnerEventPayloads<TContext>]?: RunnerEventListener<TContext, K>[];
+    [K in keyof RunnerEventPayloads<TContext>]?: RunnerEventListener<
+      TContext,
+      K
+    >[];
   } = {};
 
   /**
@@ -57,7 +63,9 @@ export class TaskRunnerBuilder<TContext> {
       runner.setExecutionStrategy(this.strategy);
     }
 
-    (Object.keys(this.listeners) as Array<keyof RunnerEventPayloads<TContext>>).forEach((event) => {
+    (
+      Object.keys(this.listeners) as Array<keyof RunnerEventPayloads<TContext>>
+    ).forEach((event) => {
       const callbacks = this.listeners[event];
       // callbacks is always defined because we are iterating keys of the object
       callbacks!.forEach((callback) =>

package/src/TaskStateManager.ts

@@ -55,8 +55,7 @@ export class TaskStateManager<TContext> {
           status: "skipped",
           message: `Skipped because dependency '${failedDep}' failed${depError}`,
         };
-        this.results.set(step.name, result);
-        this.eventBus.emit("taskSkipped", { step, result });
+        this.markSkipped(step, result);
         toRemove.push(step);
       } else if (!blocked) {
         toRun.push(step);
@@ -139,4 +138,15 @@ export class TaskStateManager<TContext> {
   hasPendingTasks(): boolean {
     return this.pendingSteps.size > 0;
   }
+
+  /**
+   * 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 {
+    this.running.delete(step.name);
+    this.results.set(step.name, result);
+    this.eventBus.emit("taskSkipped", { step, result });
+  }
 }

package/src/TaskStep.ts

@@ -12,6 +12,12 @@ export interface TaskStep<TContext> {
   dependencies?: string[];
   /** Optional retry configuration for the task. */
   retry?: TaskRetryConfig;
+  /**
+   * Optional function to determine if the task should run.
+   * If it returns false (synchronously or asynchronously), the task is skipped.
+   */
+  condition?: (context: TContext) => boolean | Promise<boolean>;
+
   /**
    * The core logic of the task.
    * @param context The shared context object, allowing for state to be passed between tasks.