@oscaner-skills/cdd-engine 3.0.0 → 3.0.1

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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,411 +0,0 @@
1
- // packages/cdd-engine/src-next/session/graph.ts
2
- // T6 — the TaskGraph (design spec §3.1): the execution-order single home. The
3
- // graph consumes the SAME doc.ts plan parse instance the dispatch and the lint
4
- // read — the `### Task N:` blocks and their `- **DependsOn**:` fields (the parse
5
- // single home in doc.ts) — and never re-parses the document text. It owns the
6
- // four edge-validation classes (missing-edge / missing-id / self-loop / cycle —
7
- // judged on the NORMALIZED edges: the author's literal is never adjudicated), the
8
- // `batches()` wave decomposition and the `frontier(done)` dynamic face (state.ts's
9
- // Frontier contract). The ExecutionState query surface (doneTasks() / readyBatch()
10
- // as methods — never a standalone state class) is carried here as the run-state
11
- // home (markDone) until the round ledger attests it.
12
- //
13
- // Edge judgment is single-homed here: the four classes are the ONLY edge
14
- // judgments of the new tree — nothing else decides whether an edge is missing,
15
- // dangling, looping or cyclic (the lint reads a block's declared values only to
16
- // know what NOT to suspect, and judges nothing).
17
- //
18
- // Module-level exports are types / the class — zero behavior-carrying bare
19
- // functions (the plan's zero-bare-function discipline).
20
-
21
- import { declaredRegistries } from "../contract/declare.ts";
22
- import type { PlanParsed, TaskBlock } from "../contract/doc.ts";
23
- import type { ReferenceEntry } from "../contract/project.ts";
24
- import { Projector } from "../contract/project.ts";
25
- import type { ExecutionState, Frontier } from "./state.ts";
26
-
27
- /** The four edge-validation classes — the TaskGraph's judgment vocabulary, all
28
- * judged on the NORMALIZED edges (dedupe at the extraction layer + the transitive
29
- * reduction — §3.8 the normalization chain; the author's literal declaration is
30
- * never adjudicated — a repeated declaration is normalized away, T24). */
31
- export type GraphIssueClass =
32
- /** a task block declares no `- **DependsOn**:` field (`none`/empty = the explicit no-dependency declaration) */
33
- | "missing-edge"
34
- /** an edge references a task id absent from the plan */
35
- | "missing-id"
36
- /** a task depends on itself */
37
- | "self-loop"
38
- /** a directed dependency cycle among the edges */
39
- | "cycle";
40
-
41
- /** One edge validation issue — a single failure class bound to an offending task. */
42
- export interface GraphIssue {
43
- /** The failure class. */
44
- kind: GraphIssueClass;
45
- /** The offending task id (for a cycle — the lowest task inside the cycle). */
46
- task: number;
47
- /** The one-line issue message. */
48
- message: string;
49
- /** The actionable fix. */
50
- fix: string;
51
- }
52
-
53
- /** One task's declared edge record — whether the `**DependsOn**` field exists and the dependency ids it carries. */
54
- interface EdgeRecord {
55
- /** Whether the block declares a `- **DependsOn**:` field (absent = the missing-edge class). */
56
- declared: boolean;
57
- /** The dependency ids, DEDUPED at the extraction layer + sorted ascending (the
58
- * author's repeated declaration is normalized away — never adjudicated). */
59
- deps: readonly number[];
60
- }
61
-
62
- /** The task-graph read projection (§3.8) — the task graph + the derived wave chain
63
- * + the done/current/pending view, the single projection the board face and the
64
- * pre-flight gates display. */
65
- export interface TaskGraphReport {
66
- /** Each task's dependency ids IN TRANSITIVE-REDUCED form (the direct-only display
67
- * surface — the graph-view renders this, never the author's declared superset;
68
- * redundant edges are the engine's concern, not the author's). */
69
- edges: Readonly<Record<number, readonly number[]>>;
70
- /** The derived wave chain (`batches()`) — the strict-dispatch grouping authority. */
71
- waves: readonly (readonly number[])[];
72
- /** The completed task ids, ascending. */
73
- done: readonly number[];
74
- /** The first wave holding a not-done task (the in-flight wave); null when all done. */
75
- current: readonly number[] | null;
76
- /** The not-done tasks, ascending (the remaining frontier). */
77
- pending: readonly number[];
78
- }
79
-
80
- /**
81
- * The task graph — nodes are the plan's task ids, one declared edge per block.
82
- * The task-base consumption, the six-class validate, the batch waves and the
83
- * execution query surface all read the same shared parse instance.
84
- */
85
- export class TaskGraph implements Frontier, ExecutionState {
86
- /** The registered task ids, ascending. */
87
- readonly #nodes: readonly number[];
88
- /** Each task's declared edge record, keyed by task id (the AUTHOR's declaration —
89
- * validation reads it; the consumption face is the reduction). */
90
- readonly #edges: ReadonlyMap<number, EdgeRecord>;
91
- /** The direct-only consumption surface — the transitive reduction of the declared
92
- * edges, computed once. EVERY graph consumer (`#depsOf` — batches/frontier/report/
93
- * hasPath) reads the REDUCED form; the closure — the wave basis — is preserved by
94
- * the reduction, so a redundant declaration is inert, never a wave shift. */
95
- readonly #reduced: ReadonlyMap<number, readonly number[]>;
96
- /** The run's completed task ids — the ExecutionState carrier (markDone). */
97
- readonly #done: Set<number> = new Set();
98
- /** The derived `DependsOn id` value pattern (whole-token — the declared-edge
99
- * values; the SAME derived pattern the reference lint reads, so both edge
100
- * consumers share one task-id token domain, never a re-typed literal). */
101
- readonly #depIdToken: RegExp;
102
-
103
- /** Build from a shared plan parse — the same instance the dispatch and the lint read. */
104
- constructor(parsed: PlanParsed) {
105
- this.#depIdToken = new RegExp(
106
- TaskGraph.#valuePatternOf(
107
- new Projector(declaredRegistries).reference().plan.entries,
108
- "DependsOn id",
109
- ),
110
- );
111
- this.#nodes = parsed.taskBlocks.map((block) => block.id).sort((a, b) => a - b);
112
- const edges = new Map<number, EdgeRecord>();
113
- for (const block of parsed.taskBlocks) {
114
- edges.set(block.id, this.#edgeOf(block));
115
- }
116
- this.#edges = edges;
117
- // The direct-only consumption surface — the transitive reduction, computed once
118
- // from the DECLARED edges: every edge (t → d) whose d is already reachable from
119
- // another declared dependency of t is dropped. The author declares the full
120
- // prerequisite set freely; the consumers read the reduced form, and the closure
121
- // (the wave basis) is preserved by the reduction.
122
- const reduced = new Map<number, readonly number[]>();
123
- for (const id of this.#nodes) {
124
- const raw = edges.get(id)?.deps ?? [];
125
- reduced.set(
126
- id,
127
- raw.filter(
128
- (dep) => !raw.some((other) => other !== dep && TaskGraph.#reaches(edges, other, dep)),
129
- ),
130
- );
131
- }
132
- this.#reduced = reduced;
133
- }
134
-
135
- /** Reachability along a RAW edge map (the reduction's closure test — a DFS). */
136
- static #reaches(edges: ReadonlyMap<number, EdgeRecord>, from: number, to: number): boolean {
137
- const seen = new Set<number>();
138
- const stack = [from];
139
- while (stack.length > 0) {
140
- const current = stack.pop()!;
141
- if (current === to) return true;
142
- if (seen.has(current)) continue;
143
- seen.add(current);
144
- stack.push(...(edges.get(current)?.deps ?? []));
145
- }
146
- return false;
147
- }
148
-
149
- // -------------------------------------------------------------------------
150
- // the four-class validate (all judged on the normalized edges)
151
- // -------------------------------------------------------------------------
152
-
153
- /** validate — every failure class of every task, in block order, with the cycle
154
- * class last (the graph-level judgment). The per-block classes read the
155
- * NORMALIZED edge surface (`#depsOf` — the deduped, transitive-reduced form the
156
- * consumers read); the author's literal declaration is never adjudicated. */
157
- validate(): GraphIssue[] {
158
- const issues: GraphIssue[] = [];
159
- const registered = new Set(this.#nodes);
160
- for (const blockId of this.#nodes) {
161
- issues.push(...this.#blockIssues(blockId, registered));
162
- }
163
- const cycleTask = this.#cycleMember();
164
- if (cycleTask !== null) {
165
- issues.push({
166
- kind: "cycle",
167
- task: cycleTask,
168
- message: `a directed dependency cycle closes over task ${cycleTask}: task dependencies must form a DAG`,
169
- fix: "break the cycle — no task may depend on a task that reaches back to it",
170
- });
171
- }
172
- return issues;
173
- }
174
-
175
- /** The per-block failure classes, in a stable order (missing-edge, missing-id,
176
- * self-loop) — judged on the block's NORMALIZED edge (`#depsOf`); a missing
177
- * **DependsOn** field is the missing-edge class, judged before the edges. */
178
- #blockIssues(blockId: number, registered: ReadonlySet<number>): GraphIssue[] {
179
- const edge = this.#edges.get(blockId) ?? { declared: false, deps: [] };
180
- if (!edge.declared) {
181
- return [
182
- this.#issue(
183
- "missing-edge",
184
- blockId,
185
- `task ${blockId} declares no **DependsOn** edge`,
186
- "add a - **DependsOn**: line (`none` = the explicit no-dependency declaration)",
187
- ),
188
- ];
189
- }
190
- const issues: GraphIssue[] = [];
191
- const deps = this.#depsOf(blockId); // the normalized surface (dedupe + reduction)
192
- const missing = TaskGraph.#unique(deps.filter((id) => !registered.has(id)));
193
- if (missing.length > 0) {
194
- issues.push(
195
- this.#issue(
196
- "missing-id",
197
- blockId,
198
- `task ${blockId} depends on unregistered task ${TaskGraph.#toList(missing)}`,
199
- `set **DependsOn** to a task id present in the plan (${TaskGraph.#toList(missing)} is not)`,
200
- ),
201
- );
202
- }
203
- if (deps.includes(blockId)) {
204
- issues.push(
205
- this.#issue(
206
- "self-loop",
207
- blockId,
208
- `task ${blockId} depends on itself`,
209
- `a task may never depend on its own number — drop ${blockId} from the block's **DependsOn**`,
210
- ),
211
- );
212
- }
213
- return issues;
214
- }
215
-
216
- /** The cycle class — the lowest task closing a directed cycle (self-loops
217
- * excluded: they own the self-loop class); null when the edge graph is a DAG.
218
- * Reads the NORMALIZED edge surface (`#depsOf`) — the same face every consumer
219
- * reads; the reduction preserves closure, so a cycle can never be normalized
220
- * away. */
221
- #cycleMember(): number | null {
222
- const indegree = new Map<number, number>();
223
- const dependents = new Map<number, Set<number>>();
224
- for (const id of this.#nodes) {
225
- indegree.set(id, 0);
226
- dependents.set(id, new Set());
227
- }
228
- for (const id of this.#nodes) {
229
- for (const dep of TaskGraph.#unique(this.#depsOf(id).filter((value) => value !== id))) {
230
- if (!indegree.has(dep)) continue; // a phantom can never join a real cycle
231
- indegree.set(id, indegree.get(id)! + 1); // id carries one more dependency
232
- dependents.get(dep)!.add(id); // when dep resolves, id's indegree drops
233
- }
234
- }
235
- const remaining = new Set(this.#nodes);
236
- const queue = this.#nodes.filter((id) => indegree.get(id) === 0);
237
- while (queue.length > 0) {
238
- const id = queue.shift()!;
239
- remaining.delete(id);
240
- for (const dependent of dependents.get(id)!) {
241
- const next = indegree.get(dependent)! - 1;
242
- indegree.set(dependent, next);
243
- if (next === 0) queue.push(dependent);
244
- }
245
- }
246
- return remaining.size === 0 ? null : Math.min(...remaining);
247
- }
248
-
249
- /**
250
- * batches() — the topological wave decomposition: wave 0 is every no-dependency
251
- * task, each later wave the tasks whose dependencies all sit in earlier waves.
252
- * A dependency that can never be satisfied (a phantom target, or a cycle among
253
- * real tasks) keeps its task unwaved — the derivation is halt-safe and never
254
- * recurses.
255
- */
256
- batches(): number[][] {
257
- const waves: number[][] = [];
258
- const done = new Set<number>();
259
- let pending = [...this.#nodes];
260
- while (pending.length > 0) {
261
- const wave = pending.filter((id) => this.#depsOf(id).every((dep) => done.has(dep)));
262
- if (wave.length === 0) break;
263
- waves.push(wave);
264
- for (const id of wave) done.add(id);
265
- pending = pending.filter((id) => !done.has(id));
266
- }
267
- return waves;
268
- }
269
-
270
- // -------------------------------------------------------------------------
271
- // the frontier dynamic face (state.ts Frontier)
272
- // -------------------------------------------------------------------------
273
-
274
- /** frontier(done) — the not-yet-done tasks whose dependencies are all done, ascending. */
275
- frontier(done: ReadonlySet<number>): readonly number[] {
276
- return this.#nodes.filter(
277
- (id) => !done.has(id) && this.#depsOf(id).every((dep) => done.has(dep)),
278
- );
279
- }
280
-
281
- // -------------------------------------------------------------------------
282
- // the ExecutionState query surface (state.ts ExecutionState) + the run carrier
283
- // -------------------------------------------------------------------------
284
-
285
- /** The completed task ids — a snapshot copy, never a live handle into the run. */
286
- doneTasks(): Set<number> {
287
- return new Set(this.#done);
288
- }
289
-
290
- /** The current ready batch — the frontier over the run's done set, ascending. */
291
- readyBatch(): number[] {
292
- return [...this.frontier(this.#done)];
293
- }
294
-
295
- /** Record a completed task — idempotent; an unknown id is a no-op. */
296
- markDone(id: number): void {
297
- if (this.#nodes.includes(id)) this.#done.add(id);
298
- }
299
-
300
- /** The task-graph read projection — the task graph + the derived wave chain +
301
- * the done/current/pending view one method, the board face and the pre-flight
302
- * gates' shared surface (§3.8: one projection, two displays). The edges ride the
303
- * TRANSITIVE REDUCTION (the direct-only display); the waves always derive over
304
- * the declared closure — a redundant declaration is inert, never a wave shift. */
305
- report(done: ReadonlySet<number>): TaskGraphReport {
306
- const edges = this.reduction();
307
- const waves = this.batches();
308
- const first = waves.find((wave) => wave.some((id) => !done.has(id))) ?? null;
309
- return {
310
- edges,
311
- waves,
312
- done: [...done].sort((a, b) => a - b),
313
- current: first,
314
- pending: this.#nodes.filter((id) => !done.has(id)),
315
- };
316
- }
317
-
318
- /** The transitive reduction — the direct-only dependency surface: every edge
319
- * (t → d) whose d is already reachable from ANOTHER declared dependency of t is
320
- * removed. The author declares the full prerequisite set freely (redundancy is
321
- * harmless — the waves derive over the closure); the engine normalizes the
322
- * DISPLAY, never the semantics. */
323
- reduction(): Readonly<Record<number, readonly number[]>> {
324
- const out: Record<number, readonly number[]> = {};
325
- for (const id of this.#nodes) {
326
- const deps = this.#depsOf(id);
327
- out[id] = deps.filter(
328
- (dep) => !deps.some((other) => other !== dep && this.#hasPath(other, dep)),
329
- );
330
- }
331
- return out;
332
- }
333
-
334
- /** Whether `to` is reachable from `from` along the declared edges (a DFS). */
335
- #hasPath(from: number, to: number): boolean {
336
- const seen = new Set<number>();
337
- const stack = [from];
338
- while (stack.length > 0) {
339
- const current = stack.pop()!;
340
- if (current === to) return true;
341
- if (seen.has(current)) continue;
342
- seen.add(current);
343
- stack.push(...this.#depsOf(current));
344
- }
345
- return false;
346
- }
347
-
348
- // -------------------------------------------------------------------------
349
- // edge reading
350
- // -------------------------------------------------------------------------
351
-
352
- /** The dependency ids one task consumes — THE DIRECT-ONLY REDUCTION (§3.8 / direct-only
353
- * engine rule): every consumer (batches / frontier / report / reduction / hasPath)
354
- * reads the reduced form; the author's redundant declarations are inert. */
355
- #depsOf(task: number): readonly number[] {
356
- return this.#reduced.get(task) ?? [];
357
- }
358
-
359
- /** One block's declared edge record — the `**DependsOn**` field's numeric list,
360
- * taken from the field's VALUE PREFIX only (the first `(`/`(` truncates: the
361
- * trailing parenthetical rationale is prose — zero participation, §3.8's value
362
- * domain contract; a round number in the rationale can never become a phantom
363
- * dependency). The extraction layer DEDUPES (a repeated declaration is
364
- * normalized away — the author's literal is never adjudicated, §3.8 the
365
- * normalization chain). `none`/empty carries zero edges; the field's absence is
366
- * recorded separately for the missing-edge class. */
367
- #edgeOf(block: TaskBlock): EdgeRecord {
368
- const field = block.fields.find((entry) => entry.key === "DependsOn");
369
- if (field === undefined) return { declared: false, deps: [] };
370
- const deps: number[] = [];
371
- for (const line of field.lines) {
372
- const prefix = line.split(/[((]/)[0]!;
373
- for (const token of prefix.split(/[,\s]+/)) {
374
- const candidate = token.trim();
375
- if (this.#depIdToken.test(candidate)) deps.push(Number(candidate));
376
- }
377
- }
378
- return { declared: true, deps: [...new Set(deps)].sort((a, b) => a - b) };
379
- }
380
-
381
- /** The value pattern of a registered reference entry — a lookup that fails
382
- * loudly when the declaration renames an anchor the graph consumes (the same
383
- * loud-lookup contract the reference lint's edge scan keeps). */
384
- static #valuePatternOf(entries: readonly ReferenceEntry[], anchor: string): string {
385
- const entry = entries.find((row) => row.anchor === anchor);
386
- if (entry === undefined) {
387
- throw new Error(`task graph requires the registered reference entry "${anchor}"`);
388
- }
389
- return entry.valuePattern ?? "";
390
- }
391
-
392
- /** One constructed issue (the single message/fix assembly point of the graph). */
393
- #issue(kind: GraphIssueClass, task: number, message: string, fix: string): GraphIssue {
394
- return { kind, task, message, fix };
395
- }
396
-
397
- // -------------------------------------------------------------------------
398
- // shared render helpers — pure list/text shaping (class members, never module
399
- // bare functions)
400
- // -------------------------------------------------------------------------
401
-
402
- /** The unique values of a candidate list, in first-occurrence order. */
403
- static #unique(values: readonly number[]): readonly number[] {
404
- return [...new Set(values)];
405
- }
406
-
407
- /** The `1, 2`-style list renderer for the aggregate messages. */
408
- static #toList(values: readonly number[]): string {
409
- return values.join(", ");
410
- }
411
- }