@oscaner-skills/cdd-engine 2.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.
- package/README.md +2 -2
- package/README.zh-CN.md +2 -2
- 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 +141 -0
- package/dist/face/cli.js +891 -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 +603 -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 +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/dist/infra/doc-roots.js +19 -0
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/dist/infra/root.js +62 -0
- 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 +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +8 -7
- package/templates/report/issue-body.json +0 -46
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/smoke.integration.test.ts +0 -202
- package/src-next/__tests__/zero-dep.test.ts +0 -134
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
- package/src-next/contract/__tests__/declare.test.ts +0 -242
- package/src-next/contract/__tests__/doc.test.ts +0 -358
- package/src-next/contract/__tests__/judge.test.ts +0 -873
- package/src-next/contract/__tests__/lint.test.ts +0 -314
- package/src-next/contract/__tests__/project.test.ts +0 -419
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -983
- package/src-next/contract/doc.ts +0 -753
- package/src-next/contract/invariants.ts +0 -1268
- package/src-next/contract/judge.ts +0 -142
- package/src-next/contract/lint.ts +0 -275
- package/src-next/contract/project.ts +0 -596
- package/src-next/contract/skill-anatomy.ts +0 -273
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -948
- package/src-next/face/__tests__/capsule.test.ts +0 -276
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
- package/src-next/face/__tests__/cli.test.ts +0 -4643
- 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__/negation.ts +0 -6
- package/src-next/face/__tests__/projection.test.ts +0 -301
- package/src-next/face/__tests__/sync-runner.test.ts +0 -70
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -195
- package/src-next/face/board-view.ts +0 -662
- package/src-next/face/capsule.ts +0 -149
- package/src-next/face/cli.ts +0 -819
- package/src-next/face/declare.ts +0 -326
- package/src-next/face/gate.ts +0 -170
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -326
- package/src-next/face/lifecycle.ts +0 -700
- package/src-next/face/projection.ts +0 -282
- package/src-next/face/route-render.ts +0 -160
- package/src-next/face/words.ts +0 -296
- package/src-next/infra/__tests__/infra.test.ts +0 -287
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -185
- package/src-next/infra/workspace.ts +0 -232
- package/src-next/render/__tests__/render.test.ts +0 -499
- package/src-next/render/__tests__/skeleton.test.ts +0 -466
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -159
- package/src-next/render/skeleton.ts +0 -437
- package/src-next/render/templates.ts +0 -650
- package/src-next/session/__tests__/graph.test.ts +0 -270
- 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 -744
- package/src-next/session/__tests__/next.test.ts +0 -368
- package/src-next/session/__tests__/preflight.test.ts +0 -491
- package/src-next/session/__tests__/run.test.ts +0 -1014
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -469
- 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 -1004
- package/src-next/session/next.ts +0 -192
- package/src-next/session/preflight.ts +0 -240
- package/src-next/session/run.ts +0 -606
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -1,242 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/contract/__tests__/declare.test.ts
|
|
2
|
-
// T2 test suite for the element-registry declaration (contract/declare.ts).
|
|
3
|
-
//
|
|
4
|
-
// The declare module is the doc contract's single declaration: one typed
|
|
5
|
-
// registry per doc type (overall-spec / plan / phase-spec / single-spec). These
|
|
6
|
-
// tests pin the acceptance gates of the declared data — every registry inside
|
|
7
|
-
// the 20–40 element band (single-spec is the declared lightweight exception,
|
|
8
|
-
// exempted by name), every element carrying all five fields (anchor · presence ·
|
|
9
|
-
// value pattern · ref kind · home), the presence and ref-kind vocabularies
|
|
10
|
-
// staying inside their legal domains, and anchors unique per registry — plus the
|
|
11
|
-
// runtime type guards and the type-level contract surface.
|
|
12
|
-
//
|
|
13
|
-
// The legal value vocabularies are pinned here as the spec-side source of truth
|
|
14
|
-
// (an independent authority from the implementation): the guard or the data may
|
|
15
|
-
// never drift outside these domains. The negative type checks (a missing home,
|
|
16
|
-
// a missing elements surface) are pinned by expectTypeOf(...).not.toMatchTypeOf
|
|
17
|
-
// assertions: if a required field ever stopped being required, the incomplete
|
|
18
|
-
// shapes below would satisfy the type and the assertion itself would become a
|
|
19
|
-
// compile error, which the `tsc -p packages/cdd-engine --noEmit` gate fails on —
|
|
20
|
-
// so the compile surface is pinned even though vitest transforms types away.
|
|
21
|
-
|
|
22
|
-
import { describe, expect, expectTypeOf, it } from "vitest";
|
|
23
|
-
import type { ElementRegistry, Home, Presence, RefKind, RegistryElement } from "../declare.ts";
|
|
24
|
-
import { declaredRegistries, RegistryGuard } from "../declare.ts";
|
|
25
|
-
|
|
26
|
-
const PRESENCE_VALUES = [
|
|
27
|
-
"required",
|
|
28
|
-
"optional",
|
|
29
|
-
"conditional",
|
|
30
|
-
] as const satisfies readonly Presence[];
|
|
31
|
-
const REF_KIND_VALUES = [
|
|
32
|
-
"none",
|
|
33
|
-
"version-lineage",
|
|
34
|
-
"markdown-link",
|
|
35
|
-
"phase-id",
|
|
36
|
-
"issue-ref",
|
|
37
|
-
"spec-ref",
|
|
38
|
-
"parent-program",
|
|
39
|
-
"task-id",
|
|
40
|
-
] as const satisfies readonly RefKind[];
|
|
41
|
-
const HOME_VALUES = [
|
|
42
|
-
"header",
|
|
43
|
-
"section",
|
|
44
|
-
"facet",
|
|
45
|
-
"table",
|
|
46
|
-
"graph",
|
|
47
|
-
"task-block",
|
|
48
|
-
"task-field",
|
|
49
|
-
"task-step",
|
|
50
|
-
"design-body",
|
|
51
|
-
"conditional",
|
|
52
|
-
] as const satisfies readonly Home[];
|
|
53
|
-
|
|
54
|
-
const MIN_ELEMENTS = 20;
|
|
55
|
-
const MAX_ELEMENTS = 40;
|
|
56
|
-
/** The declared light-weight exception — single-spec is a deliberately sparse
|
|
57
|
-
* scaffold (header five-tuple + four prose sections + the change-history trio)
|
|
58
|
-
* whose registered element set sits below the full-doc band by design
|
|
59
|
-
* (declare.ts); it is exempted from the band and pinned separately. */
|
|
60
|
-
const LIGHTWEIGHT_DOC_TYPES: ReadonlySet<string> = new Set(["single-spec"]);
|
|
61
|
-
|
|
62
|
-
const ALL_REGISTRIES = [
|
|
63
|
-
declaredRegistries["overall-spec"],
|
|
64
|
-
declaredRegistries.plan,
|
|
65
|
-
declaredRegistries["phase-spec"],
|
|
66
|
-
declaredRegistries["single-spec"],
|
|
67
|
-
] as const satisfies readonly ElementRegistry[];
|
|
68
|
-
|
|
69
|
-
describe("declared registries", () => {
|
|
70
|
-
it("declares exactly the four doc types with their docType identity", () => {
|
|
71
|
-
expect(declaredRegistries["overall-spec"].docType).toBe("overall-spec");
|
|
72
|
-
expect(declaredRegistries.plan.docType).toBe("plan");
|
|
73
|
-
expect(declaredRegistries["phase-spec"].docType).toBe("phase-spec");
|
|
74
|
-
expect(declaredRegistries["single-spec"].docType).toBe("single-spec");
|
|
75
|
-
});
|
|
76
|
-
|
|
77
|
-
it("carries between 20 and 40 elements per full doc type (acceptance count gate)", () => {
|
|
78
|
-
for (const registry of ALL_REGISTRIES) {
|
|
79
|
-
if (LIGHTWEIGHT_DOC_TYPES.has(registry.docType)) continue;
|
|
80
|
-
expect(registry.elements.length, `${registry.docType} element count`).toBeGreaterThanOrEqual(
|
|
81
|
-
MIN_ELEMENTS,
|
|
82
|
-
);
|
|
83
|
-
expect(registry.elements.length, `${registry.docType} element count`).toBeLessThanOrEqual(
|
|
84
|
-
MAX_ELEMENTS,
|
|
85
|
-
);
|
|
86
|
-
}
|
|
87
|
-
});
|
|
88
|
-
|
|
89
|
-
it("keeps the light-weight doc types below the band by design (explicit exemption)", () => {
|
|
90
|
-
for (const registry of ALL_REGISTRIES) {
|
|
91
|
-
if (!LIGHTWEIGHT_DOC_TYPES.has(registry.docType)) continue;
|
|
92
|
-
expect(registry.elements.length, `${registry.docType} element count`).toBeLessThan(
|
|
93
|
-
MIN_ELEMENTS,
|
|
94
|
-
);
|
|
95
|
-
expect(registry.elements.length, `${registry.docType} element count`).toBeGreaterThan(0);
|
|
96
|
-
}
|
|
97
|
-
});
|
|
98
|
-
|
|
99
|
-
it("fills all five fields on every element (anchor · presence · valuePattern · refKind · home)", () => {
|
|
100
|
-
for (const registry of ALL_REGISTRIES) {
|
|
101
|
-
for (const element of registry.elements) {
|
|
102
|
-
expect(element.anchor.length, `${registry.docType} anchor`).toBeGreaterThan(0);
|
|
103
|
-
expect(PRESENCE_VALUES, `${registry.docType}:${element.anchor} presence`).toContain(
|
|
104
|
-
element.presence,
|
|
105
|
-
);
|
|
106
|
-
expect(
|
|
107
|
-
typeof element.valuePattern,
|
|
108
|
-
`${registry.docType}:${element.anchor} valuePattern`,
|
|
109
|
-
).toBe("string");
|
|
110
|
-
expect(REF_KIND_VALUES, `${registry.docType}:${element.anchor} refKind`).toContain(
|
|
111
|
-
element.refKind,
|
|
112
|
-
);
|
|
113
|
-
expect(HOME_VALUES, `${registry.docType}:${element.anchor} home`).toContain(element.home);
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
});
|
|
117
|
-
|
|
118
|
-
it("keeps anchors unique within each registry", () => {
|
|
119
|
-
for (const registry of ALL_REGISTRIES) {
|
|
120
|
-
const seen = new Set<string>();
|
|
121
|
-
for (const element of registry.elements) {
|
|
122
|
-
expect(
|
|
123
|
-
seen.has(element.anchor),
|
|
124
|
-
`${registry.docType} duplicate anchor: ${element.anchor}`,
|
|
125
|
-
).toBe(false);
|
|
126
|
-
seen.add(element.anchor);
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
});
|
|
130
|
-
|
|
131
|
-
it("keeps the ref-kind vocabulary inside its legal enum", () => {
|
|
132
|
-
const legal = new Set<unknown>(REF_KIND_VALUES);
|
|
133
|
-
for (const registry of ALL_REGISTRIES) {
|
|
134
|
-
for (const element of registry.elements) {
|
|
135
|
-
expect(element.refKind, `${registry.docType}:${element.anchor} refKind`).toBeDefined();
|
|
136
|
-
expect(legal.has(element.refKind), `${registry.docType}:${element.anchor} refKind`).toBe(
|
|
137
|
-
true,
|
|
138
|
-
);
|
|
139
|
-
}
|
|
140
|
-
}
|
|
141
|
-
});
|
|
142
|
-
});
|
|
143
|
-
|
|
144
|
-
describe("RegistryGuard type guards", () => {
|
|
145
|
-
it("accepts a well-formed registry element and rejects malformed shapes", () => {
|
|
146
|
-
const element = {
|
|
147
|
-
anchor: "## Goal",
|
|
148
|
-
presence: "required",
|
|
149
|
-
valuePattern: "^## Goal$",
|
|
150
|
-
refKind: "none",
|
|
151
|
-
home: "facet",
|
|
152
|
-
} satisfies RegistryElement;
|
|
153
|
-
expect(RegistryGuard.isElement(element)).toBe(true);
|
|
154
|
-
|
|
155
|
-
// Missing the required home surface.
|
|
156
|
-
expect(
|
|
157
|
-
RegistryGuard.isElement({
|
|
158
|
-
anchor: "## Goal",
|
|
159
|
-
presence: "required",
|
|
160
|
-
valuePattern: "^## Goal$",
|
|
161
|
-
refKind: "none",
|
|
162
|
-
}),
|
|
163
|
-
).toBe(false);
|
|
164
|
-
// Presence outside the legal domain.
|
|
165
|
-
expect(
|
|
166
|
-
RegistryGuard.isElement({ anchor: "## Goal", presence: "sometimes", home: "facet" }),
|
|
167
|
-
).toBe(false);
|
|
168
|
-
// Empty anchor token.
|
|
169
|
-
expect(RegistryGuard.isElement({ anchor: "", presence: "required", home: "facet" })).toBe(
|
|
170
|
-
false,
|
|
171
|
-
);
|
|
172
|
-
// Ref kind outside the legal enum.
|
|
173
|
-
expect(
|
|
174
|
-
RegistryGuard.isElement({
|
|
175
|
-
anchor: "## Goal",
|
|
176
|
-
presence: "required",
|
|
177
|
-
refKind: "elsewhere",
|
|
178
|
-
home: "facet",
|
|
179
|
-
}),
|
|
180
|
-
).toBe(false);
|
|
181
|
-
// Non-object inputs.
|
|
182
|
-
expect(RegistryGuard.isElement(null)).toBe(false);
|
|
183
|
-
expect(RegistryGuard.isElement("## Goal")).toBe(false);
|
|
184
|
-
});
|
|
185
|
-
|
|
186
|
-
it("recognizes the four declared registries and rejects registry-shaped non-registries", () => {
|
|
187
|
-
expect(RegistryGuard.isRegistry(declaredRegistries["overall-spec"])).toBe(true);
|
|
188
|
-
expect(RegistryGuard.isRegistry(declaredRegistries.plan)).toBe(true);
|
|
189
|
-
expect(RegistryGuard.isRegistry(declaredRegistries["phase-spec"])).toBe(true);
|
|
190
|
-
expect(RegistryGuard.isRegistry(declaredRegistries["single-spec"])).toBe(true);
|
|
191
|
-
// Missing the elements surface.
|
|
192
|
-
expect(RegistryGuard.isRegistry({ docType: "overall-spec" })).toBe(false);
|
|
193
|
-
// Unknown doc type.
|
|
194
|
-
expect(RegistryGuard.isRegistry({ docType: "unknown", elements: [] })).toBe(false);
|
|
195
|
-
// A registry whose element fails the element guard is not a registry.
|
|
196
|
-
expect(
|
|
197
|
-
RegistryGuard.isRegistry({
|
|
198
|
-
docType: "overall-spec",
|
|
199
|
-
elements: [{ anchor: "## X", presence: "sometimes", home: "section" }],
|
|
200
|
-
}),
|
|
201
|
-
).toBe(false);
|
|
202
|
-
});
|
|
203
|
-
});
|
|
204
|
-
|
|
205
|
-
describe("type-level contract", () => {
|
|
206
|
-
it("pins the legal value vocabularies as the narrow unions", () => {
|
|
207
|
-
expectTypeOf<Presence>().toEqualTypeOf<"required" | "optional" | "conditional">();
|
|
208
|
-
expectTypeOf<RefKind>().toEqualTypeOf<
|
|
209
|
-
| "none"
|
|
210
|
-
| "version-lineage"
|
|
211
|
-
| "markdown-link"
|
|
212
|
-
| "phase-id"
|
|
213
|
-
| "issue-ref"
|
|
214
|
-
| "spec-ref"
|
|
215
|
-
| "parent-program"
|
|
216
|
-
| "task-id"
|
|
217
|
-
>();
|
|
218
|
-
});
|
|
219
|
-
|
|
220
|
-
it("narrows a guarded unknown to the registry-element contract", () => {
|
|
221
|
-
const candidate: unknown = {
|
|
222
|
-
anchor: "## Goal",
|
|
223
|
-
presence: "required",
|
|
224
|
-
valuePattern: "^## Goal$",
|
|
225
|
-
refKind: "none",
|
|
226
|
-
home: "facet",
|
|
227
|
-
};
|
|
228
|
-
if (RegistryGuard.isElement(candidate)) {
|
|
229
|
-
expectTypeOf(candidate).toMatchTypeOf<RegistryElement>();
|
|
230
|
-
}
|
|
231
|
-
});
|
|
232
|
-
|
|
233
|
-
it("rejects incomplete shapes at the type level (home and elements are required)", () => {
|
|
234
|
-
expectTypeOf({
|
|
235
|
-
anchor: "## Goal",
|
|
236
|
-
presence: "required",
|
|
237
|
-
valuePattern: "^## Goal$",
|
|
238
|
-
refKind: "none",
|
|
239
|
-
}).not.toMatchTypeOf<RegistryElement>();
|
|
240
|
-
expectTypeOf({ docType: "overall-spec" }).not.toMatchTypeOf<ElementRegistry>();
|
|
241
|
-
});
|
|
242
|
-
});
|
|
@@ -1,358 +0,0 @@
|
|
|
1
|
-
// packages/cdd-engine/src-next/contract/__tests__/doc.test.ts
|
|
2
|
-
// T4 parse-layer suite (contract/doc.ts) — the brief's positive checkables:
|
|
3
|
-
// · the four tables of the overall parse as header + data rows;
|
|
4
|
-
// · the plan's `### Task N:` blocks parse into fields + steps;
|
|
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);
|
|
7
|
-
// · the DocType class face carries zero judgment methods (spec §2.2 — the machine
|
|
8
|
-
// assertion surface: extract-only classes).
|
|
9
|
-
// The parse records and known-good document literals are the independent sources of
|
|
10
|
-
// truth — every assertion compares against the fixture doc the parser must extract.
|
|
11
|
-
|
|
12
|
-
import { readFileSync } from "node:fs";
|
|
13
|
-
import { describe, expect, it } from "vitest";
|
|
14
|
-
import { SkeletonAssembler } from "../../render/skeleton.ts";
|
|
15
|
-
import { declaredRegistries } from "../declare.ts";
|
|
16
|
-
import { docTypeParsers, OverallDocType, PhaseSpecDocType, PlanDocType } from "../doc.ts";
|
|
17
|
-
import { Contract } from "../judge.ts";
|
|
18
|
-
import type { DocKey } from "../project.ts";
|
|
19
|
-
import { Projector } from "../project.ts";
|
|
20
|
-
|
|
21
|
-
/** A conforming overall — the four tables, the dependency graph and the header tuple. */
|
|
22
|
-
const OVERALL = [
|
|
23
|
-
"# 文档架构方法论 v2 — 测试 Overall",
|
|
24
|
-
"- **Version**: v1.1 · 2026-10-07",
|
|
25
|
-
"- **Status**: Approved",
|
|
26
|
-
"- **Author**: [human]",
|
|
27
|
-
"- **Constraints**: 全部约定自动生效",
|
|
28
|
-
"",
|
|
29
|
-
"## Document scope",
|
|
30
|
-
"scope prose",
|
|
31
|
-
"",
|
|
32
|
-
"## File paths",
|
|
33
|
-
"| Artifact | Path |",
|
|
34
|
-
"| --- | --- |",
|
|
35
|
-
"| overall-spec | docs/kairos/specs/test-overall.md |",
|
|
36
|
-
"",
|
|
37
|
-
"## Program charter",
|
|
38
|
-
"### Goal",
|
|
39
|
-
"- goal text",
|
|
40
|
-
"",
|
|
41
|
-
"### Non-goals",
|
|
42
|
-
"- non-goal text",
|
|
43
|
-
"",
|
|
44
|
-
"### Cross-cutting",
|
|
45
|
-
"- cross text",
|
|
46
|
-
"",
|
|
47
|
-
"## Issue inventory",
|
|
48
|
-
"| Phase | Issue (ref) | Title summary |",
|
|
49
|
-
"| --- | --- | --- |",
|
|
50
|
-
"| P1 | #123 | issue one |",
|
|
51
|
-
"| P2 | none | issue two |",
|
|
52
|
-
"",
|
|
53
|
-
"## Phase inventory",
|
|
54
|
-
"| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
|
|
55
|
-
"| --- | --- | --- | --- | --- | --- | --- |",
|
|
56
|
-
"| P1 | DocType 抽象 + schema 工厂 | scope a | [P1-design](docs/kairos/specs/x-p1-design.md) | [P1 plan](docs/kairos/plans/x-p1.md) | criteria a | |",
|
|
57
|
-
"| P2 | 判定面 + 协调器 | scope b | P2-design | [P2 plan](docs/kairos/plans/x-p2.md) | criteria b | |",
|
|
58
|
-
"",
|
|
59
|
-
"## Dependency graph (ASCII)",
|
|
60
|
-
"P1 -> P2",
|
|
61
|
-
"-> = hard block",
|
|
62
|
-
"",
|
|
63
|
-
"## Boundary rules",
|
|
64
|
-
"- boundary rule",
|
|
65
|
-
"",
|
|
66
|
-
"## Maintenance",
|
|
67
|
-
"- maintenance note",
|
|
68
|
-
"",
|
|
69
|
-
"## Change history",
|
|
70
|
-
"| Version | Date | Summary |",
|
|
71
|
-
"| --- | --- | --- |",
|
|
72
|
-
"| v1.20 | 2026-10-06 | prior change |",
|
|
73
|
-
"| v1.21 | 2026-10-07 | merged change |",
|
|
74
|
-
];
|
|
75
|
-
|
|
76
|
-
/** A conforming plan — the header chain anchors + the `### Task N:` blocks. */
|
|
77
|
-
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",
|
|
84
|
-
"",
|
|
85
|
-
"## Constraints",
|
|
86
|
-
"",
|
|
87
|
-
"- delta constraint",
|
|
88
|
-
"",
|
|
89
|
-
"### Task 1: skeleton",
|
|
90
|
-
"- **Objective**: establish the skeleton",
|
|
91
|
-
"- **Files**: src-next/ | tsconfig.json",
|
|
92
|
-
"- **Consumes**: none",
|
|
93
|
-
"- **Produces**: skeleton",
|
|
94
|
-
"- **Steps**:",
|
|
95
|
-
" - step one",
|
|
96
|
-
" - step two — checkable: second step check",
|
|
97
|
-
"- **Acceptance**: skeleton green",
|
|
98
|
-
"- **DependsOn**: none",
|
|
99
|
-
"",
|
|
100
|
-
"### Task 2: registry",
|
|
101
|
-
"- **Objective**: declare the registries",
|
|
102
|
-
"- **Files**: src-next/contract/declare.ts",
|
|
103
|
-
"- **Consumes**: T1 skeleton",
|
|
104
|
-
"- **Produces**: registry data",
|
|
105
|
-
"- **Steps**:",
|
|
106
|
-
" - write the registry — checkable: types compile",
|
|
107
|
-
"- **Acceptance**: registry green",
|
|
108
|
-
"- **DependsOn**: 1",
|
|
109
|
-
];
|
|
110
|
-
|
|
111
|
-
/** A conforming phase-spec — the header five-tuple + the double-layer design skeleton. */
|
|
112
|
-
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)",
|
|
119
|
-
"",
|
|
120
|
-
"## Design",
|
|
121
|
-
"",
|
|
122
|
-
"### 1. 判定面",
|
|
123
|
-
"#### 1.1 策略类族",
|
|
124
|
-
"- 判定多态",
|
|
125
|
-
"",
|
|
126
|
-
"### 2. 编排面",
|
|
127
|
-
"#### 2.1 波次",
|
|
128
|
-
"- 波次计算",
|
|
129
|
-
"",
|
|
130
|
-
"### Acceptance criteria",
|
|
131
|
-
"",
|
|
132
|
-
"- `acceptance entry`",
|
|
133
|
-
"",
|
|
134
|
-
"## Constraints",
|
|
135
|
-
"",
|
|
136
|
-
"- delta constraint",
|
|
137
|
-
"",
|
|
138
|
-
"## Review record",
|
|
139
|
-
"- review note",
|
|
140
|
-
];
|
|
141
|
-
|
|
142
|
-
describe("OverallDocType.parse — the four tables + the chain root", () => {
|
|
143
|
-
const parsed = new OverallDocType("overall-spec").parse(OVERALL);
|
|
144
|
-
|
|
145
|
-
it("parses the header lines and the section skeleton", () => {
|
|
146
|
-
expect(parsed.docType).toBe("overall-spec");
|
|
147
|
-
expect(parsed.title).toBe("# 文档架构方法论 v2 — 测试 Overall");
|
|
148
|
-
expect(parsed.headerLines.some((line) => line.includes("**Version**"))).toBe(true);
|
|
149
|
-
expect(parsed.sections.map((section) => section.heading)).toEqual([
|
|
150
|
-
"## Document scope",
|
|
151
|
-
"## File paths",
|
|
152
|
-
"## Program charter",
|
|
153
|
-
"## Issue inventory",
|
|
154
|
-
"## Phase inventory",
|
|
155
|
-
"## Dependency graph (ASCII)",
|
|
156
|
-
"## Boundary rules",
|
|
157
|
-
"## Maintenance",
|
|
158
|
-
"## Change history",
|
|
159
|
-
]);
|
|
160
|
-
});
|
|
161
|
-
|
|
162
|
-
it("parses the File-paths table into a header row + data rows", () => {
|
|
163
|
-
const table = parsed.tables["File paths"];
|
|
164
|
-
expect(table.headerRow).toEqual(["Artifact", "Path"]);
|
|
165
|
-
expect(table.rows).toEqual([["overall-spec", "docs/kairos/specs/test-overall.md"]]);
|
|
166
|
-
});
|
|
167
|
-
|
|
168
|
-
it("parses the Issue-inventory table rows", () => {
|
|
169
|
-
const table = parsed.tables["Issue inventory"];
|
|
170
|
-
expect(table.headerRow).toEqual(["Phase", "Issue (ref)", "Title summary"]);
|
|
171
|
-
expect(table.rows).toEqual([
|
|
172
|
-
["P1", "#123", "issue one"],
|
|
173
|
-
["P2", "none", "issue two"],
|
|
174
|
-
]);
|
|
175
|
-
});
|
|
176
|
-
|
|
177
|
-
it("parses the Phase-inventory table (id from the canonical first-column cell -> chain phases)", () => {
|
|
178
|
-
const table = parsed.tables["Phase inventory"];
|
|
179
|
-
expect(table.rows).toHaveLength(2);
|
|
180
|
-
expect(parsed.chain.phases.map((phase) => phase.id)).toEqual(["P1", "P2"]);
|
|
181
|
-
expect(parsed.chain.phases[0].designCell).toBe("[P1-design](docs/kairos/specs/x-p1-design.md)");
|
|
182
|
-
expect(parsed.chain.phases[0].planCell).toBe("[P1 plan](docs/kairos/plans/x-p1.md)");
|
|
183
|
-
// a tokenized (non-linked) design cell is carried verbatim, never judged here.
|
|
184
|
-
expect(parsed.chain.phases[1].designCell).toBe("P2-design");
|
|
185
|
-
});
|
|
186
|
-
|
|
187
|
-
it("parses the Change-history rows with their version tokens", () => {
|
|
188
|
-
const table = parsed.tables["Change history"];
|
|
189
|
-
expect(table.rows.map((row) => row[0])).toEqual(["v1.20", "v1.21"]);
|
|
190
|
-
});
|
|
191
|
-
|
|
192
|
-
it("parses the dependency-graph edge lines into from/to tokens", () => {
|
|
193
|
-
expect(parsed.graphEdges).toEqual([{ text: "P1 -> P2", from: "P1", to: "P2" }]);
|
|
194
|
-
});
|
|
195
|
-
|
|
196
|
-
it("parses the chain root — the overall is the root (no parent/spec links)", () => {
|
|
197
|
-
expect(parsed.chain.docType).toBe("overall-spec");
|
|
198
|
-
expect(parsed.chain.parentLink).toBeNull();
|
|
199
|
-
expect(parsed.chain.specLink).toBeNull();
|
|
200
|
-
expect(parsed.chain.parentTokens).toEqual([]);
|
|
201
|
-
});
|
|
202
|
-
});
|
|
203
|
-
|
|
204
|
-
describe("PlanDocType.parse — the task blocks + the Class-A/B chain root", () => {
|
|
205
|
-
const parsed = new PlanDocType("plan").parse(PLAN);
|
|
206
|
-
|
|
207
|
-
it("parses the header lines including the chain anchors", () => {
|
|
208
|
-
expect(parsed.docType).toBe("plan");
|
|
209
|
-
expect(parsed.headerLines.some((line) => line.includes("**Spec:**"))).toBe(true);
|
|
210
|
-
expect(parsed.sections.map((section) => section.heading)).toEqual(["## Constraints"]);
|
|
211
|
-
});
|
|
212
|
-
|
|
213
|
-
it("parses every `### Task N:` block into fields + steps", () => {
|
|
214
|
-
expect(parsed.taskBlocks.map((block) => block.id)).toEqual([1, 2]);
|
|
215
|
-
const first = parsed.taskBlocks[0];
|
|
216
|
-
expect(first.heading).toBe("### Task 1: skeleton");
|
|
217
|
-
expect(first.fields.map((field) => field.key)).toEqual([
|
|
218
|
-
"Objective",
|
|
219
|
-
"Files",
|
|
220
|
-
"Consumes",
|
|
221
|
-
"Produces",
|
|
222
|
-
"Steps",
|
|
223
|
-
"Acceptance",
|
|
224
|
-
"DependsOn",
|
|
225
|
-
]);
|
|
226
|
-
expect(first.steps.map((step) => step.action)).toEqual(["step one", "step two"]);
|
|
227
|
-
expect(first.steps[1].checkable).toBe("second step check");
|
|
228
|
-
const dependsOn = first.fields.find((field) => field.key === "DependsOn");
|
|
229
|
-
expect(dependsOn?.lines[0]).toBe("none");
|
|
230
|
-
});
|
|
231
|
-
|
|
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
|
-
});
|
|
241
|
-
expect(parsed.chain.parentTokens).toEqual(["v1.21"]);
|
|
242
|
-
expect(parsed.chain.dependsOn).toBe("P1 design v1.1");
|
|
243
|
-
});
|
|
244
|
-
});
|
|
245
|
-
|
|
246
|
-
describe("PhaseSpecDocType.parse — the design skeleton + the Class-B chain root", () => {
|
|
247
|
-
const parsed = new PhaseSpecDocType("phase-spec").parse(PHASE_SPEC);
|
|
248
|
-
|
|
249
|
-
it("parses the header five-tuple surface", () => {
|
|
250
|
-
expect(parsed.docType).toBe("phase-spec");
|
|
251
|
-
expect(parsed.headerLines.some((line) => line.includes("**Parent program**"))).toBe(true);
|
|
252
|
-
expect(parsed.sections.map((section) => section.heading)).toEqual([
|
|
253
|
-
"## Design",
|
|
254
|
-
"## Constraints",
|
|
255
|
-
"## Review record",
|
|
256
|
-
]);
|
|
257
|
-
});
|
|
258
|
-
|
|
259
|
-
it("parses the double-layer design skeleton into groups + items", () => {
|
|
260
|
-
expect(parsed.design.map((group) => group.number)).toEqual(["1", "2"]);
|
|
261
|
-
expect(parsed.design.map((group) => group.heading)).toEqual(["判定面", "编排面"]);
|
|
262
|
-
expect(parsed.design[0].items.map((item) => item.number)).toEqual(["1.1"]);
|
|
263
|
-
expect(parsed.design[0].items[0].heading).toBe("策略类族");
|
|
264
|
-
expect(parsed.design[1].items.map((item) => item.number)).toEqual(["2.1"]);
|
|
265
|
-
// the `### Acceptance criteria` leaf is a design-body anchor, not a numbered group.
|
|
266
|
-
expect(parsed.design.some((group) => group.heading.startsWith("Acceptance"))).toBe(false);
|
|
267
|
-
});
|
|
268
|
-
|
|
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
|
-
});
|
|
274
|
-
expect(parsed.chain.parentTokens).toEqual(["v1.21"]);
|
|
275
|
-
expect(parsed.chain.specLink).toBeNull();
|
|
276
|
-
});
|
|
277
|
-
});
|
|
278
|
-
|
|
279
|
-
describe("the doc-type composition root", () => {
|
|
280
|
-
it("exposes one parser per doc key", () => {
|
|
281
|
-
expect(docTypeParsers["overall-spec"]).toBeInstanceOf(OverallDocType);
|
|
282
|
-
expect(docTypeParsers.plan).toBeInstanceOf(PlanDocType);
|
|
283
|
-
expect(docTypeParsers["phase-spec"]).toBeInstanceOf(PhaseSpecDocType);
|
|
284
|
-
});
|
|
285
|
-
});
|
|
286
|
-
|
|
287
|
-
describe("the DocType class face (spec §2.2)", () => {
|
|
288
|
-
it("carries zero judgment methods — no validate/audit/detect/judge symbols on the class face", () => {
|
|
289
|
-
const source = readFileSync(new URL("../doc.ts", import.meta.url), "utf8");
|
|
290
|
-
const judgementSymbols = source.match(/\b(validate|audit|detect|judge|assert)\s*\(/g) ?? [];
|
|
291
|
-
expect(judgementSymbols, "doc.ts must be judge-free (extract-only)").toEqual([]);
|
|
292
|
-
});
|
|
293
|
-
|
|
294
|
-
it("has no exported behavior-carrying bare function", () => {
|
|
295
|
-
const source = readFileSync(new URL("../doc.ts", import.meta.url), "utf8");
|
|
296
|
-
const functionExports = source.match(/export\s+(?:async\s+)?function\s+\w+/g) ?? [];
|
|
297
|
-
expect(functionExports).toEqual([]);
|
|
298
|
-
const arrowExports = source.match(/export\s+const\s+\w+\s*=\s*(?:\([^)]*\)|[\w]+)\s*=>/g) ?? [];
|
|
299
|
-
expect(arrowExports).toEqual([]);
|
|
300
|
-
});
|
|
301
|
-
});
|
|
302
|
-
|
|
303
|
-
describe("P2 — the four doc skeletons judge clean (spec §7.2 colocated pin)", () => {
|
|
304
|
-
/** The empty fs seam — every chain link of a skeleton is a `<…>` placeholder
|
|
305
|
-
* target (the judge's exemption chain), so the file-existence / sibling-scan
|
|
306
|
-
* surfaces never fire and the skeleton is green by construction. */
|
|
307
|
-
const EMPTY_FS = { exists: () => false, read: () => null, list: () => [] };
|
|
308
|
-
const contract = new Contract();
|
|
309
|
-
const projector = new Projector(declaredRegistries);
|
|
310
|
-
const PATH_OF: Record<DocKey, string> = {
|
|
311
|
-
"overall-spec": "docs/kairos/specs/x-overall.md",
|
|
312
|
-
plan: "docs/kairos/plans/x-p1.md",
|
|
313
|
-
"phase-spec": "docs/kairos/specs/x-p1-design.md",
|
|
314
|
-
"single-spec": "docs/kairos/specs/x-single-spec.md",
|
|
315
|
-
};
|
|
316
|
-
/** The fixed run date — the version-row date truth (never a live clock). */
|
|
317
|
-
const DATE = "2026-10-11";
|
|
318
|
-
|
|
319
|
-
/** The fixed-date skeleton bytes of one doc type. */
|
|
320
|
-
const renderOf = (key: DocKey): string =>
|
|
321
|
-
new SkeletonAssembler(projector.skeleton()[key], DATE).render();
|
|
322
|
-
|
|
323
|
-
it("judges each type's skeleton clean — zero findings (the §4.1 placeholder-anchored by-construction green)", () => {
|
|
324
|
-
for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
|
|
325
|
-
const findings = contract.validate({
|
|
326
|
-
docKey: key,
|
|
327
|
-
path: PATH_OF[key],
|
|
328
|
-
content: renderOf(key),
|
|
329
|
-
root: ".",
|
|
330
|
-
fs: EMPTY_FS,
|
|
331
|
-
});
|
|
332
|
-
expect(findings, `${key} skeleton findings`).toEqual([]);
|
|
333
|
-
}
|
|
334
|
-
});
|
|
335
|
-
|
|
336
|
-
it("keeps every `:::fill` inside the content positions — zero hits on the link anchors / structure rows", () => {
|
|
337
|
-
for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
|
|
338
|
-
for (const line of renderOf(key).split("\n")) {
|
|
339
|
-
if (!line.includes(":::fill")) continue;
|
|
340
|
-
// the placeholder-link anchors (`](<`), the version/status truths, the
|
|
341
|
-
// table column headers and the separator rows never carry a fill
|
|
342
|
-
expect(line, `${key}: ${line}`).not.toMatch(/\]\(</);
|
|
343
|
-
expect(line, `${key}: ${line}`).not.toMatch(/^- \*\*Version\*\*:|^- \*\*Status\*\*:/);
|
|
344
|
-
expect(line, `${key}: ${line}`).not.toMatch(/^\| (Artifact|Phase|#|Version) \|/);
|
|
345
|
-
expect(line, `${key}: ${line}`).not.toMatch(/^\| ?---/);
|
|
346
|
-
}
|
|
347
|
-
}
|
|
348
|
-
});
|
|
349
|
-
|
|
350
|
-
it("the numeric headings are true values — the shape `### 1.` / `#### 1.1` / `### Task 1:` land, a literal `N` never", () => {
|
|
351
|
-
const spec = renderOf("phase-spec");
|
|
352
|
-
expect(spec).toContain("### 1. :::fill group-title");
|
|
353
|
-
expect(spec).toContain("#### 1.1 :::fill item-title");
|
|
354
|
-
expect(renderOf("plan")).toContain("### Task 1: :::fill task-title");
|
|
355
|
-
expect(spec).not.toContain("Task N:");
|
|
356
|
-
expect(renderOf("plan")).not.toContain("Task N:");
|
|
357
|
-
});
|
|
358
|
-
});
|