@oscaner-skills/cdd-engine 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -3,9 +3,13 @@
3
3
  // · the four tables of the overall parse as header + data rows;
4
4
  // · the plan's `### Task N:` blocks parse into fields + steps;
5
5
  // · the phase-spec's `## Design` double-layer skeleton parses into groups + items;
6
- // · the cross-doc chain root parses the Class-A/B anchors verbatim (unresolved);
6
+ // · the cross-doc chain root parses the Class-A/B head scalars verbatim (unresolved);
7
7
  // · the DocType class face carries zero judgment methods (spec §2.2 — the machine
8
8
  // assertion surface: extract-only classes).
9
+ // Since T6 the fixtures carry the front-matter head (the §2.2 delivery seam's
10
+ // canonical document form) and every parse runs dual-param — the title face is the
11
+ // head scalar, never the `---` fence line the split consumed, and the chain root
12
+ // reads the head scalars (the `{ target }`-only ChainLink face).
9
13
  // The parse records and known-good document literals are the independent sources of
10
14
  // truth — every assertion compares against the fixture doc the parser must extract.
11
15
 
@@ -13,18 +17,30 @@ import { readFileSync } from "node:fs";
13
17
  import { describe, expect, it } from "vitest";
14
18
  import { SkeletonAssembler } from "../../render/skeleton.ts";
15
19
  import { declaredRegistries } from "../declare.ts";
20
+ import type { DocType, ParsedDoc } from "../doc.ts";
16
21
  import { docTypeParsers, OverallDocType, PhaseSpecDocType, PlanDocType } from "../doc.ts";
22
+ import { FrontMatterExtractor } from "../frontmatter.ts";
23
+ import {
24
+ DesignBodyExtractor,
25
+ GraphExtractor,
26
+ HeadingScanner,
27
+ TableExtractor,
28
+ TaskExtractor,
29
+ } from "../home-extractors.ts";
17
30
  import { Contract } from "../judge.ts";
18
31
  import type { DocKey } from "../project.ts";
19
32
  import { Projector } from "../project.ts";
20
33
 
21
- /** A conforming overall — the four tables, the dependency graph and the header tuple. */
34
+ /** A conforming overall — the front-matter head, the four tables and the graph. */
22
35
  const OVERALL = [
23
- "# 文档架构方法论 v2 — 测试 Overall",
24
- "- **Version**: v1.1 · 2026-10-07",
25
- "- **Status**: Approved",
26
- "- **Author**: [human]",
27
- "- **Constraints**: 全部约定自动生效",
36
+ "---",
37
+ "title: 文档架构方法论 v2 — 测试 Overall",
38
+ "doc-type: overall-spec",
39
+ "version: v1.1",
40
+ "date: 2026-10-07",
41
+ "status: Approved",
42
+ 'author: "[human]"',
43
+ "---",
28
44
  "",
29
45
  "## Document scope",
30
46
  "scope prose",
@@ -73,14 +89,19 @@ const OVERALL = [
73
89
  "| v1.21 | 2026-10-07 | merged change |",
74
90
  ];
75
91
 
76
- /** A conforming plan — the header chain anchors + the `### Task N:` blocks. */
92
+ /** A conforming plan — the front-matter head (Class-A/B chain scalars) + the `### Task N:` blocks. */
77
93
  const PLAN = [
78
- "# 文档架构方法论 v2 — 测试 Plan",
79
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
80
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
81
- "- **Version**: v1.1 · 2026-10-07",
82
- "- **Depends on**: P1 design v1.1",
83
- "- **Base**: develop",
94
+ "---",
95
+ "title: 文档架构方法论 v2 — 测试 Plan",
96
+ "doc-type: plan",
97
+ "version: v1.1",
98
+ "date: 2026-10-07",
99
+ "spec: docs/kairos/specs/x-design.md",
100
+ "parent-program: docs/kairos/specs/x-overall.md",
101
+ "parent-version: v1.21",
102
+ "depends-on: P1 design v1.1",
103
+ "base: develop",
104
+ "---",
84
105
  "",
85
106
  "## Constraints",
86
107
  "",
@@ -108,14 +129,19 @@ const PLAN = [
108
129
  "- **DependsOn**: 1",
109
130
  ];
110
131
 
111
- /** A conforming phase-spec — the header five-tuple + the double-layer design skeleton. */
132
+ /** A conforming phase-spec — the front-matter head (the five-tuple scalars) + the design skeleton. */
112
133
  const PHASE_SPEC = [
113
- "# 文档架构方法论 v2 — 测试 Design Spec",
114
- "- **Version**: v1.2 · 2026-10-07",
115
- "- **Status**: Draft",
116
- "- **Author**: [human]",
117
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
118
- "- **Depends on**: P1(Done)",
134
+ "---",
135
+ "title: 文档架构方法论 v2 — 测试 Design Spec",
136
+ "doc-type: phase-spec",
137
+ "version: v1.2",
138
+ "date: 2026-10-07",
139
+ "status: Draft",
140
+ 'author: "[human]"',
141
+ "parent-program: docs/kairos/specs/x-overall.md",
142
+ "parent-version: v1.21",
143
+ "depends-on: P1(Done)",
144
+ "---",
119
145
  "",
120
146
  "## Design",
121
147
  "",
@@ -139,13 +165,24 @@ const PHASE_SPEC = [
139
165
  "- review note",
140
166
  ];
141
167
 
168
+ /** Parse a known-good literal with its front-matter head — the §2.2 delivery seam
169
+ * the judge's chain-docs producers use (RAW content → fence split → dual-param parse). */
170
+ const parseWithHead = <P extends ParsedDoc>(parser: DocType<P>, doc: readonly string[]): P => {
171
+ const split = FrontMatterExtractor.split(doc.join("\n"));
172
+ return parser.parse(FrontMatterExtractor.lineSplit(split.body), split.head);
173
+ };
174
+
142
175
  describe("OverallDocType.parse — the four tables + the chain root", () => {
143
- const parsed = new OverallDocType("overall-spec").parse(OVERALL);
176
+ const parsed = parseWithHead(new OverallDocType("overall-spec"), OVERALL);
144
177
 
145
- it("parses the header lines and the section skeleton", () => {
178
+ it("parses the front-matter head and the section skeleton", () => {
146
179
  expect(parsed.docType).toBe("overall-spec");
147
- expect(parsed.title).toBe("# 文档架构方法论 v2 — 测试 Overall");
148
- expect(parsed.headerLines.some((line) => line.includes("**Version**"))).toBe(true);
180
+ // the title face is the head scalar — never the `---` fence line
181
+ expect(parsed.title).toBe("文档架构方法论 v2 — 测试 Overall");
182
+ expect(parsed.title).not.toBe("---");
183
+ expect(parsed.head?.docType).toBe("overall-spec");
184
+ expect(parsed.head?.version).toBe("v1.1");
185
+ expect(parsed.head?.status).toBe("Approved");
149
186
  expect(parsed.sections.map((section) => section.heading)).toEqual([
150
187
  "## Document scope",
151
188
  "## File paths",
@@ -202,11 +239,17 @@ describe("OverallDocType.parse — the four tables + the chain root", () => {
202
239
  });
203
240
 
204
241
  describe("PlanDocType.parse — the task blocks + the Class-A/B chain root", () => {
205
- const parsed = new PlanDocType("plan").parse(PLAN);
242
+ const parsed = parseWithHead(new PlanDocType("plan"), PLAN);
206
243
 
207
- it("parses the header lines including the chain anchors", () => {
244
+ it("parses the front-matter head and the section skeleton", () => {
208
245
  expect(parsed.docType).toBe("plan");
209
- expect(parsed.headerLines.some((line) => line.includes("**Spec:**"))).toBe(true);
246
+ // the title face is the head scalar — never the `---` fence line
247
+ expect(parsed.title).toBe("文档架构方法论 v2 — 测试 Plan");
248
+ expect(parsed.title).not.toBe("---");
249
+ expect(parsed.head?.spec).toBe("docs/kairos/specs/x-design.md");
250
+ expect(parsed.head?.parentProgram).toBe("docs/kairos/specs/x-overall.md");
251
+ expect(parsed.head?.parentVersion).toBe("v1.21");
252
+ expect(parsed.head?.dependsOn).toBe("P1 design v1.1");
210
253
  expect(parsed.sections.map((section) => section.heading)).toEqual(["## Constraints"]);
211
254
  });
212
255
 
@@ -229,26 +272,25 @@ describe("PlanDocType.parse — the task blocks + the Class-A/B chain root", ()
229
272
  expect(dependsOn?.lines[0]).toBe("none");
230
273
  });
231
274
 
232
- it("parses the Class-A `**Spec:**` + Class-B `**Parent program**` chain root verbatim", () => {
233
- expect(parsed.chain.specLink).toEqual({
234
- label: "x-design.md",
235
- target: "docs/kairos/specs/x-design.md",
236
- });
237
- expect(parsed.chain.parentLink).toEqual({
238
- label: "x-overall.md v1.21",
239
- target: "docs/kairos/specs/x-overall.md",
240
- });
275
+ it("parses the Class-A `spec:` + Class-B `parent-program:` chain root from the head scalars", () => {
276
+ expect(parsed.chain.specLink).toEqual({ target: "docs/kairos/specs/x-design.md" });
277
+ expect(parsed.chain.parentLink).toEqual({ target: "docs/kairos/specs/x-overall.md" });
241
278
  expect(parsed.chain.parentTokens).toEqual(["v1.21"]);
242
279
  expect(parsed.chain.dependsOn).toBe("P1 design v1.1");
243
280
  });
244
281
  });
245
282
 
246
283
  describe("PhaseSpecDocType.parse — the design skeleton + the Class-B chain root", () => {
247
- const parsed = new PhaseSpecDocType("phase-spec").parse(PHASE_SPEC);
284
+ const parsed = parseWithHead(new PhaseSpecDocType("phase-spec"), PHASE_SPEC);
248
285
 
249
- it("parses the header five-tuple surface", () => {
286
+ it("parses the front-matter head (the five-tuple scalars) and the section skeleton", () => {
250
287
  expect(parsed.docType).toBe("phase-spec");
251
- expect(parsed.headerLines.some((line) => line.includes("**Parent program**"))).toBe(true);
288
+ // the title face is the head scalar — never the `---` fence line
289
+ expect(parsed.title).toBe("文档架构方法论 v2 — 测试 Design Spec");
290
+ expect(parsed.title).not.toBe("---");
291
+ expect(parsed.head?.status).toBe("Draft");
292
+ expect(parsed.head?.parentProgram).toBe("docs/kairos/specs/x-overall.md");
293
+ expect(parsed.head?.parentVersion).toBe("v1.21");
252
294
  expect(parsed.sections.map((section) => section.heading)).toEqual([
253
295
  "## Design",
254
296
  "## Constraints",
@@ -266,13 +308,140 @@ describe("PhaseSpecDocType.parse — the design skeleton + the Class-B chain roo
266
308
  expect(parsed.design.some((group) => group.heading.startsWith("Acceptance"))).toBe(false);
267
309
  });
268
310
 
269
- it("parses the Class-B chain root — parent link + version tokens", () => {
270
- expect(parsed.chain.parentLink).toEqual({
271
- label: "x-overall.md v1.21",
272
- target: "docs/kairos/specs/x-overall.md",
273
- });
311
+ it("parses the Class-B chain root — parent link + version tokens from the head scalars", () => {
312
+ expect(parsed.chain.parentLink).toEqual({ target: "docs/kairos/specs/x-overall.md" });
274
313
  expect(parsed.chain.parentTokens).toEqual(["v1.21"]);
275
314
  expect(parsed.chain.specLink).toBeNull();
315
+ expect(parsed.chain.dependsOn).toBe("P1(Done)");
316
+ });
317
+ });
318
+
319
+ describe("the home-driven extractors (T3 · spec §3.2) — the fixed structure rules over the registry's anchors", () => {
320
+ it("TaskExtractor — block heads + aligned id tokens + the scoped field/step occurrences", () => {
321
+ const extracted = new TaskExtractor().extract(declaredRegistries.plan, PLAN);
322
+ expect(extracted["### Task N:"]).toEqual(["### Task 1: skeleton", "### Task 2: registry"]);
323
+ expect(extracted["Task id token"]).toEqual(["1", "2"]);
324
+ expect(extracted["**Objective**"]).toEqual([
325
+ "- **Objective**: establish the skeleton",
326
+ "- **Objective**: declare the registries",
327
+ ]);
328
+ expect(extracted["**DependsOn**"]).toEqual(["- **DependsOn**: none", "- **DependsOn**: 1"]);
329
+ // the step bullets are scoped to the `**Steps**` field and matched on the
330
+ // trimmed form — the header / constraint bullets never leak in
331
+ expect(extracted["Step action"]).toEqual([
332
+ " - step one",
333
+ " - step two — checkable: second step check",
334
+ " - write the registry — checkable: types compile",
335
+ ]);
336
+ expect(extracted["Step checkable"]).toEqual([
337
+ " - step two — checkable: second step check",
338
+ " - write the registry — checkable: types compile",
339
+ ]);
340
+ // the front-matter head scalars never become line occurrences of a body anchor
341
+ expect(extracted["spec"]).toBeUndefined();
342
+ expect(extracted["parent-program"]).toBeUndefined();
343
+ });
344
+
345
+ it("DesignBodyExtractor — the numbered group/item headings and the design leaves", () => {
346
+ const extracted = new DesignBodyExtractor().extract(
347
+ declaredRegistries["phase-spec"],
348
+ PHASE_SPEC,
349
+ );
350
+ expect(extracted["## Design"]).toEqual(["## Design"]);
351
+ expect(extracted["### N. group heading"]).toEqual(["### 1. 判定面", "### 2. 编排面"]);
352
+ expect(extracted["#### N.M item heading"]).toEqual(["#### 1.1 策略类族", "#### 2.1 波次"]);
353
+ expect(extracted["### Acceptance criteria"]).toEqual(["### Acceptance criteria"]);
354
+ expect(new DesignBodyExtractor().groupOf("### 1. 判定面")).toEqual({
355
+ number: "1",
356
+ heading: "判定面",
357
+ });
358
+ expect(new DesignBodyExtractor().itemOf("#### 2.1 波次")).toEqual({
359
+ number: "2.1",
360
+ heading: "波次",
361
+ });
362
+ });
363
+
364
+ it("GraphExtractor — the declared graph edge lines on their trimmed form", () => {
365
+ const sections = new OverallDocType("overall-spec").parse(OVERALL).sections;
366
+ const graphSection = sections.find((section) =>
367
+ section.heading.startsWith("## Dependency graph"),
368
+ );
369
+ expect(graphSection).toBeDefined();
370
+ const extracted = new GraphExtractor().extract(declaredRegistries["overall-spec"], [
371
+ ...(graphSection?.lines ?? []),
372
+ ]);
373
+ expect(extracted["Hard edge"]).toEqual(["P1 -> P2"]);
374
+ expect(extracted["Graph legend"]).toEqual(["-> = hard block"]);
375
+ expect(extracted["Soft edge"]).toBeUndefined();
376
+ });
377
+
378
+ it("TableExtractor — the declared column-header and data rows", () => {
379
+ const extracted = new TableExtractor().extract(declaredRegistries["overall-spec"], [
380
+ "| Phase | Issue (ref) | Title summary |",
381
+ "| --- | --- | --- |",
382
+ "| P1 | #123 | issue one |",
383
+ ]);
384
+ expect(extracted["Issue inventory columns"]).toEqual([
385
+ "| Phase | Issue (ref) | Title summary |",
386
+ ]);
387
+ expect(extracted["Issue row"]).toEqual(["| P1 | #123 | issue one |"]);
388
+ // the separator row never matches a data anchor
389
+ expect(extracted["Change history row"]).toBeUndefined();
390
+ });
391
+
392
+ it("HeadingScanner — the registered section/facet headings by their declared rank", () => {
393
+ const extracted = new HeadingScanner().extract(declaredRegistries["overall-spec"], OVERALL);
394
+ expect(extracted["## Document scope"]).toEqual(["## Document scope"]);
395
+ expect(extracted["### Goal"]).toEqual(["### Goal"]);
396
+ expect(extracted["### Non-goals"]).toEqual(["### Non-goals"]);
397
+ });
398
+
399
+ it("HeadingScanner.sectionsOf — the declared rank-2 sections in document order, an undeclared heading excluded", () => {
400
+ const scanner = new HeadingScanner();
401
+ const sections = scanner.sectionsOf(declaredRegistries["overall-spec"], [
402
+ "## Document scope",
403
+ "scope prose",
404
+ "## Review Focus",
405
+ "undeclared prose",
406
+ "## Change history",
407
+ "| v1.1 |",
408
+ ]);
409
+ // the undeclared rank-2 heading is not a section (and does not swallow the
410
+ // declared section that follows it)
411
+ expect(sections.map((section) => section.heading)).toEqual([
412
+ "## Document scope",
413
+ "## Change history",
414
+ ]);
415
+ expect(sections[0].lines).toEqual(["scope prose"]);
416
+ // the phase-spec's conditional `## Review record` is a declared section surface
417
+ const phaseSections = scanner.sectionsOf(declaredRegistries["phase-spec"], [
418
+ "## Design",
419
+ "## Review record",
420
+ "- note",
421
+ ]);
422
+ expect(phaseSections.map((section) => section.heading)).toEqual([
423
+ "## Design",
424
+ "## Review record",
425
+ ]);
426
+ });
427
+
428
+ it("TableExtractor.tableLinesOf / headerLineOf — the table rows and the registry-declared header row", () => {
429
+ const extractor = new TableExtractor();
430
+ const lines = [
431
+ "prose line",
432
+ "| Phase | Issue (ref) | Title summary |",
433
+ "| --- | --- | --- |",
434
+ "| P1 | #123 | issue one |",
435
+ ];
436
+ expect(extractor.tableLinesOf(lines)).toEqual([
437
+ "| Phase | Issue (ref) | Title summary |",
438
+ "| P1 | #123 | issue one |",
439
+ ]);
440
+ expect(extractor.headerLineOf(declaredRegistries["overall-spec"], lines)).toBe(
441
+ "| Phase | Issue (ref) | Title summary |",
442
+ );
443
+ // a table whose declared column anchor is absent has no declared header
444
+ expect(extractor.headerLineOf(declaredRegistries["overall-spec"], ["| a | b |"])).toBeNull();
276
445
  });
277
446
  });
278
447
 
@@ -0,0 +1,58 @@
1
+ // packages/cdd-engine/src-next/contract/__tests__/dockey.guard.test.ts
2
+ // T11 (spec §3.2 ③) — the DocKey single-source gate. The four doc-type keys were
3
+ // hand-copied across the tree (project.ts declaration · judge.ts DOC_KEYS ·
4
+ // declare.ts DOC_TYPE_VALUES · board-view.ts DOC_TYPE_DOMAIN · doc.ts inline
5
+ // unions); this gate asserts every runtime array and type surface over the domain
6
+ // derives from the ONE declaration (declare.ts DOC_TYPE_VALUES, re-exported by
7
+ // project.ts as DOC_KEYS + aliased as DocKey). A drifted second list — a member
8
+ // dropped or added anywhere — fails here, never silently.
9
+
10
+ import { readFileSync } from "node:fs";
11
+ import { fileURLToPath } from "node:url";
12
+ import { describe, expect, it } from "vitest";
13
+ import { DOC_TYPE_VALUES } from "../declare.ts";
14
+ import { DOC_KEYS } from "../project.ts";
15
+
16
+ /** The canonical value domain — the ONE declaration (declare.ts). */
17
+ const CANONICAL = ["overall-spec", "plan", "phase-spec", "single-spec"];
18
+
19
+ describe("DocKey single-source derivation (spec §3.2 ③)", () => {
20
+ it("the canonical declaration carries the four keys in order", () => {
21
+ expect([...DOC_TYPE_VALUES]).toEqual(CANONICAL);
22
+ });
23
+
24
+ it("project.ts re-exports the SAME tuple as DOC_KEYS — one array, zero copy", () => {
25
+ // The re-export is the same runtime array instance, never a re-typed literal.
26
+ expect(DOC_KEYS).toBe(DOC_TYPE_VALUES);
27
+ expect([...DOC_KEYS]).toEqual(CANONICAL);
28
+ });
29
+
30
+ it("the judge + declare + board-view consumers derive from the single source (zero re-typed literal)", () => {
31
+ const contractRoot = fileURLToPath(new URL("..", import.meta.url));
32
+ // A hand-written four-key literal array is the drift form this gate bans: the
33
+ // three consumers must never carry their own copy.
34
+ const files = ["judge.ts", "declare.ts", "../face/board-view.ts"].map((rel) =>
35
+ readFileSync(`${contractRoot}/${rel}`, "utf8"),
36
+ );
37
+ for (const [index, src] of files.entries()) {
38
+ // The literal "[ \"overall-spec\", ... ]" re-typed in a consumer is the drift
39
+ // signature; the canonical declare.ts keeps its ONE declaration and the two
40
+ // consumers must not carry a second literal array.
41
+ const literalArrays = src.match(/"overall-spec"\s*,\s*"plan"\s*,\s*"phase-spec"/g) ?? [];
42
+ if (index === 1) {
43
+ // declare.ts is the declaration root — its one literal is the single source.
44
+ expect(literalArrays.length).toBeLessThanOrEqual(1);
45
+ } else {
46
+ expect(literalArrays, `${files.length}`).toEqual([]);
47
+ }
48
+ }
49
+ });
50
+
51
+ it("doc.ts carries zero inline doc-key union — the two surfaces alias DocKey", () => {
52
+ const docSrc = readFileSync(fileURLToPath(new URL("../doc.ts", import.meta.url)), "utf8");
53
+ // The collapsed inline unions read `DocKey`; a re-typed four-member union in
54
+ // doc.ts is the drift this gate bans.
55
+ const inlineUnion = docSrc.match(/docType\w*:\s*"overall-spec"\s*\|\s*"plan"/g) ?? [];
56
+ expect(inlineUnion).toEqual([]);
57
+ });
58
+ });
@@ -0,0 +1,81 @@
1
+ // packages/cdd-engine/src-next/contract/__tests__/edge-conditions.guard.test.ts
2
+ // T13 ④ (spec §3.3 ④) — the edgeConditionWords real-derivation gate. The contract's
3
+ // `edgeConditionWords` docstring claimed a wording test pinned its derivation from the
4
+ // engine word table / Route lexicon, but the array had ZERO reader (a false pin: the
5
+ // declared value could drift from the engine sources silently). This gate IS that pin:
6
+ // it derives the expected set by family concatenation from the engine's OWN single
7
+ // sources and asserts the declared contract value equals it —
8
+ // · the NEXT-LOOP phrases — the contract's own `digraph.nextLoopConditions`
9
+ // (the contract IS the authoritative home for this one family: the phrases are
10
+ // the SKILL-digraph edge-label vocabulary, a consumer-surface prose face the
11
+ // runtime `next:` never emits, so no engine runtime constant carries them — see
12
+ // the contract slot's docstring · P9 branch-review-1 F9);
13
+ // · the review-closure status words — `CAPSULE_WORDS.status` (face/words.ts) minus
14
+ // the failure statuses `FAILED_STATUS` (session/next.ts), cross-checked against the
15
+ // `RoundStatus` union (session/ledger.ts — the status type's single home);
16
+ // · the Route decision words — `ROUTE_DECISION_WORDS` (session/next.ts, the Route
17
+ // lexicon's single home).
18
+ // A drifted engine word re-projects the expected set and fails here — never a silent
19
+ // second list. Domicile: engine suite (§3.6 — the engine-internal ④ fact).
20
+
21
+ import { readFileSync } from "node:fs";
22
+ import { fileURLToPath } from "node:url";
23
+ import { describe, expect, it } from "vitest";
24
+
25
+ import { CAPSULE_WORDS } from "../../face/words.ts";
26
+ import { FAILED_STATUS, ROUTE_DECISION_WORDS } from "../../session/next.ts";
27
+ import { SKILL_ANATOMY } from "../skill-anatomy.ts";
28
+
29
+ const SRC = fileURLToPath(new URL("../../", import.meta.url));
30
+
31
+ /** The `RoundStatus` union members declared in session/ledger.ts — the status type's
32
+ * single home (parsed from the source: a string-literal union carries no runtime face). */
33
+ const roundStatusMembers = (): string[] => {
34
+ const src = readFileSync(`${SRC}/session/ledger.ts`, "utf8");
35
+ const match = /export type RoundStatus =([^;]+);/.exec(src);
36
+ if (match === null) throw new Error("ledger.ts RoundStatus shape changed");
37
+ return [...(match[1] ?? "").matchAll(/"([^"]+)"/g)].map((m) => m[1]!);
38
+ };
39
+
40
+ /** The expected engine-lexicon condition set — derived by family concatenation from
41
+ * the engine's own single sources (the contract's loop conditions + the word table's
42
+ * non-failure status vocabulary + the router's Route decision lexicon). */
43
+ const deriveExpected = (): string[] => [
44
+ ...SKILL_ANATOMY.digraph.nextLoopConditions,
45
+ ...CAPSULE_WORDS.status.filter((status) => !FAILED_STATUS.has(status)),
46
+ ...ROUTE_DECISION_WORDS,
47
+ ];
48
+
49
+ describe("edgeConditionWords — the real derivation pin (spec §3.3 ④)", () => {
50
+ it("equals the family-concatenation derivation from words.ts + next.ts + the contract's loop conditions", () => {
51
+ expect([...SKILL_ANATOMY.edgeConditionWords]).toEqual(deriveExpected());
52
+ });
53
+
54
+ it("carries the three families and no re-typed drift — the set is exactly loop + status + route words", () => {
55
+ const derived = deriveExpected();
56
+ // Each family contributes at least one word (a dropped family is a finding).
57
+ expect(SKILL_ANATOMY.digraph.nextLoopConditions.length).toBeGreaterThan(0);
58
+ expect(ROUTE_DECISION_WORDS.length).toBeGreaterThan(0);
59
+ expect(CAPSULE_WORDS.status.filter((s) => !FAILED_STATUS.has(s)).length).toBeGreaterThan(0);
60
+ expect(SKILL_ANATOMY.edgeConditionWords.length).toBe(derived.length);
61
+ // The failure statuses are excluded (a BLOCKED/TIMEOUT round carries no closure edge).
62
+ for (const failed of FAILED_STATUS) {
63
+ expect(SKILL_ANATOMY.edgeConditionWords).not.toContain(failed);
64
+ }
65
+ });
66
+
67
+ it("the closure status words derive from the RoundStatus union (ledger.ts — the status type's single home)", () => {
68
+ const members = roundStatusMembers();
69
+ const closure = CAPSULE_WORDS.status.filter((status) => !FAILED_STATUS.has(status));
70
+ // Every closure status word is a declared RoundStatus member; the word table's
71
+ // status vocabulary stays a subset of the type's union (never a status word the
72
+ // carrier cannot hold — the ledger × words cross-leg).
73
+ for (const word of closure) {
74
+ expect(members, `"${word}" is not a declared RoundStatus member`).toContain(word);
75
+ }
76
+ // The failure statuses ride the same union (the exclusion is a real subset filter).
77
+ for (const failed of FAILED_STATUS) {
78
+ expect(members, `"${failed}" is not a declared RoundStatus member`).toContain(failed);
79
+ }
80
+ });
81
+ });
@@ -0,0 +1,164 @@
1
+ // packages/cdd-engine/src-next/contract/__tests__/frontmatter.test.ts
2
+ // T1 test suite for the front-matter head extraction chain (contract/frontmatter.ts):
3
+ // · the `---` fence split — the head/body boundary, the no-fence fallback;
4
+ // · the non-scalar downgrade — a list value reads null through the accessor;
5
+ // · the RAW channel — the extracted value equals the source string verbatim;
6
+ // · the twelve declared getters map the §2.3 key set.
7
+
8
+ import { describe, expect, it } from "vitest";
9
+ import { FrontMatterExtractor, FrontMatterHead } from "../frontmatter.ts";
10
+
11
+ /** The full §2.1 plan-shaped front matter — every one of the twelve declared keys. */
12
+ const FULL_HEAD = [
13
+ "---",
14
+ "title: 引擎文档工具(Engine Doc-Tooling)— 测试 Plan",
15
+ "doc-type: plan",
16
+ "version: v0.9",
17
+ "date: 2026-10-17",
18
+ "spec: docs/kairos/specs/2026-10-10-engine-doc-tooling-p10-design.md",
19
+ "parent-program: docs/kairos/specs/2026-10-10-engine-doc-tooling-overall.md",
20
+ "parent-version: v2.46",
21
+ "depends-on: P9",
22
+ "base: develop",
23
+ "status: Draft",
24
+ 'author: "[human] · Claude Opus 5(…)"',
25
+ "issues: close all issues",
26
+ "---",
27
+ "## Design",
28
+ "body prose",
29
+ ].join("\n");
30
+
31
+ describe("FrontMatterExtractor.split — the fence split", () => {
32
+ it("splits a fenced head from the body at the second `---` fence", () => {
33
+ const { head, body } = FrontMatterExtractor.split(FULL_HEAD);
34
+ expect(body).toBe("## Design\nbody prose");
35
+ expect(head.title).toBe("引擎文档工具(Engine Doc-Tooling)— 测试 Plan");
36
+ expect(head.docType).toBe("plan");
37
+ });
38
+
39
+ it("returns a null head and the original content when no opening fence is on line zero", () => {
40
+ const content = "no fence here\nbody line";
41
+ const { head, body } = FrontMatterExtractor.split(content);
42
+ expect(body).toBe(content);
43
+ expect(head.title).toBeNull();
44
+ for (const key of [
45
+ "title",
46
+ "doc-type",
47
+ "version",
48
+ "date",
49
+ "status",
50
+ "author",
51
+ "spec",
52
+ "parent-program",
53
+ "parent-version",
54
+ "depends-on",
55
+ "base",
56
+ "issues",
57
+ ])
58
+ expect(head.value(key)).toBeNull();
59
+ });
60
+
61
+ it("returns a null head and the original content when the closing fence is missing", () => {
62
+ const content = "---\ntitle: dangling\nbody line";
63
+ const { head, body } = FrontMatterExtractor.split(content);
64
+ expect(body).toBe(content);
65
+ expect(head.value("title")).toBeNull();
66
+ });
67
+
68
+ it("returns a null head and the original content when the fenced block is not a YAML record", () => {
69
+ const content = "---\n- a\n- b\n---\nbody line";
70
+ const { head, body } = FrontMatterExtractor.split(content);
71
+ expect(body).toBe(content);
72
+ expect(head.value("title")).toBeNull();
73
+ });
74
+
75
+ it("returns a null head and the original content when the fenced YAML fails to parse", () => {
76
+ const content = "---\n: bad : yaml\n---\nbody line";
77
+ const { head, body } = FrontMatterExtractor.split(content);
78
+ expect(body).toBe(content);
79
+ expect(head.value("title")).toBeNull();
80
+ });
81
+
82
+ it("carries the typed parse error with its position for the fill-class failure (D1 · #341 — a `[`-led value is a YAML flow sequence)", () => {
83
+ const content = "---\nauthor: [human] · Claude Opus 5\ndoc-type: phase-spec\n---\nbody";
84
+ const { head, body } = FrontMatterExtractor.split(content);
85
+ // the failure never collapses into a bare null head — the error rides along
86
+ expect(body).toBe(content);
87
+ expect(head.value("doc-type")).toBeNull();
88
+ const err = head.parseError;
89
+ expect(err).not.toBeNull();
90
+ expect(err?.line).toBe(1);
91
+ expect(err?.column).toBeGreaterThan(0);
92
+ expect(err?.reason).toContain("Unexpected scalar");
93
+ // the source excerpt is the offending front-matter line itself
94
+ expect(err?.source).toBe("author: [human] · Claude Opus 5");
95
+ });
96
+ });
97
+
98
+ describe("FrontMatterHead.value — the typed accessor", () => {
99
+ const { head } = FrontMatterExtractor.split(FULL_HEAD);
100
+
101
+ it("reads every declared scalar key through value(key)", () => {
102
+ expect(head.value("title")).toBe("引擎文档工具(Engine Doc-Tooling)— 测试 Plan");
103
+ expect(head.value("version")).toBe("v0.9");
104
+ expect(head.value("depends-on")).toBe("P9");
105
+ expect(head.value("base")).toBe("develop");
106
+ expect(head.value("issues")).toBe("close all issues");
107
+ });
108
+
109
+ it("downgrades a non-scalar YAML value to null (a list is not a head fact)", () => {
110
+ const { head: listHead } = FrontMatterExtractor.split(
111
+ "---\ntitle: test\nissues:\n - a\n - b\n---\nbody",
112
+ );
113
+ expect(listHead.value("issues")).toBeNull();
114
+ expect(listHead.value("title")).toBe("test");
115
+ });
116
+
117
+ it("downgrades a non-string scalar (a bare number) to null", () => {
118
+ const { head: numberHead } = FrontMatterExtractor.split("---\nversion: 2.46\n---\nbody");
119
+ expect(numberHead.value("version")).toBeNull();
120
+ });
121
+ });
122
+
123
+ describe("the RAW channel — extraction matches the source verbatim", () => {
124
+ it("reads a bracket-led author value byte-for-byte from the source string", () => {
125
+ const { head } = FrontMatterExtractor.split(FULL_HEAD);
126
+ expect(head.author).toBe("[human] · Claude Opus 5(…)");
127
+ expect(head.value("author")).toBe(head.author);
128
+ });
129
+ });
130
+
131
+ describe("the twelve declared getters (§2.3 key set)", () => {
132
+ const { head } = FrontMatterExtractor.split(FULL_HEAD);
133
+
134
+ it("exposes the kebab keys through the getter surface", () => {
135
+ expect(head.title).toBe("引擎文档工具(Engine Doc-Tooling)— 测试 Plan");
136
+ expect(head.docType).toBe("plan");
137
+ expect(head.version).toBe("v0.9");
138
+ expect(head.date).toBe("2026-10-17");
139
+ expect(head.status).toBe("Draft");
140
+ expect(head.author).toBe("[human] · Claude Opus 5(…)");
141
+ expect(head.spec).toBe("docs/kairos/specs/2026-10-10-engine-doc-tooling-p10-design.md");
142
+ expect(head.parentProgram).toBe("docs/kairos/specs/2026-10-10-engine-doc-tooling-overall.md");
143
+ expect(head.parentVersion).toBe("v2.46");
144
+ expect(head.dependsOn).toBe("P9");
145
+ expect(head.base).toBe("develop");
146
+ expect(head.issues).toBe("close all issues");
147
+ });
148
+
149
+ it("reads null for every getter on an empty head", () => {
150
+ const empty = new FrontMatterHead(null);
151
+ expect(empty.title).toBeNull();
152
+ expect(empty.docType).toBeNull();
153
+ expect(empty.version).toBeNull();
154
+ expect(empty.date).toBeNull();
155
+ expect(empty.status).toBeNull();
156
+ expect(empty.author).toBeNull();
157
+ expect(empty.spec).toBeNull();
158
+ expect(empty.parentProgram).toBeNull();
159
+ expect(empty.parentVersion).toBeNull();
160
+ expect(empty.dependsOn).toBeNull();
161
+ expect(empty.base).toBeNull();
162
+ expect(empty.issues).toBeNull();
163
+ });
164
+ });