@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,374 +0,0 @@
1
- // packages/cdd-engine/src-next/face/__tests__/preview.test.ts
2
- // P11 T5 — the `--dry-run` preview pins. Two faces:
3
- //
4
- // · the renderer (face/preview.ts) — the §3.3 five-row block, byte for byte, over
5
- // the four target faces; the `child:` row's detected-host and no-host forms.
6
- // The renderer touches no disk for these (the names are pure path arithmetic),
7
- // so the scene is constructed inline and the env is injected.
8
- // · the CLI face — the preview's zero-write semantics on a real fixture repo
9
- // (`.kairos/` absent, `git status --porcelain` byte-identical, no round
10
- // consumed), the pre-flight refusal face's identity with the real run's, and
11
- // the flag's narrowed scope (exit 2 off the three work verbs).
12
-
13
- import { spawnSync } from "node:child_process";
14
- import {
15
- existsSync,
16
- mkdirSync,
17
- mkdtempSync,
18
- readFileSync,
19
- realpathSync,
20
- rmSync,
21
- writeFileSync,
22
- } from "node:fs";
23
- import { tmpdir } from "node:os";
24
- import path from "node:path";
25
- import { afterEach, describe, expect, it } from "vitest";
26
- import { ConfigLoader } from "../../infra/config.ts";
27
- import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
28
- import { Ledger } from "../../session/ledger.ts";
29
- import type { DispatchOutcome, OpenFrame } from "../../session/run.ts";
30
- import type { CliIo, CliOptions, DispatchScene } from "../cli.ts";
31
- import { Cli } from "../cli.ts";
32
- import { Preview } from "../preview.ts";
33
-
34
- // ---------------------------------------------------------------------------
35
- // the renderer's inline scene (no disk)
36
- // ---------------------------------------------------------------------------
37
-
38
- const ROOT = "/repo";
39
- const WORKSPACE = new Workspace(new WorkspaceRoot(ROOT, ".kairos/cdd"), "p3");
40
-
41
- /** The scene the preview reads — the same DispatchScene shape the lifecycle
42
- * dispatch reads (one scene shape, never a second). */
43
- const scene = (over: Partial<DispatchScene> = {}): DispatchScene => ({
44
- workspace: WORKSPACE,
45
- ledger: new Ledger(WORKSPACE, new ConfigLoader()),
46
- planPath: path.join(ROOT, "docs", "kairos", "plans", "p3.md"),
47
- briefPath: null,
48
- ...over,
49
- });
50
-
51
- /** A frame from the wave-review shape; `over` supplies the face. */
52
- const frame = (over: Partial<OpenFrame> = {}): OpenFrame => ({
53
- type: "wave",
54
- phase: "review",
55
- round: 1,
56
- target: { kind: "wave", tasks: [1] },
57
- params: { tasks: "1", round: 1 },
58
- key: "1",
59
- ...over,
60
- });
61
-
62
- /** A preview over the inline scene with a pinned env — `{}` detects no host, so
63
- * the test process's own markers never leak into the `child:` row. */
64
- const preview = (env: Record<string, string | undefined> = {}): Preview =>
65
- new Preview({ scene: scene(), env });
66
-
67
- describe("Preview — the §3.3 five-row block", () => {
68
- it("renders the wave review block byte for byte", () => {
69
- expect(preview().render("review", frame())).toEqual([
70
- "cdd review: preview (no repo changes)",
71
- " step: review round 1 — wave 1",
72
- " reads: .kairos/cdd/p3/tasks-1-brief.md (would re-render from the current plan)",
73
- " would write: .kairos/cdd/p3/tasks-1-review-1.json · .kairos/cdd/p3/tasks-1-review-1-report.md",
74
- ' would record: progress.waves["1"].rounds.review += [1] · reviewedRevision(brief)',
75
- " child: (no host detected — real run would BLOCK)",
76
- ]);
77
- });
78
-
79
- it("names the work face's full prescribed write set — carrier, report and test evidence", () => {
80
- const lines = preview().render(
81
- "implement",
82
- frame({
83
- phase: "implement",
84
- round: 1,
85
- target: { kind: "wave", tasks: [2, 5] },
86
- params: { tasks: "2,5" },
87
- key: "2,5",
88
- }),
89
- );
90
- expect(lines[1]).toBe(" step: implement round 1 — wave 2,5");
91
- expect(lines[3]).toBe(
92
- " would write: .kairos/cdd/p3/tasks-2,5-implement.json · .kairos/cdd/p3/tasks-2,5-implement-report.md · .kairos/cdd/p3/tasks-2,5-test-evidence.json",
93
- );
94
- // the implement round is never a review: no reviewed-revision write-back leg
95
- expect(lines[4]).toBe(' would record: progress.waves["2,5"].rounds.implement += [1]');
96
- });
97
-
98
- it("renders the spec line — the judged document as the read input, no brief re-render", () => {
99
- const lines = preview().render(
100
- "review",
101
- frame({
102
- type: "spec",
103
- round: 1,
104
- target: { kind: "spec", doc: path.join(ROOT, "docs", "kairos", "specs", "p3-design.md") },
105
- params: { round: 1 },
106
- key: "spec",
107
- }),
108
- );
109
- expect(lines[1]).toBe(" step: review round 1 — spec");
110
- expect(lines[2]).toBe(" reads: docs/kairos/specs/p3-design.md");
111
- expect(lines[3]).toBe(
112
- " would write: .kairos/cdd/p3/spec-review-1.json · .kairos/cdd/p3/spec-review-1-report.md",
113
- );
114
- expect(lines[4]).toBe(
115
- ' would record: progress.waves["spec"].rounds.review += [1] · reviewedRevision(doc)',
116
- );
117
- });
118
-
119
- it("renders the branch line — its review binds no reviewed revision (the live-tree audit)", () => {
120
- const lines = preview().render(
121
- "review",
122
- frame({
123
- type: "branch",
124
- phase: "branch-review",
125
- round: 2,
126
- target: { kind: "branch" },
127
- params: { round: 2 },
128
- key: "branch",
129
- }),
130
- );
131
- expect(lines[1]).toBe(" step: branch-review round 2 — branch");
132
- expect(lines[2]).toBe(" reads: docs/kairos/plans/p3.md");
133
- expect(lines[3]).toBe(
134
- " would write: .kairos/cdd/p3/branch-review-2.json · .kairos/cdd/p3/branch-review-2-report.md",
135
- );
136
- expect(lines[4]).toBe(' would record: progress.waves["branch"].rounds.branch-review += [2]');
137
- });
138
-
139
- it("the child row names the detected host id + the row's invoke string, never the detect marker", () => {
140
- const lines = new Preview({
141
- scene: scene(),
142
- env: { CURSOR_TRACE_ID: "trace" },
143
- }).render("review", frame());
144
- // the leading token is the HOST ID ("cursor"); the harness row's binary name
145
- // (the `cli` column) is a separate fact and never rides this row
146
- expect(lines[5]).toBe(" child: cursor --print --output-format text --force");
147
- });
148
- });
149
-
150
- // ---------------------------------------------------------------------------
151
- // the CLI face (a hermetic fixture repo)
152
- // ---------------------------------------------------------------------------
153
-
154
- /** The captured io — the CLI's stdout/stderr seam (never the process). */
155
- class CaptureIo implements CliIo {
156
- stdoutText = "";
157
- stderrText = "";
158
- stdout(text: string): void {
159
- this.stdoutText += text;
160
- }
161
- stderr(text: string): void {
162
- this.stderrText += text;
163
- }
164
- }
165
-
166
- interface CliFixture {
167
- command: Cli;
168
- io: CaptureIo;
169
- repoRoot: string;
170
- cleanup: () => void;
171
- }
172
-
173
- /** The process cwd before any fixture chdir — restored after every test (the
174
- * engine resolves the repo root from the working directory). */
175
- const ORIGINAL_CWD = process.cwd();
176
- afterEach(() => {
177
- process.chdir(ORIGINAL_CWD);
178
- });
179
-
180
- /** A hermetic CLI fixture — a fresh temp repo, the io captured, the cwd isolated
181
- * into the temp root (taken through `realpathSync`: the engine's git-top-level
182
- * resolution returns the REAL path, so the fixture must speak the same basis). */
183
- const fixture = (opts: CliOptions = {}): CliFixture => {
184
- const repoRoot = realpathSync(mkdtempSync(path.join(tmpdir(), "preview-")));
185
- process.chdir(repoRoot);
186
- const io = new CaptureIo();
187
- const command = Cli.create({ io, ...opts });
188
- return {
189
- command,
190
- io,
191
- repoRoot,
192
- cleanup: () => {
193
- process.chdir(ORIGINAL_CWD);
194
- rmSync(repoRoot, { recursive: true, force: true });
195
- },
196
- };
197
- };
198
-
199
- /** Init a git repo with one commit and a keep-out .gitignore (the dispatch's own
200
- * `.kairos` writes and the fixture's synthetic docs stay out of the tree, so the
201
- * clean-tree pre-flight gate judges the fixture's own edits alone). */
202
- const gitInit = (repoRoot: string): void => {
203
- spawnSync("git", ["init", "-q"], { cwd: repoRoot });
204
- spawnSync("git", ["config", "user.email", "preview@test"], { cwd: repoRoot });
205
- spawnSync("git", ["config", "user.name", "preview-test"], { cwd: repoRoot });
206
- writeFileSync(path.join(repoRoot, ".gitignore"), ".kairos\n/docs/\n", "utf8");
207
- writeFileSync(path.join(repoRoot, "seed.txt"), "seed\n", "utf8");
208
- spawnSync("git", ["add", "-A"], { cwd: repoRoot });
209
- spawnSync("git", ["commit", "-q", "-m", "seed"], { cwd: repoRoot });
210
- };
211
-
212
- /** A one-task plan document — the wave face's dispatch input. */
213
- const planFor = (repoRoot: string): string => {
214
- const file = path.join(repoRoot, "docs", "kairos", "plans", "p3.md");
215
- mkdirSync(path.dirname(file), { recursive: true });
216
- writeFileSync(
217
- file,
218
- [
219
- "---",
220
- "title: Test Plan",
221
- "doc-type: plan",
222
- "version: v1.0",
223
- "date: 2026-10-09",
224
- "spec: docs/kairos/specs/p3-design.md",
225
- "parent-program: docs/kairos/specs/p3-overall.md",
226
- "parent-version: v1.0",
227
- "---",
228
- "",
229
- "## Constraints",
230
- "",
231
- "- delta",
232
- "",
233
- "### Task 1: task 1",
234
- "- **Objective**: objective",
235
- "- **Files**: `a.ts`",
236
- "- **Consumes**: x",
237
- "- **Produces**: y",
238
- "- **Steps**:",
239
- " - step — checkable: green",
240
- "- **Acceptance**: ok",
241
- "- **DependsOn**: none",
242
- "",
243
- ].join("\n"),
244
- "utf8",
245
- );
246
- return file;
247
- };
248
-
249
- const porcelain = (repoRoot: string): string =>
250
- spawnSync("git", ["status", "--porcelain"], { cwd: repoRoot }).stdout.toString();
251
-
252
- const progressPath = (repoRoot: string): string =>
253
- path.join(repoRoot, ".kairos", "cdd", "p3", "progress.json");
254
-
255
- describe("cdd <verb> --dry-run — the read-only preview", () => {
256
- it("writes nothing: `.kairos/` stays absent and the tree is byte-identical", async () => {
257
- const { command, io, repoRoot, cleanup } = fixture();
258
- try {
259
- gitInit(repoRoot);
260
- const plan = planFor(repoRoot);
261
- const before = porcelain(repoRoot);
262
- const code = await command.runArgv([
263
- "implement",
264
- "--tasks",
265
- "1",
266
- "--plan",
267
- plan,
268
- "--dry-run",
269
- ]);
270
- expect(code).toBe(0);
271
- expect(io.stdoutText.startsWith("cdd implement: preview (no repo changes)\n")).toBe(true);
272
- for (const label of ["step:", "reads:", "would write:", "would record:", "child:"])
273
- expect(io.stdoutText).toContain(` ${label} `);
274
- // a preview fabricates no conclusion and no next hop
275
- expect(io.stdoutText).not.toContain("status:");
276
- expect(io.stdoutText).not.toContain("next:");
277
- expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
278
- expect(porcelain(repoRoot)).toBe(before);
279
- } finally {
280
- cleanup();
281
- }
282
- });
283
-
284
- it("consumes no round — the same line's real review still dispatches afterwards", async () => {
285
- const dispatch = async (): Promise<DispatchOutcome> => ({ status: "APPROVED", findings: [] });
286
- const { command, cleanup, repoRoot } = fixture({ dispatch });
287
- try {
288
- gitInit(repoRoot);
289
- const plan = planFor(repoRoot);
290
- expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
291
- // the preview of the next round: no write, no ledger row
292
- expect(
293
- await command.runArgv([
294
- "review",
295
- "--type",
296
- "wave",
297
- "--tasks",
298
- "1",
299
- "--plan",
300
- plan,
301
- "--dry-run",
302
- ]),
303
- ).toBe(0);
304
- expect(existsSync(path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-review-1.json"))).toBe(
305
- false,
306
- );
307
- expect(JSON.parse(readFileSync(progressPath(repoRoot), "utf8")).waves).not.toContainEqual(
308
- expect.objectContaining({ rounds: { implement: [1], review: [1] } }),
309
- );
310
- // the real review of the SAME command dispatches immediately (nothing consumed)
311
- expect(
312
- await command.runArgv(["review", "--type", "wave", "--tasks", "1", "--plan", plan]),
313
- ).toBe(0);
314
- const progress = JSON.parse(readFileSync(progressPath(repoRoot), "utf8")) as {
315
- waves: { wave: string; rounds?: Record<string, number[]> }[];
316
- };
317
- expect(progress.waves.find((row) => row.wave === "1")?.rounds).toEqual({
318
- implement: [1],
319
- review: [1],
320
- });
321
- } finally {
322
- cleanup();
323
- }
324
- });
325
-
326
- it("a refused pre-flight renders the real run's refusal face verbatim and prints no preview", async () => {
327
- const { command, io, repoRoot, cleanup } = fixture();
328
- try {
329
- gitInit(repoRoot);
330
- const plan = planFor(repoRoot);
331
- writeFileSync(path.join(repoRoot, "dirty.txt"), "dirty\n", "utf8");
332
- const argv = ["implement", "--tasks", "1", "--plan", plan];
333
- expect(await command.runArgv([...argv, "--dry-run"])).toBe(1);
334
- const previewStderr = io.stderrText;
335
- expect(io.stdoutText).not.toContain("preview");
336
- io.stdoutText = "";
337
- io.stderrText = "";
338
- expect(await command.runArgv(argv)).toBe(1);
339
- expect(io.stderrText).toBe(previewStderr);
340
- } finally {
341
- cleanup();
342
- }
343
- });
344
-
345
- it("is scoped to the three work verbs — every pure command rejects the flag (exit 2)", async () => {
346
- const { command, io, cleanup } = fixture();
347
- try {
348
- const cases: readonly (readonly string[])[] = [
349
- ["schema", "get", "plan", "--dry-run"],
350
- ["base", "get", "--plan", "docs/x.md", "--dry-run"],
351
- [
352
- "base",
353
- "set",
354
- "--plan",
355
- "docs/x.md",
356
- "--base",
357
- "main",
358
- "--source",
359
- "plan-field",
360
- "--dry-run",
361
- ],
362
- ["issue", "render", "--dry-run"],
363
- ["board", "p3", "--dry-run"],
364
- ];
365
- for (const argv of cases) {
366
- io.stderrText = "";
367
- expect(await command.runArgv([...argv])).toBe(2);
368
- expect(io.stderrText).toContain("--dry-run previews the next dispatch step");
369
- }
370
- } finally {
371
- cleanup();
372
- }
373
- });
374
- });
@@ -1,303 +0,0 @@
1
- // packages/cdd-engine/src-next/face/__tests__/projection.test.ts
2
- // T2 — the CommandTreeBuilder projection suite (spec §2.1/§4): the constructor
3
- // assembles the whole command tree from the declare single surface — the six
4
- // commands + the nested leaves, the binding rules (command keys → .option() /
5
- // .requiredOption() · positionals → .argument() · bool rows single-spelling · the
6
- // program scope merged into every node · the built-in help row un-projected), the
7
- // value-domain validation through the commander pipeline (parseArg →
8
- // commander.invalidArgument · §4.1) and the conditional-required preAction hook
9
- // (REQUIRED_GROUPS · §4.2). Instance-level assertions — the projections are read
10
- // off the assembled program, never a re-declared expectation list.
11
-
12
- import { readFileSync } from "node:fs";
13
- import type { Command } from "commander";
14
- import { describe, expect, it } from "vitest";
15
-
16
- import type { ChannelArgRow } from "../declare.ts";
17
- import { VALUE_SHAPES } from "../declare.ts";
18
- import { CommandTreeBuilder } from "../projection.ts";
19
- import { negatedOf } from "./negation.ts";
20
-
21
- /** The command node of one verb. */
22
- const commandOf = (program: Command, verb: string): Command => {
23
- const node = program.commands.find((command) => command.name() === verb);
24
- expect(node, `the ${verb} command node exists`).toBeDefined();
25
- return node!;
26
- };
27
-
28
- /** The leaf node of one parent command. */
29
- const leafOf = (parent: Command, name: string): Command => {
30
- const node = parent.commands.find((command) => command.name() === name);
31
- expect(node, `the ${name} leaf exists`).toBeDefined();
32
- return node!;
33
- };
34
-
35
- /** The code + message of the commander error `fn` rejects with (the builder's
36
- * program carries the throwing exitOverride — the composed parse rejects, never
37
- * process.exit). */
38
- const commanderError = (fn: () => void): { code: string; message: string } => {
39
- let raw: unknown = null;
40
- try {
41
- fn();
42
- } catch (caught) {
43
- raw = caught;
44
- }
45
- const error = raw as { code?: unknown; message?: unknown };
46
- expect(error, "expected the commander pipeline to reject").toBeTruthy();
47
- expect(typeof error.code, "the rejection carries a commander error code").toBe("string");
48
- return {
49
- code: error.code as string,
50
- message: typeof error.message === "string" ? error.message : "",
51
- };
52
- };
53
-
54
- describe("CommandTreeBuilder — the declaration projection (the constructor is the assembly)", () => {
55
- it("assembles the seven subcommand nodes from the CLI_COMMANDS rows, in the declared order", () => {
56
- const { program } = new CommandTreeBuilder();
57
- expect(program.commands.map((command) => command.name())).toEqual([
58
- "implement",
59
- "review",
60
- "fix",
61
- "base",
62
- "schema",
63
- "issue",
64
- "board",
65
- ]);
66
- });
67
-
68
- it("projects the review surface — every declared key option, --type as a requiredOption", () => {
69
- const { program } = new CommandTreeBuilder();
70
- const review = commandOf(program, "review");
71
- for (const key of ["--type", "--tasks", "--plan", "--spec", "--round"]) {
72
- expect(
73
- review.options.some((option) => option.flags.startsWith(key)),
74
- `review declares ${key}`,
75
- ).toBe(true);
76
- }
77
- // `--root` is retired (T2 · §2.5) — the review node no longer declares it.
78
- expect(review.options.some((option) => option.flags.startsWith("--root"))).toBe(false);
79
- // the branch range flags retired with the commit-sha surface (P7)
80
- expect(review.options.some((option) => option.flags.startsWith("--base"))).toBe(false);
81
- expect(review.options.some((option) => option.flags.startsWith("--head"))).toBe(false);
82
- const typeOption = review.options.find((option) => option.attributeName() === "type");
83
- expect(typeOption?.mandatory, "--type rides .requiredOption()").toBe(true);
84
- const tasksOption = review.options.find((option) => option.attributeName() === "tasks");
85
- expect(tasksOption?.mandatory, "--tasks stays a plain .option()").toBe(false);
86
- });
87
-
88
- it("registers the program scope --dry-run on the program and on every node — the positive spelling only (the negated form is never registered)", () => {
89
- const { program } = new CommandTreeBuilder();
90
- // the retired negated spelling is composed via the shared synthesizer —
91
- // the literal token never appears in the tree (the zero-consumption pin)
92
- expect(program.options.some((option) => option.flags === "--dry-run")).toBe(true);
93
- expect(program.options.some((option) => option.flags === negatedOf("--dry-run"))).toBe(false);
94
- const nodes = [program, ...program.commands, ...program.commands.flatMap((c) => c.commands)];
95
- for (const node of nodes) {
96
- expect(
97
- node.options.some((option) => option.flags === "--dry-run"),
98
- `the ${node.name()} node is usable with --dry-run`,
99
- ).toBe(true);
100
- }
101
- });
102
-
103
- it("never re-registers the built-in -h/--help (the help channel row is not projected)", () => {
104
- const { program } = new CommandTreeBuilder();
105
- const nodes = [program, ...program.commands, ...program.commands.flatMap((c) => c.commands)];
106
- for (const node of nodes) {
107
- for (const option of node.options) {
108
- // The built-in helpOption's flags string — the only spelling that would
109
- // indicate a duplicated help option (the --plan option is not a help flag).
110
- expect(option.flags, `the ${node.name()} node duplicates no help flag`).not.toContain(
111
- "-h, --help",
112
- );
113
- }
114
- }
115
- });
116
-
117
- it("nests base set|get — each leaf holds its own declared keys (set --force, get without)", () => {
118
- const { program } = new CommandTreeBuilder();
119
- const base = commandOf(program, "base");
120
- expect(base.commands.map((command) => command.name())).toEqual(["set", "get"]);
121
- const set = leafOf(base, "set");
122
- const get = leafOf(base, "get");
123
- expect(set.options.some((option) => option.flags.startsWith("--force"))).toBe(true);
124
- expect(get.options.some((option) => option.flags.startsWith("--force"))).toBe(false);
125
- expect(get.options.some((option) => option.flags.startsWith("--plan"))).toBe(true);
126
- // base set's --base carries the branch override domain — the base artifact
127
- // branch name (the "sha" value type retired with the commit-sha surface · P7).
128
- const baseOption = set.options.find((option) => option.flags.startsWith("--base"));
129
- expect(baseOption?.flags).toBe("--base <branch>");
130
- expect(baseOption?.description).toBe("the base branch name (required)");
131
- });
132
-
133
- it("nests schema get and issue render", () => {
134
- const { program } = new CommandTreeBuilder();
135
- const schema = commandOf(program, "schema");
136
- // D19 — the schema leaf set is the single `get` leaf (gen merged into
137
- // `get --output skeleton`); the get leaf holds the `--output` json|skeleton
138
- // option + the conditional `<target>` positional.
139
- expect(schema.commands.map((command) => command.name())).toEqual(["get"]);
140
- const get = leafOf(schema, "get");
141
- expect(get.options.some((option) => option.flags.startsWith("--output"))).toBe(true);
142
- const issue = commandOf(program, "issue");
143
- expect(issue.commands.map((command) => command.name())).toEqual(["render"]);
144
- });
145
-
146
- it("projects the positionals — schema get requires <type>, the <target> rides optional and conditional on the skeleton render", () => {
147
- const { program } = new CommandTreeBuilder();
148
- const schema = commandOf(program, "schema");
149
- const get = leafOf(schema, "get");
150
- expect(get.registeredArguments[0]?.required).toBe(true);
151
- // D19 — the merged leaf's target positional stays optional at parse (the
152
- // conditional-required judgment — only `--output skeleton` demands it — is
153
- // the run body's usage rejection, never a static commander requirement).
154
- expect(get.registeredArguments[1]?.required).toBe(false);
155
- });
156
- });
157
-
158
- describe("the commander pipeline — parseArg value-domain rejection + the normalized value (§4.1)", () => {
159
- it("rejects a non-integer --tasks token with commander.invalidArgument — the domain and the raw value in the message", () => {
160
- const { program } = new CommandTreeBuilder();
161
- const { code, message } = commanderError(() =>
162
- program.parse(["review", "--tasks", "abc"], { from: "user" }),
163
- );
164
- expect(code).toBe("commander.invalidArgument");
165
- expect(message).toContain("--tasks <n|n,n,…>");
166
- expect(message).toContain("abc");
167
- });
168
-
169
- it("normalizes --tasks to the sorted deduped comma string (2,1,1 → 1,2)", () => {
170
- const { program } = new CommandTreeBuilder();
171
- const review = commandOf(program, "review");
172
- program.parse(["review", "--type", "wave", "--tasks", "2,1,1", "--plan", "docs/x.md"], {
173
- from: "user",
174
- });
175
- expect(review.getOptionValue("tasks")).toBe("1,2");
176
- });
177
-
178
- it("rejects an out-of-enum --type and a bogus schema <type>", () => {
179
- const program = new CommandTreeBuilder().program;
180
- expect(
181
- commanderError(() => program.parse(["review", "--type", "bogus"], { from: "user" })).code,
182
- ).toBe("commander.invalidArgument");
183
- expect(
184
- commanderError(() => program.parse(["schema", "get", "bogus"], { from: "user" })).code,
185
- ).toBe("commander.invalidArgument");
186
- });
187
-
188
- it("accepts the schema <type> vocabulary — the phaseSpec alias normalizes, a command word rejects", () => {
189
- const schemaProgram = new CommandTreeBuilder();
190
- const get = leafOf(commandOf(schemaProgram.program, "schema"), "get");
191
- schemaProgram.program.parse(["schema", "get", "phaseSpec"], { from: "user" });
192
- expect(get.processedArgs[0]).toBe("phase-spec");
193
- const rejectedProgram = new CommandTreeBuilder();
194
- expect(() =>
195
- rejectedProgram.program.parse(["schema", "get", "board"], { from: "user" }),
196
- ).toThrow();
197
- });
198
- });
199
-
200
- describe("the preAction conditional-required groups (§4.2 · REQUIRED_GROUPS)", () => {
201
- it("rejects review --type wave without --plan, accepts it with both --plan and --spec (non-exclusive)", () => {
202
- const { program } = new CommandTreeBuilder();
203
- // commander's preAction fires only for commands with an action handler — the
204
- // T3 composition root wires the .action thin shells; the test attaches a
205
- // no-op action to observe the hook the way the root will.
206
- commandOf(program, "review").action(() => undefined);
207
- const { code, message } = commanderError(() =>
208
- program.parse(["review", "--type", "wave"], { from: "user" }),
209
- );
210
- expect(code).toBe("commander.invalidArgument");
211
- expect(message).toContain("--plan required when --type wave");
212
- expect(() =>
213
- program.parse(["review", "--type", "wave", "--plan", "docs/x.md", "--spec", "docs/y.md"], {
214
- from: "user",
215
- }),
216
- ).not.toThrow();
217
- });
218
-
219
- it("rejects fix --type branch without --reviews (the fix branch face)", () => {
220
- const { program } = new CommandTreeBuilder();
221
- commandOf(program, "fix").action(() => undefined);
222
- const { code, message } = commanderError(() =>
223
- program.parse(["fix", "--type", "branch"], { from: "user" }),
224
- );
225
- expect(code).toBe("commander.invalidArgument");
226
- // the branch fix carries both its findings carrier and the --plan workspace
227
- // identity (BranchRef retired — the plan is the branch line's identity · §2.3)
228
- expect(message).toContain("--reviews --plan required when --type branch");
229
- });
230
-
231
- it("rejects review --type branch without --plan (the branch review face)", () => {
232
- const { program } = new CommandTreeBuilder();
233
- commandOf(program, "review").action(() => undefined);
234
- const { code, message } = commanderError(() =>
235
- program.parse(["review", "--type", "branch"], { from: "user" }),
236
- );
237
- expect(code).toBe("commander.invalidArgument");
238
- // the branch review's sole required flag is the --plan workspace identity — the
239
- // commit range is retired (the review judges the live tree · §2.3)
240
- expect(message).toContain("--plan required when --type branch");
241
- });
242
- });
243
-
244
- describe("the value-domain table declaration — VALUE_SHAPES (T7)", () => {
245
- it("the shaped-channel key set — the validated types, and only those (the table-source pin)", () => {
246
- // The value-domain shape derives from the declaration table, never a second
247
- // hand-written list: the key set is exactly the validated subset of the
248
- // channel type vocabulary (string/path/bool faces carry no parser — the
249
- // shaped-channel record face excludes them by construction). The `sha` shape
250
- // retired with the commit-sha surface (P7).
251
- expect(Object.keys(VALUE_SHAPES)).toEqual(["enum", "int-list", "int"]);
252
- for (const key of Object.keys(VALUE_SHAPES)) {
253
- expect(typeof VALUE_SHAPES[key as keyof typeof VALUE_SHAPES].parse).toBe("function");
254
- }
255
- });
256
-
257
- it("the enum domain reads the row's declared values — an out-of-domain raw rejects", () => {
258
- const row: ChannelArgRow = { flag: "--type", type: "enum", values: ["wave", "branch"] };
259
- expect(VALUE_SHAPES.enum.parse("wave", row)).toBe("wave");
260
- const { code, message } = commanderError(() => VALUE_SHAPES.enum.parse("plan", row));
261
- expect(code).toBe("commander.invalidArgument");
262
- expect(message).toBe("must be one of wave | branch");
263
- });
264
-
265
- it("the int-list normalizes to the sorted deduped comma string and rejects non-integers", () => {
266
- const row: ChannelArgRow = { flag: "--tasks", type: "int-list" };
267
- expect(VALUE_SHAPES["int-list"].parse("3,1,3,2", row)).toBe("1,2,3");
268
- const { code, message } = commanderError(() => VALUE_SHAPES["int-list"].parse("1,x", row));
269
- expect(code).toBe("commander.invalidArgument");
270
- expect(message).toBe("--tasks <n|n,n,…> — must be comma-separated integers: x");
271
- });
272
-
273
- it("the int face rejects a non-conforming raw with the pinned byte message", () => {
274
- const intRow: ChannelArgRow = { flag: "--round", type: "int" };
275
- expect(VALUE_SHAPES.int.parse("7", intRow)).toBe("7");
276
- const { code, message } = commanderError(() => VALUE_SHAPES.int.parse("-1", intRow));
277
- expect(code).toBe("commander.invalidArgument");
278
- expect(message).toBe("must be an integer");
279
- });
280
-
281
- it("the hand-written replication is destroyed — the four #parse* methods are gone from the projection (the grep pin)", () => {
282
- const source = readFileSync(new URL("../projection.ts", import.meta.url), "utf8");
283
- for (const method of ["#parseEnum", "#parseInts", "#parseSha8", "#parseInt"] as const) {
284
- expect(
285
- source.includes(method),
286
- `${method} must not survive the table migration (the value-domain rules live in VALUE_SHAPES)`,
287
- ).toBe(false);
288
- }
289
- });
290
-
291
- it("the schema <type> vocabulary is retained — #parseTypeKey + SCHEMA_TYPE_KEYS stay out of the destroy list (T9)", () => {
292
- const projection = readFileSync(new URL("../projection.ts", import.meta.url), "utf8");
293
- const declare = readFileSync(new URL("../declare.ts", import.meta.url), "utf8");
294
- // The retention disposition (plan T7 — the spec §6.3 cross-reference): the pair
295
- // is §6.3-listed but T7 records it as RETAINED, never on the destroy list —
296
- // SCHEMA_TYPE_KEYS is the schema get <type> doc-key vocabulary, orthogonal
297
- // to the ChannelValueType value-shape table (merging it into VALUE_SHAPES does
298
- // not fit); #parseTypeKey derives through it.
299
- expect(projection).toContain("#parseTypeKey");
300
- expect(projection).toContain("SCHEMA_TYPE_KEYS");
301
- expect(declare).toContain("SCHEMA_TYPE_KEYS");
302
- });
303
- });