@calmo/task-runner 1.1.1 → 1.2.0

package/coverage/lcov.info

@@ -1,108 +1,199 @@
 TN:
+SF:src/TaskGraphValidator.ts
+FN:17,(anonymous_0)
+FN:49,(anonymous_1)
+FN:96,(anonymous_2)
+FNF:3
+FNH:3
+FNDA:29,(anonymous_0)
+FNDA:7,(anonymous_1)
+FNDA:51,(anonymous_2)
+DA:18,29
+DA:21,29
+DA:22,29
+DA:23,61
+DA:24,3
+DA:30,58
+DA:35,29
+DA:36,61
+DA:37,41
+DA:38,5
+DA:49,29
+DA:51,29
+DA:52,4
+DA:59,25
+DA:60,25
+DA:61,54
+DA:64,25
+DA:65,25
+DA:67,25
+DA:68,49
+DA:69,3
+DA:72,46
+DA:73,46
+DA:76,4
+DA:77,4
+DA:78,4
+DA:80,4
+DA:86,4
+DA:90,25
+DA:103,51
+DA:104,51
+DA:105,51
+DA:107,51
+DA:108,51
+DA:109,33
+DA:113,5
+DA:114,28
+DA:117,4
+DA:118,4
+DA:122,42
+DA:123,42
+DA:124,42
+LF:42
+LH:42
+BRDA:23,0,0,3
+BRDA:23,0,1,58
+BRDA:37,1,0,5
+BRDA:37,1,1,36
+BRDA:51,2,0,4
+BRDA:51,2,1,25
+BRDA:68,3,0,3
+BRDA:68,3,1,46
+BRDA:73,4,0,4
+BRDA:73,4,1,42
+BRDA:109,5,0,5
+BRDA:109,5,1,28
+BRDA:110,6,0,33
+BRDA:110,6,1,5
+BRDA:114,7,0,4
+BRDA:114,7,1,24
+BRF:16
+BRH:16
+end_of_record
+TN:
 SF:src/TaskRunner.ts
-FN:58,(anonymous_0)
-FN:65,(anonymous_1)
-FN:85,(anonymous_2)
-FN:101,(anonymous_3)
-FN:130,(anonymous_4)
-FN:137,(anonymous_5)
-FN:140,(anonymous_6)
-FN:143,(anonymous_7)
-FN:152,(anonymous_8)
-FN:169,(anonymous_9)
-FN:170,(anonymous_10)
-FN:177,(anonymous_11)
+FN:61,(anonymous_0)
+FN:68,(anonymous_1)
+FN:88,(anonymous_2)
+FN:104,(anonymous_3)
+FN:133,(anonymous_4)
+FN:136,(anonymous_5)
+FN:155,(anonymous_6)
+FN:187,(anonymous_7)
+FN:190,(anonymous_8)
+FN:193,(anonymous_9)
+FN:201,(anonymous_10)
+FN:214,(anonymous_11)
 FNF:12
 FNH:12
-FNDA:19,(anonymous_0)
+FNDA:22,(anonymous_0)
 FNDA:12,(anonymous_1)
 FNDA:2,(anonymous_2)
-FNDA:94,(anonymous_3)
-FNDA:18,(anonymous_4)
-FNDA:80,(anonymous_5)
-FNDA:57,(anonymous_6)
-FNDA:42,(anonymous_7)
-FNDA:45,(anonymous_8)
-FNDA:6,(anonymous_9)
-FNDA:3,(anonymous_10)
-FNDA:27,(anonymous_11)
-DA:52,19
-DA:53,19
-DA:58,19
-DA:69,12
-DA:72,11
-DA:75,12
-DA:89,2
-DA:90,1
-DA:105,94
-DA:108,94
-DA:109,13
-DA:110,13
-DA:111,13
-DA:114,1
-DA:131,18
-DA:133,18
-DA:135,18
-DA:136,26
-DA:137,80
-DA:140,26
-DA:141,57
-DA:142,57
-DA:143,42
-DA:148,26
-DA:149,57
-DA:150,56
-DA:151,57
-DA:152,45
-DA:154,57
-DA:155,7
-DA:159,7
-DA:160,7
-DA:164,26
-DA:169,6
-DA:170,3
-DA:171,3
-DA:176,23
-DA:178,27
-DA:179,27
-DA:180,27
-DA:181,27
-DA:182,25
-DA:184,2
-DA:189,27
-DA:190,27
-DA:191,27
-DA:197,15
-DA:198,15
-LF:48
-LH:48
-BRDA:69,0,0,11
-BRDA:69,0,1,1
-BRDA:89,1,0,1
-BRDA:89,1,1,1
-BRDA:108,2,0,13
-BRDA:108,2,1,81
-BRDA:137,3,0,80
-BRDA:137,3,1,57
-BRDA:141,4,0,57
-BRDA:141,4,1,19
-BRDA:143,5,0,42
-BRDA:143,5,1,19
-BRDA:149,6,0,1
-BRDA:149,6,1,56
-BRDA:150,7,0,56
-BRDA:150,7,1,19
-BRDA:152,8,0,45
-BRDA:152,8,1,19
-BRDA:154,9,0,7
-BRDA:154,9,1,50
-BRDA:164,10,0,3
-BRDA:164,10,1,23
-BRDA:165,11,0,26
-BRDA:165,11,1,6
-BRDA:165,11,2,6
-BRDA:186,12,0,1
-BRDA:186,12,1,1
+FNDA:88,(anonymous_3)
+FNDA:21,(anonymous_4)
+FNDA:43,(anonymous_5)
+FNDA:6,(anonymous_6)
+FNDA:71,(anonymous_7)
+FNDA:49,(anonymous_8)
+FNDA:35,(anonymous_9)
+FNDA:39,(anonymous_10)
+FNDA:26,(anonymous_11)
+DA:54,22
+DA:55,22
+DA:56,22
+DA:61,22
+DA:72,12
+DA:75,11
+DA:78,12
+DA:92,2
+DA:93,1
+DA:108,88
+DA:111,88
+DA:112,13
+DA:113,13
+DA:114,13
+DA:117,1
+DA:135,21
+DA:136,43
+DA:142,21
+DA:143,21
+DA:145,6
+DA:146,6
+DA:148,6
+DA:149,6
+DA:150,6
+DA:153,2
+DA:155,6
+DA:156,2
+DA:160,2
+DA:161,2
+DA:162,2
+DA:165,2
+DA:166,2
+DA:167,2
+DA:173,6
+DA:174,6
+DA:175,6
+DA:178,6
+DA:181,15
+DA:183,15
+DA:185,15
+DA:186,22
+DA:187,71
+DA:190,22
+DA:191,49
+DA:192,49
+DA:193,35
+DA:198,22
+DA:199,49
+DA:200,49
+DA:201,39
+DA:203,49
+DA:204,6
+DA:208,6
+DA:209,6
+DA:213,22
+DA:215,26
+DA:216,26
+DA:217,26
+DA:218,26
+DA:219,24
+DA:221,2
+DA:226,26
+DA:227,26
+DA:228,26
+DA:234,15
+DA:235,15
+LF:66
+LH:66
+BRDA:72,0,0,11
+BRDA:72,0,1,1
+BRDA:92,1,0,1
+BRDA:92,1,1,1
+BRDA:111,2,0,13
+BRDA:111,2,1,75
+BRDA:138,3,0,43
+BRDA:138,3,1,21
+BRDA:143,4,0,6
+BRDA:143,4,1,15
+BRDA:150,5,0,2
+BRDA:150,5,1,2
+BRDA:150,5,2,2
+BRDA:187,6,0,71
+BRDA:187,6,1,49
+BRDA:191,7,0,49
+BRDA:191,7,1,18
+BRDA:193,8,0,35
+BRDA:193,8,1,17
+BRDA:199,9,0,49
+BRDA:199,9,1,18
+BRDA:201,10,0,39
+BRDA:201,10,1,18
+BRDA:203,11,0,6
+BRDA:203,11,1,43
+BRDA:223,12,0,1
+BRDA:223,12,1,1
 BRF:27
 BRH:27
 end_of_record

package/dist/TaskGraph.d.ts

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

package/dist/TaskGraph.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=TaskGraph.js.map

package/dist/TaskGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskGraph.js","sourceRoot":"","sources":["../src/TaskGraph.ts"],"names":[],"mappings":""}

package/dist/TaskGraphValidator.d.ts

@@ -0,0 +1,17 @@
+import { ITaskGraphValidator } from "./contracts/ITaskGraphValidator.js";
+import { ValidationResult } from "./contracts/ValidationResult.js";
+import { TaskGraph } from "./TaskGraph.js";
+export declare 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;
+    private detectCycle;
+}

package/dist/TaskGraphValidator.js

@@ -0,0 +1,103 @@
+export class TaskGraphValidator {
+    /**
+     * 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) {
+        const errors = [];
+        // 1. Check for duplicate tasks
+        const taskIds = new Set();
+        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();
+        for (const task of taskGraph.tasks) {
+            adjacencyList.set(task.id, task.dependencies);
+        }
+        const visited = new Set();
+        const recursionStack = new Set();
+        for (const task of taskGraph.tasks) {
+            if (visited.has(task.id)) {
+                continue;
+            }
+            const path = [];
+            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
+        };
+    }
+    detectCycle(taskId, path, visited, recursionStack, adjacencyList) {
+        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;
+    }
+}
+//# sourceMappingURL=TaskGraphValidator.js.map

package/dist/TaskGraphValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskGraphValidator.js","sourceRoot":"","sources":["../src/TaskGraphValidator.ts"],"names":[],"mappings":"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"}

package/dist/TaskRunner.d.ts

@@ -37,6 +37,7 @@ export declare class TaskRunner<TContext> {
     private context;
     private running;
     private listeners;
+    private validator;
     /**
      * @param context The shared context object to be passed to each task.
      */

package/dist/TaskRunner.js

@@ -1,3 +1,4 @@
+import { TaskGraphValidator } from "./TaskGraphValidator.js";
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -7,6 +8,7 @@ export class TaskRunner {
     context;
     running = new Set();
     listeners = {};
+    validator = new TaskGraphValidator();
     /**
      * @param context The shared context object to be passed to each task.
      */
@@ -64,6 +66,48 @@ export class TaskRunner {
      * and values are the corresponding TaskResult objects.
      */
     async execute(steps) {
+        // Validate the task graph before execution
+        const 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();
+            const errorDetails = [];
+            for (const error of validationResult.errors) {
+                errorDetails.push(error.message);
+                switch (error.type) {
+                    case "cycle": {
+                        // details is { cyclePath: string[] }
+                        const path = error.details.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;
+                        affectedTasks.add(d.taskId);
+                        break;
+                    }
+                    case "duplicate_task": {
+                        const d = error.details;
+                        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();
         while (results.size < steps.length) {
@@ -74,8 +118,6 @@ export class TaskRunner {
             });
             // 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");
                 if (failedDep) {
@@ -87,13 +129,6 @@ export class TaskRunner {
                     this.emit("taskSkipped", { step, result });
                 }
             }
-            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);
                 this.emit("taskStart", { step });

package/dist/TaskRunner.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskRunner.js","sourceRoot":"","sources":["../src/TaskRunner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TaskRunner.js","sourceRoot":"","sources":["../src/TaskRunner.ts"],"names":[],"mappings":"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"}

package/dist/contracts/ITaskGraphValidator.d.ts

@@ -0,0 +1,13 @@
+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/dist/contracts/ITaskGraphValidator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ITaskGraphValidator.js.map

package/dist/contracts/ITaskGraphValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITaskGraphValidator.js","sourceRoot":"","sources":["../../src/contracts/ITaskGraphValidator.ts"],"names":[],"mappings":""}

package/dist/contracts/ValidationError.d.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/dist/contracts/ValidationError.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ValidationError.js.map

package/dist/contracts/ValidationError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationError.js","sourceRoot":"","sources":["../../src/contracts/ValidationError.ts"],"names":[],"mappings":""}

package/dist/contracts/ValidationResult.d.ts

@@ -0,0 +1,10 @@
+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/dist/contracts/ValidationResult.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ValidationResult.js.map

package/dist/contracts/ValidationResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationResult.js","sourceRoot":"","sources":["../../src/contracts/ValidationResult.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "",
   "repository": {
     "type": "git",