@oscaner-skills/cdd-engine 1.0.0 → 2.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.
- package/README.md +9 -8
- package/README.zh-CN.md +9 -8
- package/package.json +15 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/smoke.integration.test.ts +202 -0
- package/src-next/__tests__/zero-dep.test.ts +134 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
- package/src-next/contract/__tests__/declare.test.ts +242 -0
- package/src-next/contract/__tests__/doc.test.ts +358 -0
- package/src-next/contract/__tests__/judge.test.ts +873 -0
- package/src-next/contract/__tests__/lint.test.ts +314 -0
- package/src-next/contract/__tests__/project.test.ts +419 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +983 -0
- package/src-next/contract/doc.ts +753 -0
- package/src-next/contract/invariants.ts +1268 -0
- package/src-next/contract/judge.ts +142 -0
- package/src-next/contract/lint.ts +275 -0
- package/src-next/contract/project.ts +596 -0
- package/src-next/contract/skill-anatomy.ts +273 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +948 -0
- package/src-next/face/__tests__/capsule.test.ts +276 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
- package/src-next/face/__tests__/cli.test.ts +4643 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/projection.test.ts +301 -0
- package/src-next/face/__tests__/sync-runner.test.ts +70 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +195 -0
- package/src-next/face/board-view.ts +662 -0
- package/src-next/face/capsule.ts +149 -0
- package/src-next/face/cli.ts +819 -0
- package/src-next/face/declare.ts +326 -0
- package/src-next/face/gate.ts +170 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +326 -0
- package/src-next/face/lifecycle.ts +700 -0
- package/src-next/face/projection.ts +282 -0
- package/src-next/face/route-render.ts +160 -0
- package/src-next/face/words.ts +296 -0
- package/src-next/infra/__tests__/infra.test.ts +287 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/runtime.ts +185 -0
- package/src-next/infra/workspace.ts +232 -0
- package/src-next/render/__tests__/render.test.ts +499 -0
- package/src-next/render/__tests__/skeleton.test.ts +466 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +159 -0
- package/src-next/render/skeleton.ts +437 -0
- package/src-next/render/templates.ts +650 -0
- package/src-next/session/__tests__/graph.test.ts +270 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +744 -0
- package/src-next/session/__tests__/next.test.ts +368 -0
- package/src-next/session/__tests__/preflight.test.ts +491 -0
- package/src-next/session/__tests__/run.test.ts +1014 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +469 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1004 -0
- package/src-next/session/next.ts +192 -0
- package/src-next/session/preflight.ts +240 -0
- package/src-next/session/run.ts +606 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +18 -20
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/render/issue-body.ts
|
|
2
|
+
// T19 — IssueBodyRenderer (the P7 translation-system render landing): the aggregate
|
|
3
|
+
// issue body's steady renderer, relocated from face/cli.ts (T11's composition root
|
|
4
|
+
// only assembles it — the renderer owns no CLI). The language/label plane is
|
|
5
|
+
// data-driven:
|
|
6
|
+
//
|
|
7
|
+
// · the finding-type vocabulary is the renderer's declared steady set (bug /
|
|
8
|
+
// enhancement / chore — the input contract's type domain);
|
|
9
|
+
// · the language vocabulary is the word table's locale key projection (the langs
|
|
10
|
+
// derivation — localeKeys(), never a hardcoded list);
|
|
11
|
+
// · every label the body emits rides the word table's locale rows through the
|
|
12
|
+
// Translator (the bidirectional layer — localize(canonical, locale) renders the
|
|
13
|
+
// locale-normalized output). The capsule machine face (status · next: ·
|
|
14
|
+
// CDD_BLOCKED:) is deliberately NOT in the locale rows — English-constant, never
|
|
15
|
+
// localized.
|
|
16
|
+
//
|
|
17
|
+
// Module-level exports are types / the class — zero behavior-carrying bare functions.
|
|
18
|
+
|
|
19
|
+
import type { Translator, WordLocaleFace } from "../contract/translate.ts";
|
|
20
|
+
|
|
21
|
+
/** One finding row of the issue-report input. */
|
|
22
|
+
export interface ReportFindingInput {
|
|
23
|
+
type: string;
|
|
24
|
+
lang: string;
|
|
25
|
+
context: string;
|
|
26
|
+
problem: string;
|
|
27
|
+
impact: string;
|
|
28
|
+
suggestedFix: string;
|
|
29
|
+
meta: { skill: string; step: string };
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** The issue-report input contract — the stdin findings plane. */
|
|
33
|
+
export interface IssueReportInput {
|
|
34
|
+
harness: string;
|
|
35
|
+
findings: readonly ReportFindingInput[];
|
|
36
|
+
related?: {
|
|
37
|
+
open?: readonly { issue: number; component: string; reason: string }[];
|
|
38
|
+
closed?: readonly { issue: number }[];
|
|
39
|
+
program?: { issue: number };
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The issue-body renderer — the aggregate issue body's steady renderer (the finding
|
|
45
|
+
* type/lang vocabularies and the segment labels live on the declared data — the type
|
|
46
|
+
* set on the renderer, the locale keys + label rows on the word table, never a second
|
|
47
|
+
* source): Session block → per-finding four-segment blocks with attribution → Dedup
|
|
48
|
+
* (open hits) → Related (closed hits + program). Pure deterministic text.
|
|
49
|
+
*/
|
|
50
|
+
export class IssueBodyRenderer {
|
|
51
|
+
/** The finding-type vocabulary (the canonical type set). */
|
|
52
|
+
readonly types: readonly string[] = ["bug", "enhancement", "chore"];
|
|
53
|
+
/** The four text-segment keys, in the render order. */
|
|
54
|
+
readonly #segments: readonly string[] = ["context", "problem", "impact", "suggestedFix"];
|
|
55
|
+
/** The word table's locale face — the langs projection + the label rows. */
|
|
56
|
+
readonly #words: WordLocaleFace;
|
|
57
|
+
/** The translation layer — the label rows localize through it (locale-normalized render). */
|
|
58
|
+
readonly #translator: Translator;
|
|
59
|
+
|
|
60
|
+
constructor(words: WordLocaleFace, translator: Translator) {
|
|
61
|
+
this.#words = words;
|
|
62
|
+
this.#translator = translator;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The rendered language vocabulary — the word table's locale key projection (the
|
|
66
|
+
* langs derivation: a locale-key change in the word table re-projects this face). */
|
|
67
|
+
langs(): readonly string[] {
|
|
68
|
+
return this.#words.localeKeys();
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** The canonical `meta` bullet lines of one finding (the two attribution rows). */
|
|
72
|
+
#metaOf(meta: { skill: string; step: string }): string {
|
|
73
|
+
return `- Skill: ${meta.skill}\n- Step: ${meta.step}`;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** One finding's segment label — the word table's label row localized to the
|
|
77
|
+
* finding's lang (localize(canonical, locale); an unknown row — impossible under
|
|
78
|
+
* the completeness pin — falls back to the canonical English face). */
|
|
79
|
+
#labelOf(finding: ReportFindingInput, segment: string): string {
|
|
80
|
+
const row = this.#words.localeRow(`${finding.type}.${segment}`);
|
|
81
|
+
if (row === null) return segment;
|
|
82
|
+
return this.#translator.localize(row.en, finding.lang) ?? row.en;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** One finding's block — the four labeled segments plus the attribution. */
|
|
86
|
+
#findingOf(finding: ReportFindingInput): string {
|
|
87
|
+
const parts = this.#segments.map(
|
|
88
|
+
(segment) =>
|
|
89
|
+
`${this.#labelOf(finding, segment)}\n\n${String(finding[segment as keyof ReportFindingInput])}`,
|
|
90
|
+
);
|
|
91
|
+
return [...parts, this.#metaOf(finding.meta)].join("\n\n");
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Render the aggregate issue body — deterministic: the Session block (harness
|
|
95
|
+
* line), the findings in input order, then the Dedup / Related tails. */
|
|
96
|
+
renderBody(input: IssueReportInput): string {
|
|
97
|
+
const parts: string[] = [`# CDD aggregate issue\n\n- Harness: ${input.harness}`];
|
|
98
|
+
for (const finding of input.findings) parts.push(this.#findingOf(finding));
|
|
99
|
+
const open = input.related?.open ?? [];
|
|
100
|
+
if (open.length > 0) {
|
|
101
|
+
parts.push(
|
|
102
|
+
`## Dedup\n${open.map((hit) => `- Dedup → #${hit.issue} (open):${hit.component} · ${hit.reason}`).join("\n")}`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
const closed = input.related?.closed ?? [];
|
|
106
|
+
const program = input.related?.program;
|
|
107
|
+
if (closed.length > 0 || program !== undefined) {
|
|
108
|
+
const lines: string[] = [];
|
|
109
|
+
for (const hit of closed) lines.push(`- Regression / follow-up of #${hit.issue} (closed)`);
|
|
110
|
+
if (program !== undefined) lines.push(`- Program: #${program.issue}`);
|
|
111
|
+
parts.push(`## Related\n${lines.join("\n")}`);
|
|
112
|
+
}
|
|
113
|
+
return parts.join("\n\n");
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** Input-shape validation — the E-3 early-report contract (field paths, empty =
|
|
117
|
+
* pass). The canonical type set and the word-table locale projection are the single
|
|
118
|
+
* declared vocabularies. */
|
|
119
|
+
validateInput(raw: unknown): string[] {
|
|
120
|
+
const errors: string[] = [];
|
|
121
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw))
|
|
122
|
+
return ["input: expected an object with harness / findings / related?"];
|
|
123
|
+
const input = raw as { harness?: unknown; findings?: unknown; related?: unknown };
|
|
124
|
+
if (typeof input.harness !== "string" || input.harness.length === 0)
|
|
125
|
+
errors.push("harness: non-empty string required");
|
|
126
|
+
if (!Array.isArray(input.findings) || input.findings.length === 0) {
|
|
127
|
+
errors.push("findings: non-empty array of findings required");
|
|
128
|
+
} else {
|
|
129
|
+
input.findings.forEach((rawFinding, i) => {
|
|
130
|
+
const finding = rawFinding as Record<string, unknown> | null;
|
|
131
|
+
const base = `findings[${i}]`;
|
|
132
|
+
if (typeof finding !== "object" || finding === null) {
|
|
133
|
+
errors.push(
|
|
134
|
+
`${base}: object with type/lang/context/problem/impact/suggestedFix/meta expected`,
|
|
135
|
+
);
|
|
136
|
+
return;
|
|
137
|
+
}
|
|
138
|
+
if (!this.types.includes(String(finding.type)))
|
|
139
|
+
errors.push(`${base}.type: must be one of ${this.types.join(" | ")}`);
|
|
140
|
+
if (!this.langs().includes(String(finding.lang)))
|
|
141
|
+
errors.push(`${base}.lang: must be one of ${this.langs().join(" | ")}`);
|
|
142
|
+
for (const field of this.#segments) {
|
|
143
|
+
if (typeof finding[field] !== "string" || (finding[field] as string).length === 0)
|
|
144
|
+
errors.push(`${base}.${field}: non-empty string required`);
|
|
145
|
+
}
|
|
146
|
+
const meta = finding.meta as Record<string, unknown> | null | undefined;
|
|
147
|
+
if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
|
|
148
|
+
errors.push(`${base}.meta: object with skill / step required`);
|
|
149
|
+
} else {
|
|
150
|
+
if (typeof meta.skill !== "string" || meta.skill.length === 0)
|
|
151
|
+
errors.push(`${base}.meta.skill: non-empty string required`);
|
|
152
|
+
if (typeof meta.step !== "string" || meta.step.length === 0)
|
|
153
|
+
errors.push(`${base}.meta.step: non-empty string required`);
|
|
154
|
+
}
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
return errors;
|
|
158
|
+
}
|
|
159
|
+
}
|
|
@@ -0,0 +1,437 @@
|
|
|
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 per-anchor forms (header lines · link placeholders · generator truths ·
|
|
12
|
+
// table scaffolds) are declared constant data below; the document composition
|
|
13
|
+
// walks them in document order. render() is a pure byte renderer — it never
|
|
14
|
+
// appends a trailing newline (the CLI appends the single `\n`, so a redirected
|
|
15
|
+
// fixture ends with exactly one newline). The composition is the judgment site
|
|
16
|
+
// of the projection: after assembly render() asserts slot consumption — every
|
|
17
|
+
// registered required slot emits a probe and every probe names a registered
|
|
18
|
+
// slot, so a registry/composition drift is a loud throw in the renderer, never a
|
|
19
|
+
// silent byte gap (the doc-contract pin judges the rendered bytes; this asserts
|
|
20
|
+
// the same coverage in-process, before any bytes are produced).
|
|
21
|
+
//
|
|
22
|
+
// Module-level exports are types / the class — zero behavior-carrying bare
|
|
23
|
+
// functions (the plan's zero-bare-function discipline).
|
|
24
|
+
|
|
25
|
+
import type { DocSkeleton, SkeletonSlot } from "../contract/project.ts";
|
|
26
|
+
|
|
27
|
+
/** The per-anchor header line forms — every registered header anchor of the four
|
|
28
|
+
* doc types except the link-typed anchors (their placeholder-link lines assemble
|
|
29
|
+
* from LINK_SLOTS): the title fill, the content marker fills, the generator-truth
|
|
30
|
+
* status line and the scaffold version row. The `{date}` slot carries the
|
|
31
|
+
* injected run date (the version-row date truth). */
|
|
32
|
+
const HEADER_FORMS: Record<string, string> = {
|
|
33
|
+
"# Title": "# :::fill title",
|
|
34
|
+
"**Version**": "- **Version**: v0.1 · {date}",
|
|
35
|
+
"**Author**": "- **Author**: :::fill author",
|
|
36
|
+
"**Constraints**": "- **Constraints**: :::fill constraints",
|
|
37
|
+
"**Depends on**": "- **Depends on**: :::fill depends-on",
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/** The placeholder-link literals of the link-typed anchor slots (spec §4.1) — the
|
|
41
|
+
* `<…>` label/target pairs of the parent-program / spec links. The `<…>`-shaped
|
|
42
|
+
* target rides the judge's placeholder-exemption chain (file-existence /
|
|
43
|
+
* sibling-scan); the plan's Class-A `**Spec:**` takes label == target so the
|
|
44
|
+
* `label == basename` chain check holds. */
|
|
45
|
+
const LINK_SLOTS: Record<string, { label: string; target: string }> = {
|
|
46
|
+
"**Parent program**": { label: "<parent overall>", target: "<parent path>" },
|
|
47
|
+
"**Spec:**": { label: "<spec path>", target: "<spec path>" },
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
/** The generator truths of the pattern-typed slots (spec §3.2/§4.1) — hand-pinned
|
|
51
|
+
* legal literals consistent with each declared value domain (`**Status**` →
|
|
52
|
+
* Draft, the first legal literal of its enum; the `none` issue-ref default; the
|
|
53
|
+
* `[Pending]` design cell — the only pending form its valuePattern admits, never
|
|
54
|
+
* bare `Pending` — and the bare `Pending` plan cell, a legal alternative of its
|
|
55
|
+
* domain) and the conforming graph rows (the `P1 -> P2` hard edge + the legend
|
|
56
|
+
* line). These are derived true values, guarded by the doc-contract pins that
|
|
57
|
+
* judge the rendered bytes — never fill positions. */
|
|
58
|
+
const TRUTH_LINES: Record<string, string> = {
|
|
59
|
+
"**Status**": "Draft",
|
|
60
|
+
"Issue ref cell": "none",
|
|
61
|
+
"Implementation plan cell": "Pending",
|
|
62
|
+
"Design spec cell": "[Pending]",
|
|
63
|
+
"Hard edge": "P1 -> P2",
|
|
64
|
+
"Graph legend": "- `->` = hard block",
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
/** The change-history table scaffold — the registered `Change history row` /
|
|
68
|
+
* `Version token` / `Change history date` cells composed into the shared
|
|
69
|
+
* header + separator + first-row shape (the version row must equal the header
|
|
70
|
+
* version — v0.1 — and stay version-ascending, spec §3.2). */
|
|
71
|
+
const HISTORY_HEADER = "| Version | date | summary | author |";
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The skeleton assembler — one DocSkeleton (contract/project.ts, the required-only
|
|
75
|
+
* sixth projection) → the markdown skeleton bytes. Constructed on the projection
|
|
76
|
+
* and the run date (the CLI injects the run day; tests inject a fixed date), the
|
|
77
|
+
* instance is stateless after construction, so sharing one instance composes
|
|
78
|
+
* safely. The composition per doc type mirrors the doc's section sequence; every
|
|
79
|
+
* required element of the type lands in its structural position (the doc-contract
|
|
80
|
+
* pin judges the rendered bytes — a missing required anchor is a finding).
|
|
81
|
+
*/
|
|
82
|
+
export class SkeletonAssembler {
|
|
83
|
+
/** The doc type of the projected skeleton. */
|
|
84
|
+
readonly #docType: DocSkeleton["docType"];
|
|
85
|
+
/** The injected run date — the version-row date truth (`YYYY-MM-DD`). */
|
|
86
|
+
readonly #date: string;
|
|
87
|
+
/** The projection's slots in shape-group order. */
|
|
88
|
+
readonly #slots: readonly SkeletonSlot[];
|
|
89
|
+
|
|
90
|
+
constructor(projection: DocSkeleton, date: string) {
|
|
91
|
+
this.#docType = projection.docType;
|
|
92
|
+
this.#date = date;
|
|
93
|
+
this.#slots = projection.slots;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Render the doc skeleton's markdown bytes — no trailing newline (the CLI owns
|
|
97
|
+
* the appended `\n`; the EOF-newline rule lands on the redirected fixture).
|
|
98
|
+
* Every composed anchor registers a probe; the composition completes only when
|
|
99
|
+
* the probes and the projection's required slots coincide (a drift is a loud
|
|
100
|
+
* throw below, never silent bytes). */
|
|
101
|
+
render(): string {
|
|
102
|
+
const probe = new Set<string>();
|
|
103
|
+
const lines: string[] = this.#compose(probe);
|
|
104
|
+
this.#assertConsumed(probe);
|
|
105
|
+
return this.#join(lines);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** Compose the doc-type lines, registering every emitted registered anchor in
|
|
109
|
+
* the probe set (each composition helper probes the anchors it emits). */
|
|
110
|
+
#compose(probe: Set<string>): string[] {
|
|
111
|
+
switch (this.#docType) {
|
|
112
|
+
case "overall-spec":
|
|
113
|
+
return this.#renderOverallSpec(probe);
|
|
114
|
+
case "plan":
|
|
115
|
+
return this.#renderPlan(probe);
|
|
116
|
+
case "phase-spec":
|
|
117
|
+
return this.#renderPhaseSpec(probe);
|
|
118
|
+
case "single-spec":
|
|
119
|
+
return this.#renderSingleSpec(probe);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** The slot-consumption invariant — the composition-side tripwire of the
|
|
124
|
+
* registry-derived structure (the finding hardened in: the projection is the
|
|
125
|
+
* single structure source, the hand-written compositions must not drift from
|
|
126
|
+
* it): every required slot of the projection is emitted by the composition,
|
|
127
|
+
* and no composition probe names an anchor the registry does not require — a
|
|
128
|
+
* registered element with no composition position, or a composed anchor no
|
|
129
|
+
* longer required, is registry drift, loud never silent. */
|
|
130
|
+
#assertConsumed(probe: ReadonlySet<string>): void {
|
|
131
|
+
const registered = new Set(this.#slots.map((slot) => slot.anchor));
|
|
132
|
+
const unemitted = this.#slots
|
|
133
|
+
.filter((slot) => !probe.has(slot.anchor))
|
|
134
|
+
.map((slot) => slot.anchor);
|
|
135
|
+
if (unemitted.length > 0) {
|
|
136
|
+
throw new Error(
|
|
137
|
+
`skeleton composition omits the registered required slot(s): ${unemitted.join(", ")}`,
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
for (const anchor of probe) {
|
|
141
|
+
if (!registered.has(anchor)) {
|
|
142
|
+
throw new Error(`skeleton composition emits the unregistered anchor: ${anchor}`);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
// -------------------------------------------------------------------------
|
|
148
|
+
// the per-doc-type compositions — the doc section sequence + its scaffolds
|
|
149
|
+
// -------------------------------------------------------------------------
|
|
150
|
+
|
|
151
|
+
/** The overall-spec skeleton — the header tuple, the section sequence (the four table
|
|
152
|
+
* sections, the charter facets and the dependency graph) and the change-history
|
|
153
|
+
* table: every required overall-spec element lands in its structural position. */
|
|
154
|
+
#renderOverallSpec(probe: Set<string>): string[] {
|
|
155
|
+
const lines: string[] = [];
|
|
156
|
+
this.#pushHeader(lines, probe);
|
|
157
|
+
lines.push(...this.#section("## Document scope", [":::fill document-scope"], probe));
|
|
158
|
+
lines.push(...this.#section("## File paths", this.#filePathsTable(probe), probe));
|
|
159
|
+
lines.push(...this.#section("## Program charter", this.#programCharter(probe), probe));
|
|
160
|
+
lines.push(...this.#section("## Issue inventory", this.#issueTable(probe), probe));
|
|
161
|
+
lines.push(...this.#section("## Phase inventory", this.#phaseTable(probe), probe));
|
|
162
|
+
lines.push(...this.#section("## Dependency graph", this.#dependencyGraph(probe), probe));
|
|
163
|
+
lines.push(...this.#section("## Boundary rules", ["- :::fill boundary-rule"], probe));
|
|
164
|
+
lines.push(...this.#section("## Maintenance", ["- :::fill maintenance-note"], probe));
|
|
165
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
166
|
+
return lines;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** The plan skeleton — the header tuple, the constraints section, the first task
|
|
170
|
+
* block (`### Task 1:` with the seven required task fields) and the
|
|
171
|
+
* change-history table (§3.2 — one task block, more blocks appended when
|
|
172
|
+
* filling). */
|
|
173
|
+
#renderPlan(probe: Set<string>): string[] {
|
|
174
|
+
const lines: string[] = [];
|
|
175
|
+
this.#pushHeader(lines, probe);
|
|
176
|
+
lines.push(
|
|
177
|
+
...this.#section(
|
|
178
|
+
"## Constraints",
|
|
179
|
+
["- :::fill constraint"],
|
|
180
|
+
probe,
|
|
181
|
+
"Constraint delta bullet",
|
|
182
|
+
),
|
|
183
|
+
);
|
|
184
|
+
lines.push(...this.#taskBlock(probe));
|
|
185
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
186
|
+
return lines;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** The phase-spec skeleton — the header five-tuple, the Design double layer
|
|
190
|
+
* (one `### 1.` group + one `#### 1.1` item + the acceptance surface), the
|
|
191
|
+
* constraints section and the change-history table (§3.2 — more groups/items
|
|
192
|
+
* appended in numeric order when filling). */
|
|
193
|
+
#renderPhaseSpec(probe: Set<string>): string[] {
|
|
194
|
+
const lines: string[] = [];
|
|
195
|
+
this.#pushHeader(lines, probe);
|
|
196
|
+
lines.push(
|
|
197
|
+
...this.#section(
|
|
198
|
+
"## Design",
|
|
199
|
+
[
|
|
200
|
+
// The design intro is the Design section's one prose position — a rank-3
|
|
201
|
+
// group heading closes the rank-2 section block, so the intro line (not a
|
|
202
|
+
// blank) is what keeps the section non-hollow.
|
|
203
|
+
":::fill design-intro",
|
|
204
|
+
"",
|
|
205
|
+
"### 1. :::fill group-title",
|
|
206
|
+
"#### 1.1 :::fill item-title",
|
|
207
|
+
"- :::fill item-body",
|
|
208
|
+
"",
|
|
209
|
+
"### Acceptance criteria",
|
|
210
|
+
"",
|
|
211
|
+
"- `:::fill acceptance-entry`",
|
|
212
|
+
],
|
|
213
|
+
probe,
|
|
214
|
+
"### N. group heading",
|
|
215
|
+
"#### N.M item heading",
|
|
216
|
+
"### Acceptance criteria",
|
|
217
|
+
"Acceptance entry",
|
|
218
|
+
),
|
|
219
|
+
);
|
|
220
|
+
lines.push(
|
|
221
|
+
...this.#section(
|
|
222
|
+
"## Constraints",
|
|
223
|
+
["- :::fill constraint"],
|
|
224
|
+
probe,
|
|
225
|
+
"Constraint delta bullet",
|
|
226
|
+
),
|
|
227
|
+
);
|
|
228
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
229
|
+
return lines;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** The single-spec skeleton — the header five-tuple, the four prose sections
|
|
233
|
+
* (`:::fill` slots) and the change-history table: the lightweight scaffold of
|
|
234
|
+
* the free-form spec (P6 T2 · spec §2.1). No `### N.` double-layer outline and
|
|
235
|
+
* no `**Parent program**` — the single-spec's deliberate deviations from the
|
|
236
|
+
* phase-spec form. */
|
|
237
|
+
#renderSingleSpec(probe: Set<string>): string[] {
|
|
238
|
+
const lines: string[] = [];
|
|
239
|
+
this.#pushHeader(lines, probe);
|
|
240
|
+
lines.push(
|
|
241
|
+
...this.#section("## Background & root cause", [":::fill background-root-cause"], probe),
|
|
242
|
+
);
|
|
243
|
+
lines.push(...this.#section("## Design decisions", [":::fill design-ruling"], probe));
|
|
244
|
+
lines.push(...this.#section("## Acceptance", [":::fill acceptance"], probe));
|
|
245
|
+
lines.push(...this.#section("## Constraints", [":::fill constraints"], probe));
|
|
246
|
+
lines.push(...this.#section("## Change history", this.#historyTable(probe), probe));
|
|
247
|
+
return lines;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
// -------------------------------------------------------------------------
|
|
251
|
+
// the shared scaffolds — header, tables, sections, the join
|
|
252
|
+
// -------------------------------------------------------------------------
|
|
253
|
+
|
|
254
|
+
/** The header block — the header-home slots in projection order (the registry
|
|
255
|
+
* order — the title, then the version/status truths, the content markers, the
|
|
256
|
+
* link placeholders), each probed, followed by the blank separator. */
|
|
257
|
+
#pushHeader(lines: string[], probe: Set<string>): void {
|
|
258
|
+
for (const slot of this.#slots) {
|
|
259
|
+
if (slot.home !== "header") continue;
|
|
260
|
+
lines.push(this.#headerLine(slot));
|
|
261
|
+
probe.add(slot.anchor);
|
|
262
|
+
}
|
|
263
|
+
lines.push("");
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
/** One header line — the anchor's declared form with the injected date (the
|
|
267
|
+
* link-typed anchors assemble their placeholder-link line from the LINK_SLOTS
|
|
268
|
+
* label/target pair; the header anchors are a closed set over the four
|
|
269
|
+
* registries — an unknown header anchor is a registry drift, loud never
|
|
270
|
+
* silent). */
|
|
271
|
+
#headerLine(slot: SkeletonSlot): string {
|
|
272
|
+
if (slot.slot === "link") {
|
|
273
|
+
const pair = LINK_SLOTS[slot.anchor];
|
|
274
|
+
if (pair === undefined) {
|
|
275
|
+
throw new Error(`no skeleton link slot for the ${slot.anchor} anchor`);
|
|
276
|
+
}
|
|
277
|
+
const marker = slot.anchor === "**Spec:**" ? "**Spec:**" : `- ${slot.anchor}:`;
|
|
278
|
+
return `${marker} [${pair.label}](${pair.target})`;
|
|
279
|
+
}
|
|
280
|
+
if (slot.anchor === "**Status**") {
|
|
281
|
+
return `- **Status**: ${this.#truth("**Status**")}`;
|
|
282
|
+
}
|
|
283
|
+
const form = HEADER_FORMS[slot.anchor];
|
|
284
|
+
if (form === undefined) {
|
|
285
|
+
throw new Error(`no skeleton header form for the ${slot.anchor} anchor`);
|
|
286
|
+
}
|
|
287
|
+
return form.replace("{date}", this.#date);
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/** The generator truth of one pattern-typed slot — an unknown anchor is a
|
|
291
|
+
* registry drift, loud never silent. */
|
|
292
|
+
#truth(anchor: string): string {
|
|
293
|
+
const truth = TRUTH_LINES[anchor];
|
|
294
|
+
if (truth === undefined) throw new Error(`no skeleton truth for the ${anchor} anchor`);
|
|
295
|
+
return truth;
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/** One markdown section — the heading (probed as its registered section-heading
|
|
299
|
+
* anchor), a blank, the body and a trailing blank. The body anchors are the
|
|
300
|
+
* registered anchors the body emits beyond the heading (the table rows/cells,
|
|
301
|
+
* the delta bullets, the design-body headings) — every one must be a required
|
|
302
|
+
* slot of the doc type. */
|
|
303
|
+
#section(
|
|
304
|
+
heading: string,
|
|
305
|
+
body: readonly string[],
|
|
306
|
+
probe: Set<string>,
|
|
307
|
+
...bodyAnchors: string[]
|
|
308
|
+
): string[] {
|
|
309
|
+
probe.add(heading);
|
|
310
|
+
for (const anchor of bodyAnchors) probe.add(anchor);
|
|
311
|
+
return [heading, "", ...body, ""];
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/** The File-paths artifact table — the two-column header + the minimal one-row
|
|
315
|
+
* scaffold (the backticked path cell keeps the `File path row` shape). */
|
|
316
|
+
#filePathsTable(probe: Set<string>): string[] {
|
|
317
|
+
probe.add("File path row");
|
|
318
|
+
return ["| Artifact | Path |", "| --- | --- |", "| overall-spec | `:::fill overall-path` |"];
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** The charter facets — the three required `###` facet headings with their
|
|
322
|
+
* content bullets (the optional decision-group / endorsements leaves generate
|
|
323
|
+
* no slot — the optional/conditional zero-gen contract). */
|
|
324
|
+
#programCharter(probe: Set<string>): string[] {
|
|
325
|
+
probe.add("### Goal");
|
|
326
|
+
probe.add("### Non-goals");
|
|
327
|
+
probe.add("### Cross-cutting");
|
|
328
|
+
return [
|
|
329
|
+
"### Goal",
|
|
330
|
+
"",
|
|
331
|
+
"- :::fill goal-description",
|
|
332
|
+
"",
|
|
333
|
+
"### Non-goals",
|
|
334
|
+
"",
|
|
335
|
+
"- :::fill non-goal-description",
|
|
336
|
+
"",
|
|
337
|
+
"### Cross-cutting",
|
|
338
|
+
"",
|
|
339
|
+
"- :::fill cross-cutting-description",
|
|
340
|
+
];
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/** The Issue-inventory table — the registered columns + the minimal row (the `P1`
|
|
344
|
+
* phase cell registers the inventory id, the issue-ref cell the enum's first
|
|
345
|
+
* legal literal (`none`), the title cell a content fill). */
|
|
346
|
+
#issueTable(probe: Set<string>): string[] {
|
|
347
|
+
probe.add("Issue inventory columns");
|
|
348
|
+
probe.add("Issue row");
|
|
349
|
+
probe.add("Issue ref cell");
|
|
350
|
+
return [
|
|
351
|
+
"| Phase | Issue (ref) | Title summary |",
|
|
352
|
+
"| --- | --- | --- |",
|
|
353
|
+
`| P1 | ${this.#truth("Issue ref cell")} | :::fill issue-title |`,
|
|
354
|
+
];
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
/** The Phase-inventory table — the registered columns + two rows (the `P1 -> P2`
|
|
358
|
+
* graph edge cross-links both ids, so both phases register; the cells carry the
|
|
359
|
+
* pending-form truths (`[Pending]` design — the design domain's pending form —
|
|
360
|
+
* and `Pending` plan, each legal in its declared domain), the phase-id cell the
|
|
361
|
+
* structural id). */
|
|
362
|
+
#phaseTable(probe: Set<string>): string[] {
|
|
363
|
+
probe.add("Phase inventory columns");
|
|
364
|
+
probe.add("Phase row");
|
|
365
|
+
probe.add("Phase id token");
|
|
366
|
+
probe.add("Implementation plan cell");
|
|
367
|
+
probe.add("Design spec cell");
|
|
368
|
+
probe.add("Dependency cell");
|
|
369
|
+
const phaseRow = `:::fill phase-name | :::fill scope | ${this.#truth("Design spec cell")} | ${this.#truth("Implementation plan cell")} | :::fill acceptance-criteria | :::fill dependency`;
|
|
370
|
+
return [
|
|
371
|
+
"| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
|
|
372
|
+
"| --- | --- | --- | --- | --- | --- | --- |",
|
|
373
|
+
`| P1 | ${phaseRow} |`,
|
|
374
|
+
`| P2 | ${phaseRow} |`,
|
|
375
|
+
];
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
/** The Dependency-graph block — the hard-edge truth row + the legend line. */
|
|
379
|
+
#dependencyGraph(probe: Set<string>): string[] {
|
|
380
|
+
probe.add("Hard edge");
|
|
381
|
+
probe.add("Graph legend");
|
|
382
|
+
return [this.#truth("Hard edge"), this.#truth("Graph legend")];
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
/** The Change-history table — the header + separator + the first-row scaffold. */
|
|
386
|
+
#historyTable(probe: Set<string>): string[] {
|
|
387
|
+
probe.add("Change history row");
|
|
388
|
+
probe.add("Version token");
|
|
389
|
+
probe.add("Change history date");
|
|
390
|
+
return [HISTORY_HEADER, "| --- | --- | --- | --- |", this.#historyRow()];
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/** The change-history first row — the v0.1 version token (the header version),
|
|
394
|
+
* the injected run date and the summary/author content fills. */
|
|
395
|
+
#historyRow(): string {
|
|
396
|
+
return `| v0.1 | ${this.#date} | :::fill summary | :::fill author |`;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/** The first task block — the true-numbered `### Task 1:` heading (the title a
|
|
400
|
+
* content fill) plus the seven required task fields: the content markers with
|
|
401
|
+
* their values, the Steps field with the checkable step form (§3.2), and the
|
|
402
|
+
* `none` DependsOn default. */
|
|
403
|
+
#taskBlock(probe: Set<string>): string[] {
|
|
404
|
+
probe.add("### Task N:");
|
|
405
|
+
probe.add("Task id token");
|
|
406
|
+
probe.add("**Objective**");
|
|
407
|
+
probe.add("**Files**");
|
|
408
|
+
probe.add("File path token");
|
|
409
|
+
probe.add("**Consumes**");
|
|
410
|
+
probe.add("**Produces**");
|
|
411
|
+
probe.add("**Steps**");
|
|
412
|
+
probe.add("Step action");
|
|
413
|
+
probe.add("Step checkable");
|
|
414
|
+
probe.add("**Acceptance**");
|
|
415
|
+
probe.add("**DependsOn**");
|
|
416
|
+
return [
|
|
417
|
+
"### Task 1: :::fill task-title",
|
|
418
|
+
"- **Objective**: :::fill objective",
|
|
419
|
+
"- **Files**: :::fill file-paths",
|
|
420
|
+
"- **Consumes**: :::fill consumes",
|
|
421
|
+
"- **Produces**: :::fill produces",
|
|
422
|
+
"- **Steps**:",
|
|
423
|
+
" - :::fill step-action — checkable: :::fill step-checkable",
|
|
424
|
+
"- **Acceptance**: :::fill acceptance",
|
|
425
|
+
"- **DependsOn**: none",
|
|
426
|
+
"",
|
|
427
|
+
];
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
/** Join the assembled lines — the trailing blank of the last section dropped
|
|
431
|
+
* (render() never ends with a blank line or a newline). */
|
|
432
|
+
#join(lines: readonly string[]): string {
|
|
433
|
+
const out = [...lines];
|
|
434
|
+
while (out.length > 0 && out[out.length - 1] === "") out.pop();
|
|
435
|
+
return out.join("\n");
|
|
436
|
+
}
|
|
437
|
+
}
|