@oscaner-skills/cdd-engine 3.0.0 → 3.1.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.
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +149 -0
- package/dist/face/cli.js +893 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +702 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +504 -0
- package/dist/face/words.js +258 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +453 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- 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
|
-
}
|