@calmo/task-runner 3.4.0 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/.github/dependabot.yml +7 -7
  2. package/.github/workflows/ci.yml +4 -4
  3. package/.jules/backlog_maniac.md +1 -0
  4. package/.jules/nexus.md +1 -0
  5. package/.jules/sentinel.md +1 -0
  6. package/.releaserc.json +2 -7
  7. package/AGENTS.md +21 -16
  8. package/CHANGELOG.md +192 -174
  9. package/README.md +95 -88
  10. package/coverage/coverage-final.json +9 -9
  11. package/coverage/index.html +9 -9
  12. package/coverage/lcov-report/index.html +9 -9
  13. package/coverage/lcov-report/src/EventBus.ts.html +30 -24
  14. package/coverage/lcov-report/src/TaskGraphValidationError.ts.html +12 -3
  15. package/coverage/lcov-report/src/TaskGraphValidator.ts.html +152 -137
  16. package/coverage/lcov-report/src/TaskRunner.ts.html +48 -45
  17. package/coverage/lcov-report/src/TaskRunnerBuilder.ts.html +29 -5
  18. package/coverage/lcov-report/src/TaskRunnerExecutionConfig.ts.html +1 -1
  19. package/coverage/lcov-report/src/TaskStateManager.ts.html +82 -52
  20. package/coverage/lcov-report/src/WorkflowExecutor.ts.html +210 -66
  21. package/coverage/lcov-report/src/contracts/RunnerEvents.ts.html +1 -1
  22. package/coverage/lcov-report/src/contracts/index.html +1 -1
  23. package/coverage/lcov-report/src/index.html +16 -16
  24. package/coverage/lcov-report/src/strategies/DryRunExecutionStrategy.ts.html +4 -4
  25. package/coverage/lcov-report/src/strategies/RetryingExecutionStrategy.ts.html +29 -11
  26. package/coverage/lcov-report/src/strategies/StandardExecutionStrategy.ts.html +7 -7
  27. package/coverage/lcov-report/src/strategies/index.html +1 -1
  28. package/coverage/lcov.info +426 -383
  29. package/coverage/src/EventBus.ts.html +30 -24
  30. package/coverage/src/TaskGraphValidationError.ts.html +12 -3
  31. package/coverage/src/TaskGraphValidator.ts.html +152 -137
  32. package/coverage/src/TaskRunner.ts.html +48 -45
  33. package/coverage/src/TaskRunnerBuilder.ts.html +29 -5
  34. package/coverage/src/TaskRunnerExecutionConfig.ts.html +1 -1
  35. package/coverage/src/TaskStateManager.ts.html +82 -52
  36. package/coverage/src/WorkflowExecutor.ts.html +210 -66
  37. package/coverage/src/contracts/RunnerEvents.ts.html +1 -1
  38. package/coverage/src/contracts/index.html +1 -1
  39. package/coverage/src/index.html +16 -16
  40. package/coverage/src/strategies/DryRunExecutionStrategy.ts.html +4 -4
  41. package/coverage/src/strategies/RetryingExecutionStrategy.ts.html +29 -11
  42. package/coverage/src/strategies/StandardExecutionStrategy.ts.html +7 -7
  43. package/coverage/src/strategies/index.html +1 -1
  44. package/dist/EventBus.js +13 -11
  45. package/dist/EventBus.js.map +1 -1
  46. package/dist/TaskGraphValidationError.js.map +1 -1
  47. package/dist/TaskGraphValidator.js +9 -9
  48. package/dist/TaskGraphValidator.js.map +1 -1
  49. package/dist/TaskRunner.js.map +1 -1
  50. package/dist/TaskRunnerBuilder.js.map +1 -1
  51. package/dist/TaskStateManager.d.ts +6 -0
  52. package/dist/TaskStateManager.js +11 -2
  53. package/dist/TaskStateManager.js.map +1 -1
  54. package/dist/TaskStep.d.ts +5 -0
  55. package/dist/WorkflowExecutor.js +49 -7
  56. package/dist/WorkflowExecutor.js.map +1 -1
  57. package/dist/strategies/RetryingExecutionStrategy.js +3 -1
  58. package/dist/strategies/RetryingExecutionStrategy.js.map +1 -1
  59. package/dist/strategies/StandardExecutionStrategy.js +1 -1
  60. package/dist/strategies/StandardExecutionStrategy.js.map +1 -1
  61. package/openspec/AGENTS.md +81 -15
  62. package/openspec/changes/archive/2026-01-18-add-concurrency-control/proposal.md +7 -4
  63. package/openspec/changes/archive/2026-01-18-add-concurrency-control/tasks.md +1 -0
  64. package/openspec/changes/archive/2026-01-18-add-external-task-cancellation/proposal.md +4 -1
  65. package/openspec/changes/archive/2026-01-18-add-external-task-cancellation/tasks.md +2 -1
  66. package/openspec/changes/archive/2026-01-18-add-integration-tests/proposal.md +3 -0
  67. package/openspec/changes/archive/2026-01-18-add-integration-tests/tasks.md +1 -0
  68. package/openspec/changes/archive/2026-01-18-add-task-retry-policy/proposal.md +3 -0
  69. package/openspec/changes/archive/2026-01-18-add-task-retry-policy/tasks.md +1 -0
  70. package/openspec/changes/archive/2026-01-18-add-workflow-preview/proposal.md +3 -0
  71. package/openspec/changes/archive/2026-01-18-add-workflow-preview/tasks.md +1 -0
  72. package/openspec/changes/archive/2026-01-18-feat-conditional-execution/proposal.md +35 -0
  73. package/openspec/changes/archive/2026-01-18-feat-conditional-execution/tasks.md +32 -0
  74. package/openspec/changes/archive/2026-01-18-refactor-core-architecture/proposal.md +3 -0
  75. package/openspec/changes/archive/2026-01-18-refactor-core-architecture/tasks.md +1 -0
  76. package/openspec/changes/feat-per-task-timeout/proposal.md +11 -6
  77. package/openspec/changes/feat-per-task-timeout/tasks.md +1 -1
  78. package/openspec/project.md +21 -15
  79. package/package.json +2 -1
  80. package/src/EventBus.ts +18 -16
  81. package/src/TaskGraph.ts +8 -8
  82. package/src/TaskGraphValidationError.ts +4 -1
  83. package/src/TaskGraphValidator.ts +148 -143
  84. package/src/TaskRunner.ts +42 -41
  85. package/src/TaskRunnerBuilder.ts +11 -3
  86. package/src/TaskStateManager.ts +12 -2
  87. package/src/TaskStep.ts +6 -0
  88. package/src/WorkflowExecutor.ts +63 -15
  89. package/src/contracts/ITaskGraphValidator.ts +12 -12
  90. package/src/contracts/ValidationError.ts +6 -6
  91. package/src/contracts/ValidationResult.ts +4 -4
  92. package/src/strategies/DryRunExecutionStrategy.ts +3 -3
  93. package/src/strategies/RetryingExecutionStrategy.ts +15 -9
  94. package/src/strategies/StandardExecutionStrategy.ts +4 -4
  95. package/test-report.xml +132 -108
@@ -25,28 +25,28 @@
25
25
  <div class='fl pad1y space-right2'>
26
26
  <span class="strong">100% </span>
27
27
  <span class="quiet">Statements</span>
28
- <span class='fraction'>272/272</span>
28
+ <span class='fraction'>293/293</span>
29
29
  </div>
30
30
 
31
31
 
32
32
  <div class='fl pad1y space-right2'>
33
33
  <span class="strong">100% </span>
34
34
  <span class="quiet">Branches</span>
35
- <span class='fraction'>103/103</span>
35
+ <span class='fraction'>118/118</span>
36
36
  </div>
37
37
 
38
38
 
39
39
  <div class='fl pad1y space-right2'>
40
40
  <span class="strong">100% </span>
41
41
  <span class="quiet">Functions</span>
42
- <span class='fraction'>52/52</span>
42
+ <span class='fraction'>55/55</span>
43
43
  </div>
44
44
 
45
45
 
46
46
  <div class='fl pad1y space-right2'>
47
47
  <span class="strong">100% </span>
48
48
  <span class="quiet">Lines</span>
49
- <span class='fraction'>268/268</span>
49
+ <span class='fraction'>290/290</span>
50
50
  </div>
51
51
 
52
52
 
@@ -84,13 +84,13 @@
84
84
  <div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
85
85
  </td>
86
86
  <td data-value="100" class="pct high">100%</td>
87
- <td data-value="230" class="abs high">230/230</td>
87
+ <td data-value="251" class="abs high">251/251</td>
88
88
  <td data-value="100" class="pct high">100%</td>
89
- <td data-value="78" class="abs high">78/78</td>
89
+ <td data-value="93" class="abs high">93/93</td>
90
90
  <td data-value="100" class="pct high">100%</td>
91
- <td data-value="43" class="abs high">43/43</td>
91
+ <td data-value="46" class="abs high">46/46</td>
92
92
  <td data-value="100" class="pct high">100%</td>
93
- <td data-value="226" class="abs high">226/226</td>
93
+ <td data-value="248" class="abs high">248/248</td>
94
94
  </tr>
95
95
 
96
96
  <tr>
@@ -131,7 +131,7 @@
131
131
  <div class='footer quiet pad2 space-top1 center small'>
132
132
  Code coverage generated by
133
133
  <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
134
- at 2026-01-18T20:19:46.875Z
134
+ at 2026-01-18T23:00:28.563Z
135
135
  </div>
136
136
  <script src="prettify.js"></script>
137
137
  <script>
@@ -25,28 +25,28 @@
25
25
  <div class='fl pad1y space-right2'>
26
26
  <span class="strong">100% </span>
27
27
  <span class="quiet">Statements</span>
28
- <span class='fraction'>272/272</span>
28
+ <span class='fraction'>293/293</span>
29
29
  </div>
30
30
 
31
31
 
32
32
  <div class='fl pad1y space-right2'>
33
33
  <span class="strong">100% </span>
34
34
  <span class="quiet">Branches</span>
35
- <span class='fraction'>103/103</span>
35
+ <span class='fraction'>118/118</span>
36
36
  </div>
37
37
 
38
38
 
39
39
  <div class='fl pad1y space-right2'>
40
40
  <span class="strong">100% </span>
41
41
  <span class="quiet">Functions</span>
42
- <span class='fraction'>52/52</span>
42
+ <span class='fraction'>55/55</span>
43
43
  </div>
44
44
 
45
45
 
46
46
  <div class='fl pad1y space-right2'>
47
47
  <span class="strong">100% </span>
48
48
  <span class="quiet">Lines</span>
49
- <span class='fraction'>268/268</span>
49
+ <span class='fraction'>290/290</span>
50
50
  </div>
51
51
 
52
52
 
@@ -84,13 +84,13 @@
84
84
  <div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
85
85
  </td>
86
86
  <td data-value="100" class="pct high">100%</td>
87
- <td data-value="230" class="abs high">230/230</td>
87
+ <td data-value="251" class="abs high">251/251</td>
88
88
  <td data-value="100" class="pct high">100%</td>
89
- <td data-value="78" class="abs high">78/78</td>
89
+ <td data-value="93" class="abs high">93/93</td>
90
90
  <td data-value="100" class="pct high">100%</td>
91
- <td data-value="43" class="abs high">43/43</td>
91
+ <td data-value="46" class="abs high">46/46</td>
92
92
  <td data-value="100" class="pct high">100%</td>
93
- <td data-value="226" class="abs high">226/226</td>
93
+ <td data-value="248" class="abs high">248/248</td>
94
94
  </tr>
95
95
 
96
96
  <tr>
@@ -131,7 +131,7 @@
131
131
  <div class='footer quiet pad2 space-top1 center small'>
132
132
  Code coverage generated by
133
133
  <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
134
- at 2026-01-18T20:19:46.886Z
134
+ at 2026-01-18T23:00:28.573Z
135
135
  </div>
136
136
  <script src="prettify.js"></script>
137
137
  <script>
@@ -25,7 +25,7 @@
25
25
  <div class='fl pad1y space-right2'>
26
26
  <span class="strong">100% </span>
27
27
  <span class="quiet">Statements</span>
28
- <span class='fraction'>15/15</span>
28
+ <span class='fraction'>16/16</span>
29
29
  </div>
30
30
 
31
31
 
@@ -39,14 +39,14 @@
39
39
  <div class='fl pad1y space-right2'>
40
40
  <span class="strong">100% </span>
41
41
  <span class="quiet">Functions</span>
42
- <span class='fraction'>4/4</span>
42
+ <span class='fraction'>5/5</span>
43
43
  </div>
44
44
 
45
45
 
46
46
  <div class='fl pad1y space-right2'>
47
47
  <span class="strong">100% </span>
48
48
  <span class="quiet">Lines</span>
49
- <span class='fraction'>15/15</span>
49
+ <span class='fraction'>16/16</span>
50
50
  </div>
51
51
 
52
52
 
@@ -147,7 +147,9 @@
147
147
  <a name='L82'></a><a href='#L82'>82</a>
148
148
  <a name='L83'></a><a href='#L83'>83</a>
149
149
  <a name='L84'></a><a href='#L84'>84</a>
150
- <a name='L85'></a><a href='#L85'>85</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
150
+ <a name='L85'></a><a href='#L85'>85</a>
151
+ <a name='L86'></a><a href='#L86'>86</a>
152
+ <a name='L87'></a><a href='#L87'>87</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
151
153
  <span class="cline-any cline-neutral">&nbsp;</span>
152
154
  <span class="cline-any cline-neutral">&nbsp;</span>
153
155
  <span class="cline-any cline-neutral">&nbsp;</span>
@@ -158,7 +160,7 @@
158
160
  <span class="cline-any cline-neutral">&nbsp;</span>
159
161
  <span class="cline-any cline-neutral">&nbsp;</span>
160
162
  <span class="cline-any cline-neutral">&nbsp;</span>
161
- <span class="cline-any cline-yes">63x</span>
163
+ <span class="cline-any cline-yes">74x</span>
162
164
  <span class="cline-any cline-neutral">&nbsp;</span>
163
165
  <span class="cline-any cline-neutral">&nbsp;</span>
164
166
  <span class="cline-any cline-neutral">&nbsp;</span>
@@ -205,10 +207,11 @@
205
207
  <span class="cline-any cline-neutral">&nbsp;</span>
206
208
  <span class="cline-any cline-neutral">&nbsp;</span>
207
209
  <span class="cline-any cline-neutral">&nbsp;</span>
208
- <span class="cline-any cline-yes">342x</span>
210
+ <span class="cline-any cline-yes">378x</span>
209
211
  <span class="cline-any cline-neutral">&nbsp;</span>
210
212
  <span class="cline-any cline-neutral">&nbsp;</span>
211
- <span class="cline-any cline-yes">342x</span>
213
+ <span class="cline-any cline-yes">378x</span>
214
+ <span class="cline-any cline-yes">14x</span>
212
215
  <span class="cline-any cline-yes">14x</span>
213
216
  <span class="cline-any cline-yes">14x</span>
214
217
  <span class="cline-any cline-yes">14x</span>
@@ -231,6 +234,7 @@
231
234
  <span class="cline-any cline-neutral">&nbsp;</span>
232
235
  <span class="cline-any cline-neutral">&nbsp;</span>
233
236
  <span class="cline-any cline-neutral">&nbsp;</span>
237
+ <span class="cline-any cline-neutral">&nbsp;</span>
234
238
  <span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js">import {
235
239
  ListenerMap,
236
240
  RunnerEventListener,
@@ -294,23 +298,25 @@ export class EventBus&lt;TContext&gt; {
294
298
  | undefined;
295
299
  if (listeners) {
296
300
  for (const listener of listeners) {
297
- try {
298
- const result = listener(data);
299
- if (result instanceof Promise) {
300
- result.catch((error) =&gt; {
301
- console.error(
302
- `Error in event listener for ${String(event)}:`,
303
- error
304
- );
305
- });
301
+ Promise.resolve().then(() =&gt; {
302
+ try {
303
+ const result = listener(data);
304
+ if (result instanceof Promise) {
305
+ result.catch((error) =&gt; {
306
+ console.error(
307
+ `Error in event listener for ${String(event)}:`,
308
+ error
309
+ );
310
+ });
311
+ }
312
+ } catch (error) {
313
+ // Prevent listener errors from bubbling up
314
+ console.error(
315
+ `Error in event listener for ${String(event)}:`,
316
+ error
317
+ );
306
318
  }
307
- } catch (error) {
308
- // Prevent listener errors from bubbling up
309
- console.error(
310
- `Error in event listener for ${String(event)}:`,
311
- error
312
- );
313
- }
319
+ });
314
320
  }
315
321
  }
316
322
  }
@@ -322,7 +328,7 @@ export class EventBus&lt;TContext&gt; {
322
328
  <div class='footer quiet pad2 space-top1 center small'>
323
329
  Code coverage generated by
324
330
  <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
325
- at 2026-01-18T20:19:46.886Z
331
+ at 2026-01-18T23:00:28.573Z
326
332
  </div>
327
333
  <script src="../prettify.js"></script>
328
334
  <script>
@@ -75,7 +75,11 @@
75
75
  <a name='L10'></a><a href='#L10'>10</a>
76
76
  <a name='L11'></a><a href='#L11'>11</a>
77
77
  <a name='L12'></a><a href='#L12'>12</a>
78
- <a name='L13'></a><a href='#L13'>13</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
78
+ <a name='L13'></a><a href='#L13'>13</a>
79
+ <a name='L14'></a><a href='#L14'>14</a>
80
+ <a name='L15'></a><a href='#L15'>15</a>
81
+ <a name='L16'></a><a href='#L16'>16</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
82
+ <span class="cline-any cline-neutral">&nbsp;</span>
79
83
  <span class="cline-any cline-neutral">&nbsp;</span>
80
84
  <span class="cline-any cline-neutral">&nbsp;</span>
81
85
  <span class="cline-any cline-neutral">&nbsp;</span>
@@ -83,6 +87,8 @@
83
87
  <span class="cline-any cline-neutral">&nbsp;</span>
84
88
  <span class="cline-any cline-neutral">&nbsp;</span>
85
89
  <span class="cline-any cline-yes">9x</span>
90
+ <span class="cline-any cline-neutral">&nbsp;</span>
91
+ <span class="cline-any cline-neutral">&nbsp;</span>
86
92
  <span class="cline-any cline-yes">9x</span>
87
93
  <span class="cline-any cline-yes">9x</span>
88
94
  <span class="cline-any cline-neutral">&nbsp;</span>
@@ -94,7 +100,10 @@
94
100
  * Contains the validation result with detailed error information.
95
101
  */
96
102
  export class TaskGraphValidationError extends Error {
97
- constructor(public result: ValidationResult, message: string) {
103
+ constructor(
104
+ public result: ValidationResult,
105
+ message: string
106
+ ) {
98
107
  super(message);
99
108
  this.name = "TaskGraphValidationError";
100
109
  }
@@ -106,7 +115,7 @@ export class TaskGraphValidationError extends Error {
106
115
  <div class='footer quiet pad2 space-top1 center small'>
107
116
  Code coverage generated by
108
117
  <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
109
- at 2026-01-18T20:19:46.886Z
118
+ at 2026-01-18T23:00:28.573Z
110
119
  </div>
111
120
  <script src="../prettify.js"></script>
112
121
  <script>
@@ -46,7 +46,7 @@
46
46
  <div class='fl pad1y space-right2'>
47
47
  <span class="strong">100% </span>
48
48
  <span class="quiet">Lines</span>
49
- <span class='fraction'>54/54</span>
49
+ <span class='fraction'>55/55</span>
50
50
  </div>
51
51
 
52
52
 
@@ -226,7 +226,12 @@
226
226
  <a name='L161'></a><a href='#L161'>161</a>
227
227
  <a name='L162'></a><a href='#L162'>162</a>
228
228
  <a name='L163'></a><a href='#L163'>163</a>
229
- <a name='L164'></a><a href='#L164'>164</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
229
+ <a name='L164'></a><a href='#L164'>164</a>
230
+ <a name='L165'></a><a href='#L165'>165</a>
231
+ <a name='L166'></a><a href='#L166'>166</a>
232
+ <a name='L167'></a><a href='#L167'>167</a>
233
+ <a name='L168'></a><a href='#L168'>168</a>
234
+ <a name='L169'></a><a href='#L169'>169</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
230
235
  <span class="cline-any cline-neutral">&nbsp;</span>
231
236
  <span class="cline-any cline-neutral">&nbsp;</span>
232
237
  <span class="cline-any cline-neutral">&nbsp;</span>
@@ -275,6 +280,8 @@
275
280
  <span class="cline-any cline-neutral">&nbsp;</span>
276
281
  <span class="cline-any cline-neutral">&nbsp;</span>
277
282
  <span class="cline-any cline-yes">61x</span>
283
+ <span class="cline-any cline-yes">9x</span>
284
+ <span class="cline-any cline-neutral">&nbsp;</span>
278
285
  <span class="cline-any cline-neutral">&nbsp;</span>
279
286
  <span class="cline-any cline-yes">61x</span>
280
287
  <span class="cline-any cline-yes">6x</span>
@@ -301,6 +308,8 @@
301
308
  <span class="cline-any cline-yes">20139x</span>
302
309
  <span class="cline-any cline-neutral">&nbsp;</span>
303
310
  <span class="cline-any cline-neutral">&nbsp;</span>
311
+ <span class="cline-any cline-neutral">&nbsp;</span>
312
+ <span class="cline-any cline-neutral">&nbsp;</span>
304
313
  <span class="cline-any cline-yes">5x</span>
305
314
  <span class="cline-any cline-yes">5x</span>
306
315
  <span class="cline-any cline-yes">5x</span>
@@ -339,6 +348,7 @@
339
348
  <span class="cline-any cline-neutral">&nbsp;</span>
340
349
  <span class="cline-any cline-neutral">&nbsp;</span>
341
350
  <span class="cline-any cline-neutral">&nbsp;</span>
351
+ <span class="cline-any cline-neutral">&nbsp;</span>
342
352
  <span class="cline-any cline-yes">20139x</span>
343
353
  <span class="cline-any cline-neutral">&nbsp;</span>
344
354
  <span class="cline-any cline-yes">20139x</span>
@@ -395,162 +405,167 @@ import { ValidationError } from "./contracts/ValidationError.js";
395
405
  import { TaskGraph } from "./TaskGraph.js";
396
406
  &nbsp;
397
407
  export class TaskGraphValidator implements ITaskGraphValidator {
398
- /**
399
- * Validates a given task graph for structural integrity.
400
- * Checks for:
401
- * 1. Duplicate task IDs.
402
- * 2. Missing dependencies (tasks that depend on non-existent IDs).
403
- * 3. Circular dependencies (cycles in the graph).
404
- *
405
- * @param taskGraph The task graph to validate.
406
- * @returns A ValidationResult object indicating the outcome of the validation.
407
- */
408
- validate(taskGraph: TaskGraph): ValidationResult {
409
- const errors: ValidationError[] = [];
410
- &nbsp;
411
- // 1. Check for duplicate tasks
412
- const taskIds = new Set&lt;string&gt;();
413
- for (const task of taskGraph.tasks) {
414
- if (taskIds.has(task.id)) {
415
- errors.push({
416
- type: "duplicate_task",
417
- message: `Duplicate task detected with ID: ${task.id}`,
418
- details: { taskId: task.id }
419
- });
420
- } else {
421
- taskIds.add(task.id);
422
- }
423
- }
408
+ /**
409
+ * Validates a given task graph for structural integrity.
410
+ * Checks for:
411
+ * 1. Duplicate task IDs.
412
+ * 2. Missing dependencies (tasks that depend on non-existent IDs).
413
+ * 3. Circular dependencies (cycles in the graph).
414
+ *
415
+ * @param taskGraph The task graph to validate.
416
+ * @returns A ValidationResult object indicating the outcome of the validation.
417
+ */
418
+ validate(taskGraph: TaskGraph): ValidationResult {
419
+ const errors: ValidationError[] = [];
424
420
  &nbsp;
425
- // 2. Check for missing dependencies
426
- for (const task of taskGraph.tasks) {
427
- for (const dependenceId of task.dependencies) {
428
- if (!taskIds.has(dependenceId)) {
429
- errors.push({
430
- type: "missing_dependency",
431
- message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
432
- details: { taskId: task.id, missingDependencyId: dependenceId }
433
- });
434
- }
435
- }
436
- }
437
- &nbsp;
438
- // 3. Check for cycles
439
- // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
440
- const hasMissingDependencies = errors.some(e =&gt; e.type === "missing_dependency");
421
+ // 1. Check for duplicate tasks
422
+ const taskIds = new Set&lt;string&gt;();
423
+ for (const task of taskGraph.tasks) {
424
+ if (taskIds.has(task.id)) {
425
+ errors.push({
426
+ type: "duplicate_task",
427
+ message: `Duplicate task detected with ID: ${task.id}`,
428
+ details: { taskId: task.id },
429
+ });
430
+ } else {
431
+ taskIds.add(task.id);
432
+ }
433
+ }
441
434
  &nbsp;
442
- if (hasMissingDependencies) {
443
- return {
444
- isValid: errors.length === 0,
445
- errors
446
- };
435
+ // 2. Check for missing dependencies
436
+ for (const task of taskGraph.tasks) {
437
+ for (const dependenceId of task.dependencies) {
438
+ if (!taskIds.has(dependenceId)) {
439
+ errors.push({
440
+ type: "missing_dependency",
441
+ message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
442
+ details: { taskId: task.id, missingDependencyId: dependenceId },
443
+ });
447
444
  }
445
+ }
446
+ }
448
447
  &nbsp;
449
- // Build adjacency list
450
- const adjacencyList = new Map&lt;string, string[]&gt;();
451
- for (const task of taskGraph.tasks) {
452
- adjacencyList.set(task.id, task.dependencies);
453
- }
448
+ // 3. Check for cycles
449
+ // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
450
+ const hasMissingDependencies = errors.some(
451
+ (e) =&gt; e.type === "missing_dependency"
452
+ );
454
453
  &nbsp;
455
- const visited = new Set&lt;string&gt;();
456
- const recursionStack = new Set&lt;string&gt;();
454
+ if (hasMissingDependencies) {
455
+ return {
456
+ isValid: errors.length === 0,
457
+ errors,
458
+ };
459
+ }
457
460
  &nbsp;
458
- for (const task of taskGraph.tasks) {
459
- if (visited.has(task.id)) {
460
- continue;
461
- }
461
+ // Build adjacency list
462
+ const adjacencyList = new Map&lt;string, string[]&gt;();
463
+ for (const task of taskGraph.tasks) {
464
+ adjacencyList.set(task.id, task.dependencies);
465
+ }
462
466
  &nbsp;
463
- const path: string[] = [];
464
- if (this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)) {
465
- // Extract the actual cycle from the path
466
- // The path might look like A -&gt; B -&gt; C -&gt; B (if we started at A and found cycle B-C-B)
467
- const cycleStart = path[path.length - 1];
468
- const cycleStartIndex = path.indexOf(cycleStart);
469
- const cyclePath = path.slice(cycleStartIndex);
467
+ const visited = new Set&lt;string&gt;();
468
+ const recursionStack = new Set&lt;string&gt;();
470
469
  &nbsp;
471
- errors.push({
472
- type: "cycle",
473
- message: `Cycle detected: ${cyclePath.join(" -&gt; ")}`,
474
- details: { cyclePath }
475
- });
476
- // Break after first cycle found to avoid spamming similar errors
477
- break;
478
- }
479
- }
470
+ for (const task of taskGraph.tasks) {
471
+ if (visited.has(task.id)) {
472
+ continue;
473
+ }
480
474
  &nbsp;
481
- return {
482
- isValid: errors.length === 0,
483
- errors
484
- };
485
- }
475
+ const path: string[] = [];
476
+ if (
477
+ this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
478
+ ) {
479
+ // Extract the actual cycle from the path
480
+ // The path might look like A -&gt; B -&gt; C -&gt; B (if we started at A and found cycle B-C-B)
481
+ const cycleStart = path[path.length - 1];
482
+ const cycleStartIndex = path.indexOf(cycleStart);
483
+ const cyclePath = path.slice(cycleStartIndex);
486
484
  &nbsp;
487
- /**
488
- * Creates a human-readable error message from a validation result.
489
- * @param result The validation result containing errors.
490
- * @returns A formatted error string.
491
- */
492
- createErrorMessage(result: ValidationResult): string {
493
- const errorDetails = result.errors.map(e =&gt; e.message);
494
- return `Task graph validation failed: ${errorDetails.join("; ")}`;
485
+ errors.push({
486
+ type: "cycle",
487
+ message: `Cycle detected: ${cyclePath.join(" -&gt; ")}`,
488
+ details: { cyclePath },
489
+ });
490
+ // Break after first cycle found to avoid spamming similar errors
491
+ break;
492
+ }
495
493
  }
496
494
  &nbsp;
497
- private detectCycle(
498
- startTaskId: string,
499
- path: string[],
500
- visited: Set&lt;string&gt;,
501
- recursionStack: Set&lt;string&gt;,
502
- adjacencyList: Map&lt;string, string[]&gt;
503
- ): boolean {
504
- // Use an explicit stack to avoid maximum call stack size exceeded errors
505
- const stack: { taskId: string; index: number; dependencies: string[] }[] = [];
495
+ return {
496
+ isValid: errors.length === 0,
497
+ errors,
498
+ };
499
+ }
506
500
  &nbsp;
507
- visited.add(startTaskId);
508
- recursionStack.add(startTaskId);
509
- path.push(startTaskId);
501
+ /**
502
+ * Creates a human-readable error message from a validation result.
503
+ * @param result The validation result containing errors.
504
+ * @returns A formatted error string.
505
+ */
506
+ createErrorMessage(result: ValidationResult): string {
507
+ const errorDetails = result.errors.map((e) =&gt; e.message);
508
+ return `Task graph validation failed: ${errorDetails.join("; ")}`;
509
+ }
510
510
  &nbsp;
511
- stack.push({
512
- taskId: startTaskId,
513
- index: 0,
514
- /* v8 ignore next */
515
- dependencies: adjacencyList.get(startTaskId) ?? []
516
- });
511
+ private detectCycle(
512
+ startTaskId: string,
513
+ path: string[],
514
+ visited: Set&lt;string&gt;,
515
+ recursionStack: Set&lt;string&gt;,
516
+ adjacencyList: Map&lt;string, string[]&gt;
517
+ ): boolean {
518
+ // Use an explicit stack to avoid maximum call stack size exceeded errors
519
+ const stack: { taskId: string; index: number; dependencies: string[] }[] =
520
+ [];
517
521
  &nbsp;
518
- while (stack.length &gt; 0) {
519
- const frame = stack[stack.length - 1];
520
- const { taskId, dependencies } = frame;
522
+ visited.add(startTaskId);
523
+ recursionStack.add(startTaskId);
524
+ path.push(startTaskId);
521
525
  &nbsp;
522
- if (frame.index &lt; dependencies.length) {
523
- const dependenceId = dependencies[frame.index];
524
- frame.index++;
526
+ stack.push({
527
+ taskId: startTaskId,
528
+ index: 0,
529
+ /* v8 ignore next */
530
+ dependencies: adjacencyList.get(startTaskId) ?? [],
531
+ });
525
532
  &nbsp;
526
- if (recursionStack.has(dependenceId)) {
527
- // Cycle detected
528
- path.push(dependenceId);
529
- return true;
530
- }
533
+ while (stack.length &gt; 0) {
534
+ const frame = stack[stack.length - 1];
535
+ const { taskId, dependencies } = frame;
531
536
  &nbsp;
532
- if (!visited.has(dependenceId)) {
533
- visited.add(dependenceId);
534
- recursionStack.add(dependenceId);
535
- path.push(dependenceId);
537
+ if (frame.index &lt; dependencies.length) {
538
+ const dependenceId = dependencies[frame.index];
539
+ frame.index++;
536
540
  &nbsp;
537
- stack.push({
538
- taskId: dependenceId,
539
- index: 0,
540
- /* v8 ignore next */
541
- dependencies: adjacencyList.get(dependenceId) ?? []
542
- });
543
- }
544
- } else {
545
- // Finished all dependencies for this node
546
- recursionStack.delete(taskId);
547
- path.pop();
548
- stack.pop();
549
- }
541
+ if (recursionStack.has(dependenceId)) {
542
+ // Cycle detected
543
+ path.push(dependenceId);
544
+ return true;
550
545
  }
551
546
  &nbsp;
552
- return false;
547
+ if (!visited.has(dependenceId)) {
548
+ visited.add(dependenceId);
549
+ recursionStack.add(dependenceId);
550
+ path.push(dependenceId);
551
+ &nbsp;
552
+ stack.push({
553
+ taskId: dependenceId,
554
+ index: 0,
555
+ /* v8 ignore next */
556
+ dependencies: adjacencyList.get(dependenceId) ?? [],
557
+ });
558
+ }
559
+ } else {
560
+ // Finished all dependencies for this node
561
+ recursionStack.delete(taskId);
562
+ path.pop();
563
+ stack.pop();
564
+ }
553
565
  }
566
+ &nbsp;
567
+ return false;
568
+ }
554
569
  }
555
570
  &nbsp;</pre></td></tr></table></pre>
556
571
 
@@ -559,7 +574,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
559
574
  <div class='footer quiet pad2 space-top1 center small'>
560
575
  Code coverage generated by
561
576
  <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
562
- at 2026-01-18T20:19:46.886Z
577
+ at 2026-01-18T23:00:28.573Z
563
578
  </div>
564
579
  <script src="../prettify.js"></script>
565
580
  <script>