@calmo/task-runner 1.1.0 → 1.2.0

package/.github/workflows/ci.yml

@@ -13,6 +13,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -37,6 +39,11 @@ jobs:
       - name: Test
         run: pnpm test
 
+      - name: SonarQube Scan
+        uses: SonarSource/sonarqube-scan-action@v6
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:

package/CHANGELOG.md

@@ -1,3 +1,45 @@
+## 1.2.0 (2026-01-18)
+
+* Merge branch 'main' into 004-pre-execution-validation-14850747355617832302 ([cc01409](https://github.com/thalesraymond/task-runner/commit/cc01409))
+* Merge branch 'main' into 004-pre-execution-validation-14850747355617832302 ([0a31f84](https://github.com/thalesraymond/task-runner/commit/0a31f84))
+* Merge pull request #25 from thalesraymond/004-pre-execution-validation-14850747355617832302 ([8c022d1](https://github.com/thalesraymond/task-runner/commit/8c022d1)), closes [#25](https://github.com/thalesraymond/task-runner/issues/25)
+* refactor: address PR comments, extract TaskGraph ([f2d506f](https://github.com/thalesraymond/task-runner/commit/f2d506f))
+* refactor: address PR review feedback ([38e7878](https://github.com/thalesraymond/task-runner/commit/38e7878))
+* refactor: split validation contracts into individual files ([c9caea0](https://github.com/thalesraymond/task-runner/commit/c9caea0))
+* feat: pre-validation of task graph for cycles and missing deps ([4680c1b](https://github.com/thalesraymond/task-runner/commit/4680c1b)), closes [#004](https://github.com/thalesraymond/task-runner/issues/004)
+
+## <small>1.1.1 (2026-01-18)</small>
+
+* Merge branch 'main' into chore/configure-sonar-quality-gate-6593988281334866666 ([fe5c88d](https://github.com/thalesraymond/task-runner/commit/fe5c88d))
+* Merge pull request #23 from thalesraymond/004-pre-execution-validation ([bf641c5](https://github.com/thalesraymond/task-runner/commit/bf641c5)), closes [#23](https://github.com/thalesraymond/task-runner/issues/23)
+* Merge pull request #26 from thalesraymond/002-task-cancellation ([30fafaa](https://github.com/thalesraymond/task-runner/commit/30fafaa)), closes [#26](https://github.com/thalesraymond/task-runner/issues/26)
+* Merge pull request #28 from thalesraymond/chore/configure-sonar-quality-gate-6593988281334866666 ([0b7373f](https://github.com/thalesraymond/task-runner/commit/0b7373f)), closes [#28](https://github.com/thalesraymond/task-runner/issues/28)
+* Merge pull request #29 from thalesraymond/update-docs-and-constitution-15453351708375382519 ([84b6293](https://github.com/thalesraymond/task-runner/commit/84b6293)), closes [#29](https://github.com/thalesraymond/task-runner/issues/29)
+* Update GEMINI.md ([64c5660](https://github.com/thalesraymond/task-runner/commit/64c5660))
+* Update GEMINI.md ([e28abbd](https://github.com/thalesraymond/task-runner/commit/e28abbd))
+* Update specs/002-task-cancellation/quickstart.md ([c52ca0d](https://github.com/thalesraymond/task-runner/commit/c52ca0d))
+* Update specs/002-task-cancellation/quickstart.md ([153981a](https://github.com/thalesraymond/task-runner/commit/153981a))
+* Update specs/004-pre-execution-validation/checklists/requirements.md ([e1cd90f](https://github.com/thalesraymond/task-runner/commit/e1cd90f))
+* Update specs/004-pre-execution-validation/checklists/requirements.md ([03869b8](https://github.com/thalesraymond/task-runner/commit/03869b8))
+* Update specs/004-pre-execution-validation/contracts/api.ts ([b217a10](https://github.com/thalesraymond/task-runner/commit/b217a10))
+* Update specs/004-pre-execution-validation/contracts/api.ts ([503309e](https://github.com/thalesraymond/task-runner/commit/503309e))
+* Update specs/004-pre-execution-validation/contracts/api.ts ([6394f0d](https://github.com/thalesraymond/task-runner/commit/6394f0d))
+* Update specs/004-pre-execution-validation/quickstart.md ([4756fbc](https://github.com/thalesraymond/task-runner/commit/4756fbc))
+* Update specs/004-pre-execution-validation/quickstart.md ([9233e8c](https://github.com/thalesraymond/task-runner/commit/9233e8c))
+* Update specs/004-pre-execution-validation/quickstart.md ([1d639d2](https://github.com/thalesraymond/task-runner/commit/1d639d2))
+* Update specs/004-pre-execution-validation/spec.md ([74875de](https://github.com/thalesraymond/task-runner/commit/74875de))
+* Update specs/004-pre-execution-validation/tasks.md ([93ee4a7](https://github.com/thalesraymond/task-runner/commit/93ee4a7))
+* fix: address PR comments on sonar config ([6eab0b5](https://github.com/thalesraymond/task-runner/commit/6eab0b5))
+* fix: address PR comments on sonar config ([156eea0](https://github.com/thalesraymond/task-runner/commit/156eea0))
+* docs: ✏️ fix gemini code review discussion ([a788e47](https://github.com/thalesraymond/task-runner/commit/a788e47))
+* docs: ✏️ fix gemini inconsistent pointed by gemini ([ddc39b7](https://github.com/thalesraymond/task-runner/commit/ddc39b7))
+* docs: ✏️ fix inconsistences pointed in CR ([95acba7](https://github.com/thalesraymond/task-runner/commit/95acba7))
+* docs: ✏️ signal abort spec ([57f1cbf](https://github.com/thalesraymond/task-runner/commit/57f1cbf))
+* docs: ✏️ spec for abort signal ([90340b8](https://github.com/thalesraymond/task-runner/commit/90340b8))
+* docs: ✏️ specs for tree pre validation ([e13f056](https://github.com/thalesraymond/task-runner/commit/e13f056))
+* docs: update constitution and README with latest features ([7b601fc](https://github.com/thalesraymond/task-runner/commit/7b601fc))
+* chore: configure SonarCloud quality gate and coverage ([e08912b](https://github.com/thalesraymond/task-runner/commit/e08912b))
+
 ## 1.1.0 (2026-01-18)
 
 * Merge branch 'main' into feat/task-runner-observer-pattern-15088823676344229252 ([d38d6f8](https://github.com/thalesraymond/task-runner/commit/d38d6f8))

package/GEMINI.md

@@ -3,6 +3,9 @@
 Auto-generated from all feature plans. Last updated: 2026-01-17
 
 ## Active Technologies
+- TypeScript 5.9.3 + vitest 4.0.17 (for testing) (004-pre-execution-validation)
+- TypeScript 5.9.3 + vitest 4.0.17, AbortSignal/AbortController (standard Web APIs) (002-task-cancellation)
+- N/A (in-memory context object) (002-task-cancellation)
 
 - TypeScript 5.9.3 + vitest 4.0.17 (003-refactor-file-structure)
 
@@ -24,10 +27,11 @@ tests/
 : Follow standard conventions
 
 ## Recent Changes
+- 002-task-cancellation: Added TypeScript 5.9.3 + vitest 4.0.17, AbortSignal/AbortController (standard Web APIs)
+- 004-pre-execution-validation: Added TypeScript 5.9.3 + vitest 4.0.17 (for testing)
 
 - 003-refactor-file-structure: Added TypeScript 5.9.3 + vitest 4.0.17
 
-- 001-generic-task-runner: Added
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

package/README.md

@@ -9,6 +9,22 @@ A lightweight, type-safe, and domain-agnostic task orchestration engine. It reso
 - **Parallel Execution**: Automatically identifies and runs independent steps concurrently.
 - **Dependency Management**: Enforces execution order based on dependencies.
 - **Error Handling & Skipping**: robustly handles failures and automatically skips dependent steps.
+- **Event System**: Subscribe to lifecycle events (`workflowStart`, `taskStart`, `taskEnd`, etc.) for logging or monitoring.
+- **Runtime Validation**: Automatically detects circular dependencies and missing dependencies before execution loops.
+
+## Event System
+
+The `TaskRunner` implements an Observer Pattern, allowing you to subscribe to various lifecycle events.
+
+```typescript
+runner.on("taskStart", ({ step }) => {
+  console.log(`Starting step: ${step.name}`);
+});
+
+runner.on("taskEnd", ({ step, result }) => {
+  console.log(`Step ${step.name} finished with status: ${result.status}`);
+});
+```
 
 ## Usage Example
 
@@ -77,6 +93,10 @@ async function main() {
 main();
 ```
 
+## Skip Propagation
+
+If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites, saving resources and preventing cascading errors.
+
 ## Context Hydration
 
 One nice thing to do is to avoid optional parameters and excessive use of ```!``` operator, with task dependencies we can chain our steps and context usages to make sure steps are executed only when pre requisites are met.

package/coverage/TaskGraphValidator.ts.html

@@ -0,0 +1,463 @@
+
+<!doctype html>
+<html lang="en">
+
+<head>
+    <title>Code coverage report for TaskGraphValidator.ts</title>
+    <meta charset="utf-8" />
+    <link rel="stylesheet" href="prettify.css" />
+    <link rel="stylesheet" href="base.css" />
+    <link rel="shortcut icon" type="image/x-icon" href="favicon.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style type='text/css'>
+        .coverage-summary .sorter {
+            background-image: url(sort-arrow-sprite.png);
+        }
+    </style>
+</head>
+    
+<body>
+<div class='wrapper'>
+    <div class='pad1'>
+        <h1><a href="index.html">All files</a> TaskGraphValidator.ts</h1>
+        <div class='clearfix'>
+            
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Statements</span>
+                <span class='fraction'>43/43</span>
+            </div>
+        
+            
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Branches</span>
+                <span class='fraction'>16/16</span>
+            </div>
+        
+            
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Functions</span>
+                <span class='fraction'>3/3</span>
+            </div>
+        
+            
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Lines</span>
+                <span class='fraction'>42/42</span>
+            </div>
+        
+            
+        </div>
+        <p class="quiet">
+            Press <em>n</em> or <em>j</em> to go to the next uncovered block, <em>b</em>, <em>p</em> or <em>k</em> for the previous block.
+        </p>
+        <template id="filterTemplate">
+            <div class="quiet">
+                Filter:
+                <input type="search" id="fileSearch">
+            </div>
+        </template>
+    </div>
+    <div class='status-line high'></div>
+    <pre><table class="coverage">
+<tr><td class="line-count quiet"><a name='L1'></a><a href='#L1'>1</a>
+<a name='L2'></a><a href='#L2'>2</a>
+<a name='L3'></a><a href='#L3'>3</a>
+<a name='L4'></a><a href='#L4'>4</a>
+<a name='L5'></a><a href='#L5'>5</a>
+<a name='L6'></a><a href='#L6'>6</a>
+<a name='L7'></a><a href='#L7'>7</a>
+<a name='L8'></a><a href='#L8'>8</a>
+<a name='L9'></a><a href='#L9'>9</a>
+<a name='L10'></a><a href='#L10'>10</a>
+<a name='L11'></a><a href='#L11'>11</a>
+<a name='L12'></a><a href='#L12'>12</a>
+<a name='L13'></a><a href='#L13'>13</a>
+<a name='L14'></a><a href='#L14'>14</a>
+<a name='L15'></a><a href='#L15'>15</a>
+<a name='L16'></a><a href='#L16'>16</a>
+<a name='L17'></a><a href='#L17'>17</a>
+<a name='L18'></a><a href='#L18'>18</a>
+<a name='L19'></a><a href='#L19'>19</a>
+<a name='L20'></a><a href='#L20'>20</a>
+<a name='L21'></a><a href='#L21'>21</a>
+<a name='L22'></a><a href='#L22'>22</a>
+<a name='L23'></a><a href='#L23'>23</a>
+<a name='L24'></a><a href='#L24'>24</a>
+<a name='L25'></a><a href='#L25'>25</a>
+<a name='L26'></a><a href='#L26'>26</a>
+<a name='L27'></a><a href='#L27'>27</a>
+<a name='L28'></a><a href='#L28'>28</a>
+<a name='L29'></a><a href='#L29'>29</a>
+<a name='L30'></a><a href='#L30'>30</a>
+<a name='L31'></a><a href='#L31'>31</a>
+<a name='L32'></a><a href='#L32'>32</a>
+<a name='L33'></a><a href='#L33'>33</a>
+<a name='L34'></a><a href='#L34'>34</a>
+<a name='L35'></a><a href='#L35'>35</a>
+<a name='L36'></a><a href='#L36'>36</a>
+<a name='L37'></a><a href='#L37'>37</a>
+<a name='L38'></a><a href='#L38'>38</a>
+<a name='L39'></a><a href='#L39'>39</a>
+<a name='L40'></a><a href='#L40'>40</a>
+<a name='L41'></a><a href='#L41'>41</a>
+<a name='L42'></a><a href='#L42'>42</a>
+<a name='L43'></a><a href='#L43'>43</a>
+<a name='L44'></a><a href='#L44'>44</a>
+<a name='L45'></a><a href='#L45'>45</a>
+<a name='L46'></a><a href='#L46'>46</a>
+<a name='L47'></a><a href='#L47'>47</a>
+<a name='L48'></a><a href='#L48'>48</a>
+<a name='L49'></a><a href='#L49'>49</a>
+<a name='L50'></a><a href='#L50'>50</a>
+<a name='L51'></a><a href='#L51'>51</a>
+<a name='L52'></a><a href='#L52'>52</a>
+<a name='L53'></a><a href='#L53'>53</a>
+<a name='L54'></a><a href='#L54'>54</a>
+<a name='L55'></a><a href='#L55'>55</a>
+<a name='L56'></a><a href='#L56'>56</a>
+<a name='L57'></a><a href='#L57'>57</a>
+<a name='L58'></a><a href='#L58'>58</a>
+<a name='L59'></a><a href='#L59'>59</a>
+<a name='L60'></a><a href='#L60'>60</a>
+<a name='L61'></a><a href='#L61'>61</a>
+<a name='L62'></a><a href='#L62'>62</a>
+<a name='L63'></a><a href='#L63'>63</a>
+<a name='L64'></a><a href='#L64'>64</a>
+<a name='L65'></a><a href='#L65'>65</a>
+<a name='L66'></a><a href='#L66'>66</a>
+<a name='L67'></a><a href='#L67'>67</a>
+<a name='L68'></a><a href='#L68'>68</a>
+<a name='L69'></a><a href='#L69'>69</a>
+<a name='L70'></a><a href='#L70'>70</a>
+<a name='L71'></a><a href='#L71'>71</a>
+<a name='L72'></a><a href='#L72'>72</a>
+<a name='L73'></a><a href='#L73'>73</a>
+<a name='L74'></a><a href='#L74'>74</a>
+<a name='L75'></a><a href='#L75'>75</a>
+<a name='L76'></a><a href='#L76'>76</a>
+<a name='L77'></a><a href='#L77'>77</a>
+<a name='L78'></a><a href='#L78'>78</a>
+<a name='L79'></a><a href='#L79'>79</a>
+<a name='L80'></a><a href='#L80'>80</a>
+<a name='L81'></a><a href='#L81'>81</a>
+<a name='L82'></a><a href='#L82'>82</a>
+<a name='L83'></a><a href='#L83'>83</a>
+<a name='L84'></a><a href='#L84'>84</a>
+<a name='L85'></a><a href='#L85'>85</a>
+<a name='L86'></a><a href='#L86'>86</a>
+<a name='L87'></a><a href='#L87'>87</a>
+<a name='L88'></a><a href='#L88'>88</a>
+<a name='L89'></a><a href='#L89'>89</a>
+<a name='L90'></a><a href='#L90'>90</a>
+<a name='L91'></a><a href='#L91'>91</a>
+<a name='L92'></a><a href='#L92'>92</a>
+<a name='L93'></a><a href='#L93'>93</a>
+<a name='L94'></a><a href='#L94'>94</a>
+<a name='L95'></a><a href='#L95'>95</a>
+<a name='L96'></a><a href='#L96'>96</a>
+<a name='L97'></a><a href='#L97'>97</a>
+<a name='L98'></a><a href='#L98'>98</a>
+<a name='L99'></a><a href='#L99'>99</a>
+<a name='L100'></a><a href='#L100'>100</a>
+<a name='L101'></a><a href='#L101'>101</a>
+<a name='L102'></a><a href='#L102'>102</a>
+<a name='L103'></a><a href='#L103'>103</a>
+<a name='L104'></a><a href='#L104'>104</a>
+<a name='L105'></a><a href='#L105'>105</a>
+<a name='L106'></a><a href='#L106'>106</a>
+<a name='L107'></a><a href='#L107'>107</a>
+<a name='L108'></a><a href='#L108'>108</a>
+<a name='L109'></a><a href='#L109'>109</a>
+<a name='L110'></a><a href='#L110'>110</a>
+<a name='L111'></a><a href='#L111'>111</a>
+<a name='L112'></a><a href='#L112'>112</a>
+<a name='L113'></a><a href='#L113'>113</a>
+<a name='L114'></a><a href='#L114'>114</a>
+<a name='L115'></a><a href='#L115'>115</a>
+<a name='L116'></a><a href='#L116'>116</a>
+<a name='L117'></a><a href='#L117'>117</a>
+<a name='L118'></a><a href='#L118'>118</a>
+<a name='L119'></a><a href='#L119'>119</a>
+<a name='L120'></a><a href='#L120'>120</a>
+<a name='L121'></a><a href='#L121'>121</a>
+<a name='L122'></a><a href='#L122'>122</a>
+<a name='L123'></a><a href='#L123'>123</a>
+<a name='L124'></a><a href='#L124'>124</a>
+<a name='L125'></a><a href='#L125'>125</a>
+<a name='L126'></a><a href='#L126'>126</a>
+<a name='L127'></a><a href='#L127'>127</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">29x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">29x</span>
+<span class="cline-any cline-yes">29x</span>
+<span class="cline-any cline-yes">61x</span>
+<span class="cline-any cline-yes">3x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">58x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">29x</span>
+<span class="cline-any cline-yes">61x</span>
+<span class="cline-any cline-yes">41x</span>
+<span class="cline-any cline-yes">5x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">29x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">29x</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">25x</span>
+<span class="cline-any cline-yes">25x</span>
+<span class="cline-any cline-yes">54x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">25x</span>
+<span class="cline-any cline-yes">25x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">25x</span>
+<span class="cline-any cline-yes">49x</span>
+<span class="cline-any cline-yes">3x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">46x</span>
+<span class="cline-any cline-yes">46x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">25x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">51x</span>
+<span class="cline-any cline-yes">51x</span>
+<span class="cline-any cline-yes">51x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">51x</span>
+<span class="cline-any cline-yes">51x</span>
+<span class="cline-any cline-yes">33x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">5x</span>
+<span class="cline-any cline-yes">28x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-yes">4x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">42x</span>
+<span class="cline-any cline-yes">42x</span>
+<span class="cline-any cline-yes">42x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js">import { ITaskGraphValidator } from "./contracts/ITaskGraphValidator.js";
+import { ValidationResult } from "./contracts/ValidationResult.js";
+import { ValidationError } from "./contracts/ValidationError.js";
+import { TaskGraph } from "./TaskGraph.js";
+&nbsp;
+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[] = [];
+&nbsp;
+        // 1. Check for duplicate tasks
+        const taskIds = new Set&lt;string&gt;();
+        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);
+            }
+        }
+&nbsp;
+        // 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 }
+                    });
+                }
+            }
+        }
+&nbsp;
+        // 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 =&gt; e.type === "missing_dependency");
+&nbsp;
+        if (hasMissingDependencies) {
+            return {
+                isValid: errors.length === 0,
+                errors
+            };
+        }
+&nbsp;
+        // Build adjacency list
+        const adjacencyList = new Map&lt;string, string[]&gt;();
+        for (const task of taskGraph.tasks) {
+            adjacencyList.set(task.id, task.dependencies);
+        }
+&nbsp;
+        const visited = new Set&lt;string&gt;();
+        const recursionStack = new Set&lt;string&gt;();
+&nbsp;
+        for (const task of taskGraph.tasks) {
+            if (visited.has(task.id)) {
+                continue;
+            }
+&nbsp;
+            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 -&gt; B -&gt; C -&gt; 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);
+&nbsp;
+                errors.push({
+                    type: "cycle",
+                    message: `Cycle detected: ${cyclePath.join(" -&gt; ")}`,
+                    details: { cyclePath }
+                });
+                // Break after first cycle found to avoid spamming similar errors
+                break;
+            }
+        }
+&nbsp;
+        return {
+            isValid: errors.length === 0,
+            errors
+        };
+    }
+&nbsp;
+    private detectCycle(
+        taskId: string,
+        path: string[],
+        visited: Set&lt;string&gt;,
+        recursionStack: Set&lt;string&gt;,
+        adjacencyList: Map&lt;string, string[]&gt;
+    ): boolean {
+        visited.add(taskId);
+        recursionStack.add(taskId);
+        path.push(taskId);
+&nbsp;
+        const dependencies = adjacencyList.get(taskId)!;
+        for (const dependenceId of dependencies) {
+            if (
+                !visited.has(dependenceId) &amp;&amp;
+                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;
+            }
+        }
+&nbsp;
+        recursionStack.delete(taskId);
+        path.pop();
+        return false;
+    }
+}
+&nbsp;</pre></td></tr></table></pre>
+
+                <div class='push'></div><!-- for sticky footer -->
+            </div><!-- /wrapper -->
+            <div class='footer quiet pad2 space-top1 center small'>
+                Code coverage generated by
+                <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
+                at 2026-01-18T03:56:21.880Z
+            </div>
+        <script src="prettify.js"></script>
+        <script>
+            window.onload = function () {
+                prettyPrint();
+            };
+        </script>
+        <script src="sorter.js"></script>
+        <script src="block-navigation.js"></script>
+    </body>
+</html>
+