@calmo/task-runner 1.1.1 → 1.2.0

package/src/TaskGraph.ts

@@ -0,0 +1,19 @@
+/**
+ * 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;
+}
+
+/**
+ * Represents the entire collection of tasks and their interdependencies.
+ */
+export interface TaskGraph {
+    /** An array of tasks that make up the graph. */
+    tasks: Task[];
+}

package/src/TaskGraphValidator.ts

@@ -0,0 +1,126 @@
+import { ITaskGraphValidator } from "./contracts/ITaskGraphValidator.js";
+import { ValidationResult } from "./contracts/ValidationResult.js";
+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);
+            }
+        }
+
+        // 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");
+
+        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);
+        }
+
+        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
+        };
+    }
+
+    private detectCycle(
+        taskId: string,
+        path: string[],
+        visited: Set<string>,
+        recursionStack: Set<string>,
+        adjacencyList: Map<string, string[]>
+    ): boolean {
+        visited.add(taskId);
+        recursionStack.add(taskId);
+        path.push(taskId);
+
+        const dependencies = adjacencyList.get(taskId)!;
+        for (const dependenceId of dependencies) {
+            if (
+                !visited.has(dependenceId) &&
+                this.detectCycle(dependenceId, path, visited, recursionStack, adjacencyList)
+            ) {
+                return true;
+            } else if (recursionStack.has(dependenceId)) {
+                // Cycle detected
+                // Add the dependency to complete the visual cycle
+                path.push(dependenceId);
+                return true;
+            }
+        }
+
+        recursionStack.delete(taskId);
+        path.pop();
+        return false;
+    }
+}

package/src/TaskRunner.ts

@@ -1,5 +1,7 @@
 import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
+import { TaskGraphValidator } from "./TaskGraphValidator.js";
+import { TaskGraph } from "./TaskGraph.js";
 
 /**
  * Define the payload for every possible event in the lifecycle.
@@ -51,6 +53,7 @@ type ListenerMap<TContext> = {
 export class TaskRunner<TContext> {
   private running = new Set<string>();
   private listeners: ListenerMap<TContext> = {};
+  private validator = new TaskGraphValidator();
 
   /**
    * @param context The shared context object to be passed to each task.
@@ -128,6 +131,53 @@ export class TaskRunner<TContext> {
    * and values are the corresponding TaskResult objects.
    */
   async execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>> {
+    // Validate the task graph before execution
+    const taskGraph: TaskGraph = {
+      tasks: steps.map((step) => ({
+        id: step.name,
+        dependencies: step.dependencies ?? [],
+      })),
+    };
+
+    const validationResult = this.validator.validate(taskGraph);
+    if (!validationResult.isValid) {
+      // Construct error message compatible with legacy tests
+      const affectedTasks = new Set<string>();
+      const errorDetails: string[] = [];
+
+      for (const error of validationResult.errors) {
+        errorDetails.push(error.message);
+        switch (error.type) {
+          case "cycle": {
+            // details is { cyclePath: string[] }
+            const path = (error.details as { cyclePath: string[] }).cyclePath;
+            // The last element duplicates the first in the path representation, so valid unique tasks are slice(0, -1) or just all as Set handles uniq
+            path.forEach((t) => affectedTasks.add(t));
+            break;
+          }
+          case "missing_dependency": {
+            // details is { taskId: string, missingDependencyId: string }
+            const d = error.details as { taskId: string };
+            affectedTasks.add(d.taskId);
+            break;
+          }
+          case "duplicate_task": {
+            const d = error.details as { taskId: string };
+            affectedTasks.add(d.taskId);
+            break;
+          }
+        }
+      }
+
+      // Legacy error format: "Circular dependency or missing dependency detected. Unable to run tasks: A, B"
+      const taskList = Array.from(affectedTasks).join(", ");
+      const legacyMessage = `Circular dependency or missing dependency detected. Unable to run tasks: ${taskList}`;
+      const detailedMessage = `Task graph validation failed: ${errorDetails.join("; ")}`;
+
+      // Combine them to satisfy both legacy tests (checking for legacy message) and new requirements (clear details)
+      throw new Error(`${legacyMessage} | ${detailedMessage}`);
+    }
+
     this.emit("workflowStart", { context: this.context, steps });
 
     const results = new Map<string, TaskResult>();
@@ -146,7 +196,6 @@ export class TaskRunner<TContext> {
 
       // Skip tasks with failed dependencies
       for (const step of pendingSteps) {
-        if (results.has(step.name)) continue;
         const deps = step.dependencies ?? [];
         const failedDep = deps.find(
           (dep) => results.has(dep) && results.get(dep)?.status !== "success"
@@ -161,18 +210,6 @@ export class TaskRunner<TContext> {
         }
       }
 
-      if (
-        readySteps.length === 0 &&
-        this.running.size === 0 &&
-        results.size < steps.length
-      ) {
-        const unrunnableSteps = steps.filter((s) => !results.has(s.name));
-        const unrunnableStepNames = unrunnableSteps.map((s) => s.name);
-        throw new Error(
-          `Circular dependency or missing dependency detected. Unable to run tasks: ${unrunnableStepNames.join(", ")}`
-        );
-      }
-
       await Promise.all(
         readySteps.map(async (step) => {
           this.running.add(step.name);

package/src/contracts/ITaskGraphValidator.ts

@@ -0,0 +1,14 @@
+import { TaskGraph } from "../TaskGraph.js";
+import { ValidationResult } from "./ValidationResult.js";
+
+/**
+ * Defines the interface for a task graph validator.
+ */
+export interface ITaskGraphValidator {
+    /**
+     * Validates a given task graph for structural integrity.
+     * @param taskGraph The task graph to validate.
+     * @returns A ValidationResult object indicating the outcome of the validation.
+     */
+    validate(taskGraph: TaskGraph): ValidationResult;
+}

package/src/contracts/ValidationError.ts

@@ -0,0 +1,11 @@
+/**
+ * Describes a specific validation error found in the task graph.
+ */
+export interface ValidationError {
+    /** The type of validation error. */
+    type: "cycle" | "missing_dependency" | "duplicate_task";
+    /** A human-readable message describing the error. */
+    message: string;
+    /** Optional detailed information about the error, e.g., the cycle path, or the task with a missing dependency. */
+    details?: unknown;
+}

package/src/contracts/ValidationResult.ts

@@ -0,0 +1,11 @@
+import { ValidationError } from "./ValidationError.js";
+
+/**
+ * The result of a task graph validation operation.
+ */
+export interface ValidationResult {
+    /** True if the graph is valid, false otherwise. */
+    isValid: boolean;
+    /** An array of ValidationError objects if the graph is not valid. Empty if isValid is true. */
+    errors: ValidationError[];
+}

package/test-report.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<testsuites name="vitest tests" tests="19" failures="0" errors="0" time="0.135083259">
-    <testsuite name="tests/ComplexScenario.test.ts" timestamp="2026-01-18T03:50:46.197Z" hostname="runnervmmtnos" tests="2" failures="0" errors="0" skipped="0" time="0.009883356">
-        <testcase classname="tests/ComplexScenario.test.ts" name="Complex Scenario Integration Tests &gt; 1. All steps execute when all succeed and context is hydrated" time="0.006132912">
+<testsuites name="vitest tests" tests="31" failures="0" errors="0" time="0.148869921">
+    <testsuite name="tests/ComplexScenario.test.ts" timestamp="2026-01-18T03:56:21.866Z" hostname="runnervmmtnos" tests="2" failures="0" errors="0" skipped="0" time="0.008692833">
+        <testcase classname="tests/ComplexScenario.test.ts" name="Complex Scenario Integration Tests &gt; 1. All steps execute when all succeed and context is hydrated" time="0.005600185">
             <system-out>
 Running StepA
 Running StepB
@@ -15,45 +15,73 @@ Running StepG
 
             </system-out>
         </testcase>
-        <testcase classname="tests/ComplexScenario.test.ts" name="Complex Scenario Integration Tests &gt; 2. The &apos;skip&apos; propagation works as intended if something breaks up in the tree" time="0.00153012">
+        <testcase classname="tests/ComplexScenario.test.ts" name="Complex Scenario Integration Tests &gt; 2. The &apos;skip&apos; propagation works as intended if something breaks up in the tree" time="0.001185557">
         </testcase>
     </testsuite>
-    <testsuite name="tests/TaskRunner.test.ts" timestamp="2026-01-18T03:50:46.199Z" hostname="runnervmmtnos" tests="10" failures="0" errors="0" skipped="0" time="0.109323687">
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should run tasks in the correct sequential order" time="0.002455516">
+    <testsuite name="tests/TaskGraphValidator.test.ts" timestamp="2026-01-18T03:56:21.867Z" hostname="runnervmmtnos" tests="9" failures="0" errors="0" skipped="0" time="0.00859907">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should be instantiated" time="0.001784141">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle an empty list of tasks gracefully" time="0.000305152">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should return valid result for empty graph" time="0.001494487">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should run independent tasks in parallel" time="0.100731975">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should detect duplicate tasks" time="0.001370324">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should skip dependent tasks if a root task fails" time="0.00046882">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should detect missing dependencies" time="0.000348985">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should throw an error for &apos;circular dependency&apos;" time="0.00185594">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should detect cycles" time="0.000306475">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should throw an error for &apos;missing dependency&apos;" time="0.000228108">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should return valid for a correct graph" time="0.000329659">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle tasks that throw an error during execution" time="0.000243576">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should not detect cycles if missing dependencies are present" time="0.000273113">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should skip tasks whose dependencies are skipped" time="0.000262202">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should detect more complex cycles" time="0.000237105">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle tasks that throw a non-Error object during execution" time="0.000268865">
+        <testcase classname="tests/TaskGraphValidator.test.ts" name="TaskGraphValidator &gt; should handle cycle detection with no cycles but shared dependencies" time="0.000156013">
         </testcase>
-        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle duplicate steps where one gets skipped due to failed dependency" time="0.00040515">
+    </testsuite>
+    <testsuite name="tests/TaskRunner.test.ts" timestamp="2026-01-18T03:56:21.869Z" hostname="runnervmmtnos" tests="10" failures="0" errors="0" skipped="0" time="0.111209003">
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should run tasks in the correct sequential order" time="0.003746958">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle an empty list of tasks gracefully" time="0.00041004">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should run independent tasks in parallel" time="0.100646475">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should skip dependent tasks if a root task fails" time="0.000392958">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should throw an error for &apos;circular dependency&apos;" time="0.001934242">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should throw an error for &apos;missing dependency&apos;" time="0.000290306">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle tasks that throw an error during execution" time="0.00024479">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should skip tasks whose dependencies are skipped" time="0.000380384">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle tasks that throw a non-Error object during execution" time="0.000391555">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle duplicate steps where one gets skipped due to failed dependency" time="0.00036763">
         </testcase>
     </testsuite>
-    <testsuite name="tests/TaskRunnerEvents.test.ts" timestamp="2026-01-18T03:50:46.201Z" hostname="runnervmmtnos" tests="7" failures="0" errors="0" skipped="0" time="0.015876216">
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire all lifecycle events in a successful run" time="0.004415742">
+    <testsuite name="tests/TaskRunnerEvents.test.ts" timestamp="2026-01-18T03:56:21.871Z" hostname="runnervmmtnos" tests="7" failures="0" errors="0" skipped="0" time="0.013775682">
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire all lifecycle events in a successful run" time="0.004847334">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire taskSkipped event when dependency fails" time="0.004274688">
         </testcase>
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire taskSkipped event when dependency fails" time="0.005824924">
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should not crash if a listener throws an error" time="0.001365544">
         </testcase>
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should not crash if a listener throws an error" time="0.001840071">
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire workflow events even for empty step list" time="0.000304822">
         </testcase>
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire workflow events even for empty step list" time="0.000423804">
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should handle unsubscribe correctly" time="0.000354125">
         </testcase>
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should handle unsubscribe correctly" time="0.000460765">
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should safely handle off() when no listeners exist" time="0.00015962">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should support multiple listeners for the same event" time="0.000313028">
+        </testcase>
+    </testsuite>
+    <testsuite name="tests/integration.test.ts" timestamp="2026-01-18T03:56:21.873Z" hostname="runnervmmtnos" tests="3" failures="0" errors="0" skipped="0" time="0.006593333">
+        <testcase classname="tests/integration.test.ts" name="TaskRunner Validation Integration &gt; should throw validation error with clear message for duplicate tasks" time="0.004083429">
         </testcase>
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should safely handle off() when no listeners exist" time="0.000210355">
+        <testcase classname="tests/integration.test.ts" name="TaskRunner Validation Integration &gt; should throw validation error with clear message for missing dependencies" time="0.000367681">
         </testcase>
-        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should support multiple listeners for the same event" time="0.000482585">
+        <testcase classname="tests/integration.test.ts" name="TaskRunner Validation Integration &gt; should throw validation error with clear message for cycles" time="0.000389051">
         </testcase>
     </testsuite>
 </testsuites>