@oscaner-skills/cdd-engine 3.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +149 -0
- package/dist/face/cli.js +893 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +702 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +504 -0
- package/dist/face/words.js +258 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +453 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -0,0 +1,434 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/render/skeleton.ts
|
|
2
|
+
// The SkeletonAssembler — the render face of the skeleton projection (spec §3/§4.1,
|
|
3
|
+
// the `cdd schema get <type> --output skeleton` rendering): a DocSkeleton (contract/project.ts — the
|
|
4
|
+
// required-only derived face, every element classified into its
|
|
5
|
+
// placeholder-anchoring slot kind) is assembled into the markdown skeleton bytes
|
|
6
|
+
// the consumer fills. The structure is the same registry-derived surface the
|
|
7
|
+
// judge reads — the skeleton is green by construction, never an exemption channel
|
|
8
|
+
// (spec §4.1: pure content slots take `:::fill`, link-shaped anchors a placeholder
|
|
9
|
+
// link, structure is true value — the doc-contract pin judges the rendered bytes).
|
|
10
|
+
//
|
|
11
|
+
// The front-matter head is the ONE structured-metadata channel (spec §2.2's
|
|
12
|
+
// standard parser): the frontmatter-home slots render as a `---`-fenced YAML
|
|
13
|
+
// record emitted by `yaml.stringify` in one call — an independent line set, never
|
|
14
|
+
// hand-spun header lines and never part of the slot/probe channel. §4.2's
|
|
15
|
+
// placeholder three-way split: the link-typed keys (`spec` · `parent-program`)
|
|
16
|
+
// emit a `<…>` scalar on the judge's placeholder-exemption chain; the content
|
|
17
|
+
// keys (`title` · `author` · `depends-on` · `base`) emit `:::fill <key>`; the
|
|
18
|
+
// truth keys (`doc-type` · `version` · `date` · `status`) emit true values. The
|
|
19
|
+
// optional `parent-version` key is deliberately NOT emitted — its shape is typed
|
|
20
|
+
// (`v<n>.<m>`, so a fill or a link scalar would violate the domain) and absence
|
|
21
|
+
// is legal. The markdown body stays the registry-driven scaffold. render() is a
|
|
22
|
+
// pure byte renderer — it never appends a trailing newline (the CLI appends the
|
|
23
|
+
// single `\n`, so a redirected fixture ends with exactly one newline). The
|
|
24
|
+
// composition is the judgment site of the projection: after assembly render()
|
|
25
|
+
// asserts slot consumption over the BODY slots — every registered body slot emits
|
|
26
|
+
// a probe and every probe names a registered body slot, so a registry/composition
|
|
27
|
+
// drift is a loud throw in the renderer, never a silent byte gap (the front-matter
|
|
28
|
+
// key set is registry-faithful by construction — the assertion domain is the body
|
|
29
|
+
// the composition hand-assembles).
|
|
30
|
+
//
|
|
31
|
+
// Module-level exports are types / the class — zero behavior-carrying bare
|
|
32
|
+
// functions (the plan's zero-bare-function discipline).
|
|
33
|
+
import { Pair, Scalar, stringify as stringifyYaml, YAMLMap } from "yaml";
|
|
34
|
+
/** The placeholder scalars of the front-matter link keys (spec §4.2 + D3) — the
|
|
35
|
+
* link-typed head keys (`spec` · `parent-program`) render a `<…>`-shaped value
|
|
36
|
+
* that rides the judge's placeholder-exemption chain (a bare `^<[^>]+>$` target
|
|
37
|
+
* the file-existence / sibling-scan / cross-doc-chain strategies all skip),
|
|
38
|
+
* never a `:::fill` (a fill in a link slot is a guaranteed finding). The
|
|
39
|
+
* placeholder IS the fill contract (show-don't-tell — zero prose rules): its
|
|
40
|
+
* inner shape is a BARE relative-path exemplar (`docs/kairos/specs/…-overall.md`),
|
|
41
|
+
* the exact form the consumer must fill — the <>-shell keeps the exemption, the
|
|
42
|
+
* path inside both bookends the value and doubles as the shape sample (#342: a
|
|
43
|
+
* consumer copying the exemplar fills a bare path, never a markdown link). */
|
|
44
|
+
const FRONT_MATTER_LINKS = {
|
|
45
|
+
spec: "<docs/kairos/specs/…-design.md>",
|
|
46
|
+
"parent-program": "<docs/kairos/specs/…-overall.md>",
|
|
47
|
+
};
|
|
48
|
+
/** The generator truths of the pattern-typed body slots (spec §3.2/§4.1) —
|
|
49
|
+
* hand-pinned legal literals consistent with each declared value domain (the
|
|
50
|
+
* `none` issue-ref default; the `[Pending]` design cell — the only pending form
|
|
51
|
+
* its valuePattern admits, never bare `Pending` — and the bare `Pending` plan
|
|
52
|
+
* cell, a legal alternative of its domain) and the conforming graph rows (the
|
|
53
|
+
* `P1 -> P2` hard edge + the legend line). The head's `status` truth lives in
|
|
54
|
+
* the front-matter emission (`status: Draft` — the first legal literal of every
|
|
55
|
+
* status enum — via `#frontmatterTruth`, never a body fill). */
|
|
56
|
+
const TRUTH_LINES = {
|
|
57
|
+
"Issue ref cell": "none",
|
|
58
|
+
"Implementation plan cell": "Pending",
|
|
59
|
+
"Design spec cell": "[Pending]",
|
|
60
|
+
"Hard edge": "P1 -> P2",
|
|
61
|
+
"Graph legend": "- `->` = hard block",
|
|
62
|
+
};
|
|
63
|
+
/** The change-history table scaffold — the registered `Change history row` /
|
|
64
|
+
* `Version token` / `Change history date` cells composed into the shared
|
|
65
|
+
* header + separator + first-row shape (the version row must equal the header
|
|
66
|
+
* version — v0.1 — and stay version-ascending, spec §3.2). */
|
|
67
|
+
const HISTORY_HEADER = "| Version | date | summary | author |";
|
|
68
|
+
/**
|
|
69
|
+
* The skeleton assembler — one DocSkeleton (contract/project.ts, the required-only
|
|
70
|
+
* sixth projection) → the markdown skeleton bytes. Constructed on the projection
|
|
71
|
+
* and the run date (the CLI injects the run day; tests inject a fixed date), the
|
|
72
|
+
* instance is stateless after construction, so sharing one instance composes
|
|
73
|
+
* safely. The composition per doc type mirrors the doc's section sequence; every
|
|
74
|
+
* required element of the type lands in its structural position — the front-
|
|
75
|
+
* matter keys in the head record (the registry's frontmatter-home slot order),
|
|
76
|
+
* the body elements in the section scaffold (the doc-contract pin judges the
|
|
77
|
+
* rendered bytes — a missing required anchor is a finding).
|
|
78
|
+
*/
|
|
79
|
+
export class SkeletonAssembler {
|
|
80
|
+
/** The doc type of the projected skeleton. */
|
|
81
|
+
#docType;
|
|
82
|
+
/** The injected run date — the front-matter `date:` truth (`YYYY-MM-DD`). */
|
|
83
|
+
#date;
|
|
84
|
+
/** The projection's slots in shape-group order (the body slot channel). */
|
|
85
|
+
#slots;
|
|
86
|
+
/** The front-matter emission list — the head's required + optional keys. */
|
|
87
|
+
#frontmatterSlots;
|
|
88
|
+
constructor(projection, date) {
|
|
89
|
+
this.#docType = projection.docType;
|
|
90
|
+
this.#date = date;
|
|
91
|
+
this.#slots = projection.slots;
|
|
92
|
+
this.#frontmatterSlots = projection.frontmatter;
|
|
93
|
+
}
|
|
94
|
+
/** Render the doc skeleton's markdown bytes — no trailing newline (the CLI owns
|
|
95
|
+
* the appended `\n`; the EOF-newline rule lands on the redirected fixture).
|
|
96
|
+
* The front-matter head is emitted as the registry's key set (never probed);
|
|
97
|
+
* every body anchor registers a probe; the composition completes only when
|
|
98
|
+
* the probes and the projection's body slots coincide (a drift is a loud
|
|
99
|
+
* throw below, never silent bytes). */
|
|
100
|
+
render() {
|
|
101
|
+
const probe = new Set();
|
|
102
|
+
const lines = this.#compose(probe);
|
|
103
|
+
this.#assertConsumed(probe);
|
|
104
|
+
return this.#join(lines);
|
|
105
|
+
}
|
|
106
|
+
/** Compose the doc-type lines, registering every emitted registered anchor in
|
|
107
|
+
* the probe set (each composition helper probes the anchors it emits). */
|
|
108
|
+
#compose(probe) {
|
|
109
|
+
switch (this.#docType) {
|
|
110
|
+
case "overall-spec":
|
|
111
|
+
return this.#renderOverallSpec(probe);
|
|
112
|
+
case "plan":
|
|
113
|
+
return this.#renderPlan(probe);
|
|
114
|
+
case "phase-spec":
|
|
115
|
+
return this.#renderPhaseSpec(probe);
|
|
116
|
+
case "single-spec":
|
|
117
|
+
return this.#renderSingleSpec(probe);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
/** The slot-consumption invariant — the composition-side tripwire of the
|
|
121
|
+
* registry-derived structure (the finding hardened in: the projection is the
|
|
122
|
+
* single structure source, the hand-written compositions must not drift from
|
|
123
|
+
* it). The assertion domain is the BODY slots — the front-matter head is
|
|
124
|
+
* emitted from the projection's independent emission list (the §2.2
|
|
125
|
+
* structured channel, never probed), so the tripwire covers the
|
|
126
|
+
* hand-assembled body:
|
|
127
|
+
* every required body slot of the projection is emitted by the composition,
|
|
128
|
+
* and no composition probe names an anchor the registry does not require — a
|
|
129
|
+
* registered element with no composition position, or a composed anchor no
|
|
130
|
+
* longer required, is registry drift, loud never silent. */
|
|
131
|
+
#assertConsumed(probe) {
|
|
132
|
+
const registered = new Set(this.#slots.filter((slot) => slot.home !== "frontmatter").map((slot) => slot.anchor));
|
|
133
|
+
const unemitted = this.#slots
|
|
134
|
+
.filter((slot) => slot.home !== "frontmatter" && !probe.has(slot.anchor))
|
|
135
|
+
.map((slot) => slot.anchor);
|
|
136
|
+
if (unemitted.length > 0) {
|
|
137
|
+
throw new Error(`skeleton composition omits the registered required slot(s): ${unemitted.join(", ")}`);
|
|
138
|
+
}
|
|
139
|
+
for (const anchor of probe) {
|
|
140
|
+
if (!registered.has(anchor)) {
|
|
141
|
+
throw new Error(`skeleton composition emits the unregistered anchor: ${anchor}`);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
// -------------------------------------------------------------------------
|
|
146
|
+
// the per-doc-type compositions — the doc section sequence + its scaffolds
|
|
147
|
+
// -------------------------------------------------------------------------
|
|
148
|
+
/** The overall-spec skeleton — the front-matter head, the section sequence
|
|
149
|
+
* (the four table sections, the charter facets, the dependency graph, the
|
|
150
|
+
* Form-A constraints surface and the change-history table): every required
|
|
151
|
+
* overall-spec element lands in its structural position. */
|
|
152
|
+
#renderOverallSpec(probe) {
|
|
153
|
+
const lines = [];
|
|
154
|
+
this.#pushFrontmatter(lines);
|
|
155
|
+
lines.push(...this.#section("## Document scope", [":::fill document-scope"], probe));
|
|
156
|
+
lines.push(...this.#section("## File paths", this.#filePathsTable(probe), probe));
|
|
157
|
+
lines.push(...this.#section("## Program charter", this.#programCharter(probe), probe));
|
|
158
|
+
lines.push(...this.#section("## Issue inventory", this.#issueTable(probe), probe));
|
|
159
|
+
lines.push(...this.#section("## Phase inventory", this.#phaseTable(probe), probe));
|
|
160
|
+
lines.push(...this.#section("## Dependency graph", this.#dependencyGraph(probe), probe));
|
|
161
|
+
lines.push(...this.#section("## Boundary rules", ["- :::fill boundary-rule"], probe));
|
|
162
|
+
// The overall Constraints section — the Form-A delta-only surface shared
|
|
163
|
+
// with the plan/phase-spec: the heading + the `Constraint delta bullet`,
|
|
164
|
+
// composed at the declared registry position (between Boundary rules and
|
|
165
|
+
// Maintenance). The section heading line and its delta bullet land in the
|
|
166
|
+
// SAME composition step — the three same-order parts (the declared section
|
|
167
|
+
// anchor, the composed heading, the composed bullet) must move together, or
|
|
168
|
+
// the `#assertConsumed` tripwire throws (a heading without its bullet omits
|
|
169
|
+
// a registered required slot).
|
|
170
|
+
lines.push(...this.#section("## Constraints", ["- :::fill constraint"], probe, "Constraint delta bullet"));
|
|
171
|
+
lines.push(...this.#section("## Maintenance", ["- :::fill maintenance-note"], probe));
|
|
172
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
173
|
+
return lines;
|
|
174
|
+
}
|
|
175
|
+
/** The plan skeleton — the front-matter head, the constraints section, the first
|
|
176
|
+
* task block (`### Task 1:` with the seven required task fields) and the
|
|
177
|
+
* change-history table (§3.2 — one task block, more blocks appended when
|
|
178
|
+
* filling). */
|
|
179
|
+
#renderPlan(probe) {
|
|
180
|
+
const lines = [];
|
|
181
|
+
this.#pushFrontmatter(lines);
|
|
182
|
+
lines.push(...this.#section("## Constraints", ["- :::fill constraint"], probe, "Constraint delta bullet"));
|
|
183
|
+
lines.push(...this.#taskBlock(probe));
|
|
184
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
185
|
+
return lines;
|
|
186
|
+
}
|
|
187
|
+
/** The phase-spec skeleton — the front-matter head, the Design double layer
|
|
188
|
+
* (one `### 1.` group + one `#### 1.1` item + the acceptance surface), the
|
|
189
|
+
* constraints section and the change-history table (§3.2 — more groups/items
|
|
190
|
+
* appended in numeric order when filling). */
|
|
191
|
+
#renderPhaseSpec(probe) {
|
|
192
|
+
const lines = [];
|
|
193
|
+
this.#pushFrontmatter(lines);
|
|
194
|
+
lines.push(...this.#section("## Design", [
|
|
195
|
+
// The design intro is the Design section's one prose position — a rank-3
|
|
196
|
+
// group heading closes the rank-2 section block, so the intro line (not a
|
|
197
|
+
// blank) is what keeps the section non-hollow.
|
|
198
|
+
":::fill design-intro",
|
|
199
|
+
"",
|
|
200
|
+
"### 1. :::fill group-title",
|
|
201
|
+
"#### 1.1 :::fill item-title",
|
|
202
|
+
"- :::fill item-body",
|
|
203
|
+
"",
|
|
204
|
+
"### Acceptance criteria",
|
|
205
|
+
"",
|
|
206
|
+
"- `:::fill acceptance-entry`",
|
|
207
|
+
], probe, "### N. group heading", "#### N.M item heading", "### Acceptance criteria", "Acceptance entry"));
|
|
208
|
+
lines.push(...this.#section("## Constraints", ["- :::fill constraint"], probe, "Constraint delta bullet"));
|
|
209
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
210
|
+
return lines;
|
|
211
|
+
}
|
|
212
|
+
/** The single-spec skeleton — the front-matter head, the four prose sections
|
|
213
|
+
* (`:::fill` slots) and the change-history table: the lightweight scaffold of
|
|
214
|
+
* the free-form spec (P6 T2 · spec §2.1). No `### N.` double-layer outline and
|
|
215
|
+
* no parent-program key — the single-spec's deliberate deviations from the
|
|
216
|
+
* phase-spec form. */
|
|
217
|
+
#renderSingleSpec(probe) {
|
|
218
|
+
const lines = [];
|
|
219
|
+
this.#pushFrontmatter(lines);
|
|
220
|
+
lines.push(...this.#section("## Background & root cause", [":::fill background-root-cause"], probe));
|
|
221
|
+
lines.push(...this.#section("## Design decisions", [":::fill design-ruling"], probe));
|
|
222
|
+
lines.push(...this.#section("## Acceptance", [":::fill acceptance"], probe));
|
|
223
|
+
lines.push(...this.#section("## Constraints", [":::fill constraints"], probe));
|
|
224
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
225
|
+
return lines;
|
|
226
|
+
}
|
|
227
|
+
// -------------------------------------------------------------------------
|
|
228
|
+
// the shared scaffolds — the front-matter head, tables, sections, the join
|
|
229
|
+
// -------------------------------------------------------------------------
|
|
230
|
+
/** The front-matter head block — the projection's front-matter emission list
|
|
231
|
+
* (the head's required keys plus the type's optional keys) in registry order,
|
|
232
|
+
* emitted by `yaml.stringify` in one call (§2.2's standard structured-metadata
|
|
233
|
+
* channel): §4.2's placeholder three-way split — the link keys a `<…>` scalar,
|
|
234
|
+
* the content keys a `:::fill <key>`, the truth keys their true values. An
|
|
235
|
+
* independent line set — never part of the slot/probe channel (the
|
|
236
|
+
* `#assertConsumed` domain is the body the composition hand-assembles). The
|
|
237
|
+
* head's `doc-type:` key is the canonical machine read (spec §3.1 ⑩ · D34 —
|
|
238
|
+
* the read faces consume the front-matter record, zero header-line marker
|
|
239
|
+
* grammar). */
|
|
240
|
+
#pushFrontmatter(lines) {
|
|
241
|
+
// The front-matter record is emitted by `yaml.stringify` in ONE call over the
|
|
242
|
+
// projection's emission list (spec §2.2's structured channel — the
|
|
243
|
+
// parsed-nodes form keeps the keys ordered and the emission single: D3 quotes
|
|
244
|
+
// the content-fill values so a consumer filling `[human] · …` / `Title: …`
|
|
245
|
+
// into the slot never breaks the scalar (the #341 fill class dies at the
|
|
246
|
+
// skeleton's default form, not at report time). The truth values stay plain,
|
|
247
|
+
// the link placeholders plain (the <>-bookended exemplar — exemption-shaped).
|
|
248
|
+
const fields = new YAMLMap();
|
|
249
|
+
// The emission list is the projection's independent front-matter set — the
|
|
250
|
+
// required head keys plus the type's optional keys (`base` / `depends-on`);
|
|
251
|
+
// `parent-version` never appears (the projection excludes it — §4.2's
|
|
252
|
+
// optional shape-typed key, whose `v<n>.<m>` domain admits no placeholder).
|
|
253
|
+
for (const slot of this.#frontmatterSlots) {
|
|
254
|
+
const value = new Scalar(this.#frontmatterValue(slot));
|
|
255
|
+
// D3: the content fills emit single-quoted — the consumer may fill
|
|
256
|
+
// `[human] · …` / `Title: …` into the slot; the quote keeps the scalar
|
|
257
|
+
// intact regardless of the leading character (the #341 class dies at the
|
|
258
|
+
// skeleton's default form). The truths and the link placeholders stay
|
|
259
|
+
// plain.
|
|
260
|
+
value.type = slot.slot === "content" ? Scalar.QUOTE_SINGLE : Scalar.PLAIN;
|
|
261
|
+
fields.items.push(new Pair(new Scalar(slot.anchor), value));
|
|
262
|
+
}
|
|
263
|
+
const block = stringifyYaml(fields).trimEnd().split("\n");
|
|
264
|
+
lines.push("---", ...block, "---", "");
|
|
265
|
+
}
|
|
266
|
+
/** One front-matter value — the §4.2 placeholder three-way split over the slot
|
|
267
|
+
* kind: the link keys a `<…>` placeholder scalar, the content keys a content
|
|
268
|
+
* fill (`:::fill <key>`), the truth keys (the fixed version/date scaffold and
|
|
269
|
+
* the doc-type / status patterns) their true values. */
|
|
270
|
+
#frontmatterValue(slot) {
|
|
271
|
+
if (slot.slot === "link") {
|
|
272
|
+
const placeholder = FRONT_MATTER_LINKS[slot.anchor];
|
|
273
|
+
if (placeholder === undefined) {
|
|
274
|
+
throw new Error(`no skeleton front-matter link placeholder for the ${slot.anchor} anchor`);
|
|
275
|
+
}
|
|
276
|
+
return placeholder;
|
|
277
|
+
}
|
|
278
|
+
if (slot.slot === "content")
|
|
279
|
+
return `:::fill ${slot.anchor}`;
|
|
280
|
+
return this.#frontmatterTruth(slot);
|
|
281
|
+
}
|
|
282
|
+
/** The true front-matter value of a fixed/patterned front-matter key — the doc
|
|
283
|
+
* type from the projection, the injected run date, the fixed first version and
|
|
284
|
+
* the first legal status literal (`Draft`, the shared head of every status
|
|
285
|
+
* enum domain). An unknown truth key is a registry drift, loud never silent. */
|
|
286
|
+
#frontmatterTruth(slot) {
|
|
287
|
+
switch (slot.anchor) {
|
|
288
|
+
case "doc-type":
|
|
289
|
+
return this.#docType;
|
|
290
|
+
case "version":
|
|
291
|
+
return "v0.1";
|
|
292
|
+
case "date":
|
|
293
|
+
return this.#date;
|
|
294
|
+
case "status":
|
|
295
|
+
return "Draft";
|
|
296
|
+
}
|
|
297
|
+
throw new Error(`no skeleton front-matter truth for the ${slot.anchor} anchor`);
|
|
298
|
+
}
|
|
299
|
+
/** The generator truth of one pattern-typed body slot — an unknown anchor is a
|
|
300
|
+
* registry drift, loud never silent. */
|
|
301
|
+
#truth(anchor) {
|
|
302
|
+
const truth = TRUTH_LINES[anchor];
|
|
303
|
+
if (truth === undefined)
|
|
304
|
+
throw new Error(`no skeleton truth for the ${anchor} anchor`);
|
|
305
|
+
return truth;
|
|
306
|
+
}
|
|
307
|
+
/** One markdown section — the heading (probed as its registered section-heading
|
|
308
|
+
* anchor), a blank, the body and a trailing blank. The body anchors are the
|
|
309
|
+
* registered anchors the body emits beyond the heading (the table rows/cells,
|
|
310
|
+
* the delta bullets, the design-body headings) — every one must be a required
|
|
311
|
+
* slot of the doc type. */
|
|
312
|
+
#section(heading, body, probe, ...bodyAnchors) {
|
|
313
|
+
probe.add(heading);
|
|
314
|
+
for (const anchor of bodyAnchors)
|
|
315
|
+
probe.add(anchor);
|
|
316
|
+
return [heading, "", ...body, ""];
|
|
317
|
+
}
|
|
318
|
+
/** The File-paths artifact table — the two-column header + the minimal one-row
|
|
319
|
+
* scaffold (the backticked path cell keeps the `File path row` shape). */
|
|
320
|
+
#filePathsTable(probe) {
|
|
321
|
+
probe.add("File path row");
|
|
322
|
+
return ["| Artifact | Path |", "| --- | --- |", "| overall-spec | `:::fill overall-path` |"];
|
|
323
|
+
}
|
|
324
|
+
/** The charter facets — the three required `###` facet headings with their
|
|
325
|
+
* content bullets (the optional decision-group / endorsements leaves generate
|
|
326
|
+
* no slot — the optional/conditional zero-gen contract). */
|
|
327
|
+
#programCharter(probe) {
|
|
328
|
+
probe.add("### Goal");
|
|
329
|
+
probe.add("### Non-goals");
|
|
330
|
+
probe.add("### Cross-cutting");
|
|
331
|
+
return [
|
|
332
|
+
"### Goal",
|
|
333
|
+
"",
|
|
334
|
+
"- :::fill goal-description",
|
|
335
|
+
"",
|
|
336
|
+
"### Non-goals",
|
|
337
|
+
"",
|
|
338
|
+
"- :::fill non-goal-description",
|
|
339
|
+
"",
|
|
340
|
+
"### Cross-cutting",
|
|
341
|
+
"",
|
|
342
|
+
"- :::fill cross-cutting-description",
|
|
343
|
+
];
|
|
344
|
+
}
|
|
345
|
+
/** The Issue-inventory table — the registered columns + the minimal row (the `P1`
|
|
346
|
+
* phase cell registers the inventory id, the issue-ref cell the enum's first
|
|
347
|
+
* legal literal (`none`), the title cell a content fill). */
|
|
348
|
+
#issueTable(probe) {
|
|
349
|
+
probe.add("Issue inventory columns");
|
|
350
|
+
probe.add("Issue row");
|
|
351
|
+
probe.add("Issue ref cell");
|
|
352
|
+
return [
|
|
353
|
+
"| Phase | Issue (ref) | Title summary |",
|
|
354
|
+
"| --- | --- | --- |",
|
|
355
|
+
`| P1 | ${this.#truth("Issue ref cell")} | :::fill issue-title |`,
|
|
356
|
+
];
|
|
357
|
+
}
|
|
358
|
+
/** The Phase-inventory table — the registered columns + two rows (the `P1 -> P2`
|
|
359
|
+
* graph edge cross-links both ids, so both phases register; the cells carry the
|
|
360
|
+
* pending-form truths (`[Pending]` design — the design domain's pending form —
|
|
361
|
+
* and `Pending` plan, each legal in its declared domain), the phase-id cell the
|
|
362
|
+
* structural id). */
|
|
363
|
+
#phaseTable(probe) {
|
|
364
|
+
probe.add("Phase inventory columns");
|
|
365
|
+
probe.add("Phase row");
|
|
366
|
+
probe.add("Phase id token");
|
|
367
|
+
probe.add("Implementation plan cell");
|
|
368
|
+
probe.add("Design spec cell");
|
|
369
|
+
probe.add("Dependency cell");
|
|
370
|
+
const phaseRow = `:::fill phase-name | :::fill scope | ${this.#truth("Design spec cell")} | ${this.#truth("Implementation plan cell")} | :::fill acceptance-criteria | :::fill dependency`;
|
|
371
|
+
return [
|
|
372
|
+
"| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
|
|
373
|
+
"| --- | --- | --- | --- | --- | --- | --- |",
|
|
374
|
+
`| P1 | ${phaseRow} |`,
|
|
375
|
+
`| P2 | ${phaseRow} |`,
|
|
376
|
+
];
|
|
377
|
+
}
|
|
378
|
+
/** The Dependency-graph block — the hard-edge truth row + the legend line. */
|
|
379
|
+
#dependencyGraph(probe) {
|
|
380
|
+
probe.add("Hard edge");
|
|
381
|
+
probe.add("Graph legend");
|
|
382
|
+
return [this.#truth("Hard edge"), this.#truth("Graph legend")];
|
|
383
|
+
}
|
|
384
|
+
/** The Change-history table — the header + separator + the first-row scaffold. */
|
|
385
|
+
#historyTable(probe) {
|
|
386
|
+
probe.add("Change history row");
|
|
387
|
+
probe.add("Version token");
|
|
388
|
+
probe.add("Change history date");
|
|
389
|
+
return [HISTORY_HEADER, "| --- | --- | --- | --- |", this.#historyRow()];
|
|
390
|
+
}
|
|
391
|
+
/** The change-history first row — the v0.1 version token (the header version),
|
|
392
|
+
* the injected run date and the summary/author content fills. */
|
|
393
|
+
#historyRow() {
|
|
394
|
+
return `| v0.1 | ${this.#date} | :::fill summary | :::fill author |`;
|
|
395
|
+
}
|
|
396
|
+
/** The first task block — the true-numbered `### Task 1:` heading (the title a
|
|
397
|
+
* content fill) plus the seven required task fields: the content markers with
|
|
398
|
+
* their values, the Steps field with the checkable step form (§3.2), and the
|
|
399
|
+
* `none` DependsOn default. */
|
|
400
|
+
#taskBlock(probe) {
|
|
401
|
+
probe.add("### Task N:");
|
|
402
|
+
probe.add("Task id token");
|
|
403
|
+
probe.add("**Objective**");
|
|
404
|
+
probe.add("**Files**");
|
|
405
|
+
probe.add("File path token");
|
|
406
|
+
probe.add("**Consumes**");
|
|
407
|
+
probe.add("**Produces**");
|
|
408
|
+
probe.add("**Steps**");
|
|
409
|
+
probe.add("Step action");
|
|
410
|
+
probe.add("Step checkable");
|
|
411
|
+
probe.add("**Acceptance**");
|
|
412
|
+
probe.add("**DependsOn**");
|
|
413
|
+
return [
|
|
414
|
+
"### Task 1: :::fill task-title",
|
|
415
|
+
"- **Objective**: :::fill objective",
|
|
416
|
+
"- **Files**: :::fill file-paths",
|
|
417
|
+
"- **Consumes**: :::fill consumes",
|
|
418
|
+
"- **Produces**: :::fill produces",
|
|
419
|
+
"- **Steps**:",
|
|
420
|
+
" - :::fill step-action — checkable: :::fill step-checkable",
|
|
421
|
+
"- **Acceptance**: :::fill acceptance",
|
|
422
|
+
"- **DependsOn**: none",
|
|
423
|
+
"",
|
|
424
|
+
];
|
|
425
|
+
}
|
|
426
|
+
/** Join the assembled lines — the trailing blank of the last section dropped
|
|
427
|
+
* (render() never ends with a blank line or a newline). */
|
|
428
|
+
#join(lines) {
|
|
429
|
+
const out = [...lines];
|
|
430
|
+
while (out.length > 0 && out[out.length - 1] === "")
|
|
431
|
+
out.pop();
|
|
432
|
+
return out.join("\n");
|
|
433
|
+
}
|
|
434
|
+
}
|