@oscaner-skills/cdd-engine 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,656 +0,0 @@
1
- // packages/cdd-engine/src-next/contract/project.ts
2
- // T3 — the projection face: the six derived surfaces (shape / schema / slices /
3
- // tokens / reference / skeleton) are projected from the declared registries
4
- // (declare.ts) through one shared derivation chain.
5
- //
6
- // Every surface is pure derivation from the registries injected at construction —
7
- // zero hand-written shape prose, zero duplicated data. The chain: each registry
8
- // row is projected onto a derived identity (anchor · presence · ref-kind · home ·
9
- // value pattern), and the six projection methods each select the face their
10
- // consumers need:
11
- // · shape — the section skeleton: registry rows grouped by home surface
12
- // in first-occurrence order (the interpreter's structure walk);
13
- // · schema — a JSON Schema per doc type (properties keyed by anchor, the
14
- // required set from the required-presence elements, property
15
- // descriptions carrying presence · home · ref-kind);
16
- // · slices — the parse face: every element's anchor-literal slice plus the
17
- // declared value pattern compiled for line/cell matching.
18
- // Frontmatter-home elements are exempt from both compilations —
19
- // their anchor is a YAML key, looked up directly against the
20
- // parsed front-matter, never scanned line-by-line (§3.3);
21
- // · tokens — the flat anchor lexicon, one token per registered element;
22
- // · reference — the per-element reference vocabulary (ref-kind + value
23
- // pattern), one entry per registered element;
24
- // · skeleton — the doc-skeleton face (spec §4.1/§4.2): every required
25
- // element classified into its placeholder-anchoring slot kind
26
- // (content / link / numeric-heading / generator-truth /
27
- // table-header / table-row / scaffold) in shape-group order,
28
- // plus the independent front-matter emission list (the head's
29
- // required + optional keys) — the skeleton the
30
- // `cdd schema get <type> --output skeleton` render face (D19)
31
- // assembles.
32
- //
33
- // The module's whole behavior surface is the Projector class (the zero-bare-
34
- // function discipline: module-level exports are types / the class — the projection
35
- // helpers and the escape primitive are private members). The schema/shape bytes are
36
- // pinned from the new tree's first version by the test suite (byte snapshots) —
37
- // both serializations are insertion-order deterministic, so the pinned bytes are
38
- // stable across runs.
39
-
40
- import type {
41
- DeclaredRegistries,
42
- DocType,
43
- ElementRegistry,
44
- Home,
45
- Presence,
46
- RefKind,
47
- RegistryElement,
48
- } from "./declare.ts";
49
- import { DOC_TYPE_VALUES } from "./declare.ts";
50
-
51
- /** The projection record keys — the declared-registries record shape ({ "overall-spec",
52
- * plan, "phase-spec", "single-spec" }). Derived from the ONE declaration root
53
- * (declare.ts): the `DocKey` type aliases `DocType` and the runtime `DOC_KEYS`
54
- * tuple aliases `DOC_TYPE_VALUES`, so the value domain has a single source (spec
55
- * §3.2 ③) — judge/declare/board-view all consume these, never a second copy. */
56
- export type DocKey = DocType;
57
-
58
- /** The four doc-type record keys in canonical order — the runtime companion of
59
- * `DocKey`, re-exported from the declaration root (declare.ts `DOC_TYPE_VALUES`).
60
- * The judge's policy composition and the board's declaration domain read THIS
61
- * tuple; a value drift is impossible (one array). */
62
- export const DOC_KEYS = DOC_TYPE_VALUES;
63
-
64
- // ---------------------------------------------------------------------------
65
- // shared derivation chain
66
- // ---------------------------------------------------------------------------
67
-
68
- /** The derived identity of one declared element — the chain root every projection selects from. */
69
- interface DerivedElement {
70
- /** The machine anchor token the element keys on. */
71
- anchor: string;
72
- /** Whether a conforming document must carry the element. */
73
- presence: Presence;
74
- /** The referential kind the element participates in — "none" for presence-only elements. */
75
- refKind: RefKind;
76
- /** The document surface the anchor lives in. */
77
- home: Home;
78
- /** The declared value shape, when the element carries one. */
79
- valuePattern?: string;
80
- }
81
-
82
- // ---------------------------------------------------------------------------
83
- // shape — the section skeleton
84
- // ---------------------------------------------------------------------------
85
-
86
- /** One projected shape element — the structural identity of a registered element. */
87
- export interface ShapeElement {
88
- /** The machine anchor token. */
89
- anchor: string;
90
- /** Whether the conforming document must carry the element. */
91
- presence: Presence;
92
- /** The referential kind the element participates in. */
93
- refKind: RefKind;
94
- }
95
-
96
- /** One section skeleton group — the registered elements of one home surface, in registry order. */
97
- export interface ShapeGroup {
98
- /** The document surface the group collects (header, section, facet, table, …). */
99
- home: Home;
100
- /** The surface's elements, in registry order. */
101
- elements: readonly ShapeElement[];
102
- }
103
-
104
- /** One doc type's shape projection — its section structure grouped by home surface. */
105
- export interface DocShape {
106
- /** The doc-type identity the projection derives from. */
107
- docType: DocType;
108
- /** The section skeleton: non-empty groups in first home-occurrence order. */
109
- structure: readonly ShapeGroup[];
110
- }
111
-
112
- // ---------------------------------------------------------------------------
113
- // schema — the JSON Schema face
114
- // ---------------------------------------------------------------------------
115
-
116
- /** One schema property — a registered element's value shape as a JSON Schema property. */
117
- export interface SchemaProperty {
118
- /** Every declared element's line/cell is a string. */
119
- type: "string";
120
- /** The declared value pattern — matches the element's line/cell in a conforming document. */
121
- pattern: string;
122
- /** The property description — the element's identity (presence · home · ref). */
123
- description: string;
124
- }
125
-
126
- /** One doc type's derived JSON Schema — one property per registered element that declares a value pattern; the required set is the required-presence anchors. */
127
- export interface DocSchema {
128
- /** The doc-type identity the projection derives from. */
129
- docType: DocType;
130
- /** The JSON Schema draft the structure targets. */
131
- $schema: string;
132
- /** Derived doc-type label. */
133
- title: string;
134
- /** Derived summary of the projected structure (element and required counts). */
135
- description: string;
136
- /** The manifest is an object over the declared anchor keys. */
137
- type: "object";
138
- /** One property per registered element that declares a value pattern, in registry order (required-presence anchors appear in `required` regardless of a declared pattern). */
139
- properties: Record<string, SchemaProperty>;
140
- /** The anchors a conforming document must carry, in registry order. */
141
- required: string[];
142
- }
143
-
144
- // ---------------------------------------------------------------------------
145
- // slices — the parse face
146
- // ---------------------------------------------------------------------------
147
-
148
- /** One element's parse face — the anchor-literal slice plus the declared value slice. */
149
- export interface ElementSlice {
150
- /** The machine anchor token the slice parses. */
151
- anchor: string;
152
- /** Whether a conforming document must carry the element. */
153
- presence: Presence;
154
- /** The document surface the anchor lives in. */
155
- home: Home;
156
- /**
157
- * The anchor-literal slice — the escaped anchor compiled for body surfaces
158
- * (home !== "frontmatter"). It parses the anchor itself (each slice parses its
159
- * own anchor) and locates the literal token inside a document line.
160
- * Frontmatter-home elements carry no compiled pattern — their anchor is a YAML
161
- * key, looked up directly against the parsed front-matter, never a line scan
162
- * (§3.3).
163
- */
164
- anchorPattern?: RegExp;
165
- /** The value slice — the declared value pattern compiled for body surfaces;
166
- * undefined on frontmatter-home elements (their values are judged against the
167
- * declared scalar pattern in the registry, not a compiled line slice). */
168
- valuePattern?: RegExp;
169
- }
170
-
171
- /** One doc type's parse face — one slice per registered element, in registry order. */
172
- export interface DocSlices {
173
- /** The doc-type identity the projection derives from. */
174
- docType: DocType;
175
- /** The slice rows, in registry order. */
176
- slices: readonly ElementSlice[];
177
- }
178
-
179
- // ---------------------------------------------------------------------------
180
- // tokens — the anchor lexicon
181
- // ---------------------------------------------------------------------------
182
-
183
- /** One projected token — an anchor of the doc-type vocabulary. */
184
- export interface DocToken {
185
- /** The machine anchor token. */
186
- anchor: string;
187
- /** Whether a conforming document must carry the element. */
188
- presence: Presence;
189
- /** The document surface the anchor lives in. */
190
- home: Home;
191
- /** The referential kind the element participates in. */
192
- refKind: RefKind;
193
- }
194
-
195
- /** One doc type's lexicon — one token per registered element, in registry order. */
196
- export interface DocTokens {
197
- /** The doc-type identity the projection derives from. */
198
- docType: DocType;
199
- /** The token rows, in registry order. */
200
- tokens: readonly DocToken[];
201
- }
202
-
203
- // ---------------------------------------------------------------------------
204
- // reference — the reference vocabulary
205
- // ---------------------------------------------------------------------------
206
-
207
- /** One reference entry — the referential role a registered element participates in. */
208
- export interface ReferenceEntry {
209
- /** The machine anchor token. */
210
- anchor: string;
211
- /** The referential kind the element participates in ("none" for presence-only elements). */
212
- refKind: RefKind;
213
- /** The declared value pattern the reference rides on, when the element carries one. */
214
- valuePattern?: string;
215
- }
216
-
217
- /** One doc type's reference projection — one entry per registered element, in registry order. */
218
- export interface DocReference {
219
- /** The doc-type identity the projection derives from. */
220
- docType: DocType;
221
- /** The reference rows, in registry order. */
222
- entries: readonly ReferenceEntry[];
223
- }
224
-
225
- // ---------------------------------------------------------------------------
226
- // skeleton — the doc-skeleton face (the schema-gen rendering input)
227
- // ---------------------------------------------------------------------------
228
-
229
- /** The slot kinds of one skeleton element — how the element's value renders in
230
- * the assembled markdown skeleton (spec §4.1, the placeholder-anchoring
231
- * strategy: pure content slots take `:::fill`, link-shaped anchors a placeholder
232
- * link, structure is always true value). */
233
- export type SlotKind =
234
- /** A free-text value position — the ONLY `:::fill <slot>` landing class. */
235
- | "content"
236
- /** A link-shaped anchor slot — the parent-program / spec-ref links render as a
237
- * placeholder link (a `<…>` target on the exemption chain), never `:::fill`. */
238
- | "link"
239
- /** A digit-family heading — `N.` / `N.M` / `Task N:` render with true numbers
240
- * (a literal `N` would puncture the declared digit-shaped value pattern). */
241
- | "numeric-heading"
242
- /** A pattern-typed truth row — an enum domain's first legal literal (`status:
243
- * Draft`) or a graph row (hard edge / legend) — a conforming row, not a fill. */
244
- | "generator-truth"
245
- /** A table column-header row. */
246
- | "table-header"
247
- /** A table data row. */
248
- | "table-row"
249
- /** The fixed scaffold lines — the version row, the table version/date tokens and
250
- * the fixed structure headings — structural, never fill positions. */
251
- | "scaffold";
252
-
253
- /** One skeleton slot — an element's contribution to the assembled skeleton. */
254
- export interface SkeletonSlot {
255
- /** The machine anchor token. */
256
- anchor: string;
257
- /** The element's declared presence — always required in the body slot list;
258
- * the front-matter emission list also carries the type's optional keys. */
259
- presence: Presence;
260
- /** The document surface the anchor lives in. */
261
- home: Home;
262
- /** The skeleton slot kind — the element's placeholder-anchoring class (spec §4.1). */
263
- slot: SlotKind;
264
- /** The declared value shape, when the element carries one. */
265
- valuePattern?: string;
266
- /** The referential kind the element participates in. */
267
- refKind: RefKind;
268
- }
269
-
270
- /** One doc type's skeleton projection — the body slot list in shape home-group
271
- * order (optional/conditional elements generate no slot — the zero
272
- * conditional-residue contract mirrored at the skeleton surface) plus the
273
- * independent front-matter emission list (spec §4.2: the required keys plus
274
- * the type's optional frontmatter-home keys — `base` / `depends-on` — which
275
- * never ride the slot channel). */
276
- export interface DocSkeleton {
277
- /** The doc-type identity the projection derives from. */
278
- docType: DocType;
279
- /** The required elements' slots in shape home-group order (body + the required
280
- * front-matter keys). */
281
- slots: readonly SkeletonSlot[];
282
- /** The front-matter emission list in registry order — the required head keys
283
- * plus the type's optional frontmatter-home keys, minus the deliberately
284
- * omitted `parent-version` (§4.2's shape-typed exclusion). */
285
- frontmatter: readonly SkeletonSlot[];
286
- }
287
-
288
- // ---------------------------------------------------------------------------
289
- // the six projection faces
290
- // ---------------------------------------------------------------------------
291
-
292
- /** The shape projection record — one DocShape per doc type. */
293
- export type ShapeProjection = Record<DocKey, DocShape>;
294
- /** The schema projection record — one DocSchema per doc type. */
295
- export type SchemaProjection = Record<DocKey, DocSchema>;
296
- /** The slices projection record — one DocSlices per doc type. */
297
- export type SlicesProjection = Record<DocKey, DocSlices>;
298
- /** The tokens projection record — one DocTokens per doc type. */
299
- export type TokensProjection = Record<DocKey, DocTokens>;
300
- /** The reference projection record — one DocReference per doc type. */
301
- export type ReferenceProjection = Record<DocKey, DocReference>;
302
- /** The skeleton projection record — one DocSkeleton per doc type. */
303
- export type SkeletonProjection = Record<DocKey, DocSkeleton>;
304
-
305
- /** The composed six-projection surface derived from the declared registries. */
306
- export interface ProjectedRegistries {
307
- shape: ShapeProjection;
308
- schema: SchemaProjection;
309
- slices: SlicesProjection;
310
- tokens: TokensProjection;
311
- reference: ReferenceProjection;
312
- skeleton: SkeletonProjection;
313
- }
314
-
315
- /**
316
- * The projection carrier — the registered registries' single derivation surface.
317
- * Constructed on the declared registries (the domain's `declaredRegistries`),
318
- * its seven methods project the six faces (shape / schema / slices / tokens /
319
- * reference / skeleton) and their composed record. Every surface is pure
320
- * derivation from the injected registries; construction is cheap and the
321
- * instance is stateless after construction, so sharing one instance across the
322
- * consumers (the parsers, the contract, the lint, the graph) composes safely.
323
- */
324
- export class Projector {
325
- /** The declared registries every projection derives from — the construction input. */
326
- readonly #registries: DeclaredRegistries;
327
-
328
- constructor(registries: DeclaredRegistries) {
329
- this.#registries = registries;
330
- }
331
-
332
- /** Derive all four doc types' section-skeleton faces. */
333
- shape(): ShapeProjection {
334
- return this.#projectAll((registry) => this.#projectDocShape(registry));
335
- }
336
-
337
- /** Derive all four doc types' JSON Schema faces. */
338
- schema(): SchemaProjection {
339
- return this.#projectAll((registry) => this.#projectDocSchema(registry));
340
- }
341
-
342
- /** Derive all four doc types' parse-regex faces. */
343
- slices(): SlicesProjection {
344
- return this.#projectAll((registry) => this.#projectDocSlices(registry));
345
- }
346
-
347
- /** Derive all four doc types' anchor lexicons. */
348
- tokens(): TokensProjection {
349
- return this.#projectAll((registry) => this.#projectDocTokens(registry));
350
- }
351
-
352
- /** Derive all four doc types' reference vocabularies. */
353
- reference(): ReferenceProjection {
354
- return this.#projectAll((registry) => this.#projectDocReference(registry));
355
- }
356
-
357
- /** Derive all four doc types' doc-skeleton faces (body slots + the front-matter
358
- * emission list). */
359
- skeleton(): SkeletonProjection {
360
- return this.#projectAll((registry) => this.#projectDocSkeleton(registry));
361
- }
362
-
363
- /** The composed projection face — all six derived surfaces over the injected registries. */
364
- registries(): ProjectedRegistries {
365
- return {
366
- shape: this.shape(),
367
- schema: this.schema(),
368
- slices: this.slices(),
369
- tokens: this.tokens(),
370
- reference: this.reference(),
371
- skeleton: this.skeleton(),
372
- };
373
- }
374
-
375
- /**
376
- * Escape a literal so it can be embedded verbatim in a RegExp — the
377
- * anchor-literal → parse-regex derivation the slices face is built on. Every
378
- * declared anchor escapes to a pattern that matches the anchor itself (the
379
- * "each slice parses its anchor" checkable).
380
- */
381
- static #escapeRegExp(text: string): string {
382
- return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
383
- }
384
-
385
- // -------------------------------------------------------------------------
386
- // shared derivation chain — the chain root every projection selects from
387
- // -------------------------------------------------------------------------
388
-
389
- /** Project one registry row onto the derived identity (refKind materialized to its "none" default). */
390
- #deriveElement(element: RegistryElement): DerivedElement {
391
- return {
392
- anchor: element.anchor,
393
- presence: element.presence,
394
- refKind: element.refKind ?? "none",
395
- home: element.home,
396
- valuePattern: element.valuePattern,
397
- };
398
- }
399
-
400
- /** Derive the whole registry rows of one doc type. */
401
- #deriveRegistry(registry: ElementRegistry): DerivedElement[] {
402
- return registry.elements.map((element) => this.#deriveElement(element));
403
- }
404
-
405
- /** Map a per-registry projector across the four injected registries, keyed by their record identity. */
406
- #projectAll<T>(project: (registry: ElementRegistry) => T): Record<DocKey, T> {
407
- return {
408
- "overall-spec": project(this.#registries["overall-spec"]),
409
- plan: project(this.#registries.plan),
410
- "phase-spec": project(this.#registries["phase-spec"]),
411
- "single-spec": project(this.#registries["single-spec"]),
412
- };
413
- }
414
-
415
- // -------------------------------------------------------------------------
416
- // the per-face projectors
417
- // -------------------------------------------------------------------------
418
-
419
- /** Project one registry onto its section-structure face (one shape element per registered element). */
420
- #projectDocShape(registry: ElementRegistry): DocShape {
421
- const groups: ShapeGroup[] = [];
422
- const groupSlotOf = new Map<Home, number>();
423
- for (const element of this.#deriveRegistry(registry)) {
424
- let slot = groupSlotOf.get(element.home);
425
- if (slot === undefined) {
426
- slot = groups.length;
427
- groupSlotOf.set(element.home, slot);
428
- groups.push({ home: element.home, elements: [] });
429
- }
430
- (groups[slot].elements as ShapeElement[]).push({
431
- anchor: element.anchor,
432
- presence: element.presence,
433
- refKind: element.refKind,
434
- });
435
- }
436
- return { docType: registry.docType, structure: groups };
437
- }
438
-
439
- /** Project one registry onto its JSON Schema face. */
440
- #projectDocSchema(registry: ElementRegistry): DocSchema {
441
- const elements = this.#deriveRegistry(registry);
442
- const properties: Record<string, SchemaProperty> = {};
443
- const required: string[] = [];
444
- for (const element of elements) {
445
- if (element.valuePattern !== undefined) {
446
- properties[element.anchor] = {
447
- type: "string",
448
- pattern: element.valuePattern,
449
- description: `presence: ${element.presence} · home: ${element.home} · ref: ${element.refKind}`,
450
- };
451
- }
452
- if (element.presence === "required") required.push(element.anchor);
453
- }
454
- return {
455
- docType: registry.docType,
456
- $schema: "https://json-schema.org/draft/2020-12/schema",
457
- title: `${registry.docType} document structure`,
458
- description: `Derived JSON Schema — ${elements.length} declared elements · ${required.length} required`,
459
- type: "object",
460
- properties,
461
- required,
462
- };
463
- }
464
-
465
- /** Project one registry onto its parse-regex face. */
466
- #projectDocSlices(registry: ElementRegistry): DocSlices {
467
- const slices: ElementSlice[] = [];
468
- for (const element of this.#deriveRegistry(registry)) {
469
- // Frontmatter-home elements anchor on YAML keys — a key is looked up
470
- // directly against the parsed front-matter, so both RegExp compilations
471
- // (anchor + value) stop on the header leg (§3.3).
472
- const header = element.home === "frontmatter";
473
- slices.push({
474
- anchor: element.anchor,
475
- presence: element.presence,
476
- home: element.home,
477
- anchorPattern: header ? undefined : new RegExp(Projector.#escapeRegExp(element.anchor)),
478
- valuePattern:
479
- element.valuePattern === undefined || header
480
- ? undefined
481
- : new RegExp(element.valuePattern),
482
- });
483
- }
484
- return { docType: registry.docType, slices };
485
- }
486
-
487
- /** Project one registry onto its anchor-lexicon face. */
488
- #projectDocTokens(registry: ElementRegistry): DocTokens {
489
- return {
490
- docType: registry.docType,
491
- tokens: this.#deriveRegistry(registry).map((element) => ({
492
- anchor: element.anchor,
493
- presence: element.presence,
494
- home: element.home,
495
- refKind: element.refKind,
496
- })),
497
- };
498
- }
499
-
500
- /** Project one registry onto its reference-vocabulary face. */
501
- #projectDocReference(registry: ElementRegistry): DocReference {
502
- return {
503
- docType: registry.docType,
504
- entries: this.#deriveRegistry(registry).map((element) => ({
505
- anchor: element.anchor,
506
- refKind: element.refKind,
507
- valuePattern: element.valuePattern,
508
- })),
509
- };
510
- }
511
-
512
- // -------------------------------------------------------------------------
513
- // the skeleton face — the doc-skeleton projection (spec §4.1/§4.2)
514
- // -------------------------------------------------------------------------
515
-
516
- /** Project one registry onto its doc-skeleton face — the required elements'
517
- * slots in the shape's home-group order (the shape walk is the ordering
518
- * source: group sequence + within-group registry order, never a second order
519
- * declaration). Optional/conditional elements generate no slot — the zero
520
- * conditional-residue contract mirrored at the skeleton surface. The
521
- * front-matter emission list is projected independently of the slot channel
522
- * (§4.2: required head keys + the type's optional head keys; `parent-version`
523
- * is the one explicit exclusion — its `v<n>.<m>` domain admits no placeholder
524
- * form). */
525
- #projectDocSkeleton(registry: ElementRegistry): DocSkeleton {
526
- const byAnchor = new Map(
527
- this.#deriveRegistry(registry).map((element) => [element.anchor, element]),
528
- );
529
- const slots: SkeletonSlot[] = [];
530
- for (const group of this.#projectDocShape(registry).structure) {
531
- for (const element of group.elements) {
532
- const derived = byAnchor.get(element.anchor)!;
533
- if (derived.presence !== "required") continue;
534
- slots.push(this.#skeletonSlot(derived));
535
- }
536
- }
537
- return { docType: registry.docType, slots, frontmatter: this.#frontmatterSlots(registry) };
538
- }
539
-
540
- /** The front-matter emission list — the independent line set §4.2 prescribes:
541
- * every frontmatter-home required key plus the type's optional head keys
542
- * (`base` / `depends-on`), in registry order. `parent-version` is the single
543
- * explicit exclusion: an optional shape-typed key whose domain admits neither
544
- * placeholder form, so absence is the only legal skeleton state (the consumer
545
- * fills it when the parent version is known). */
546
- #frontmatterSlots(registry: ElementRegistry): SkeletonSlot[] {
547
- const out: SkeletonSlot[] = [];
548
- for (const element of this.#deriveRegistry(registry)) {
549
- if (element.home !== "frontmatter") continue;
550
- if (element.anchor === "parent-version") continue;
551
- out.push(this.#skeletonSlot(element));
552
- }
553
- return out;
554
- }
555
-
556
- /** Project one derived element onto its skeleton slot row. */
557
- #skeletonSlot(element: DerivedElement): SkeletonSlot {
558
- return {
559
- anchor: element.anchor,
560
- presence: element.presence,
561
- home: element.home,
562
- slot: this.#skeletonSlotOf(element),
563
- valuePattern: element.valuePattern,
564
- refKind: element.refKind,
565
- };
566
- }
567
-
568
- /** Classify one required element's slot kind — the placeholder-anchoring
569
- * semantics of the element's value (spec §4.1):
570
- * · link — the parent-program / spec-ref link-shaped anchors render
571
- * as placeholder links (`:::fill` never lands on them — a
572
- * fill in a link slot is a guaranteed finding);
573
- * · numeric-heading — the digit-family headings (`N.` / `N.M` / `Task N:`)
574
- * whose numbers are true values in the skeleton, never a
575
- * literal `N` (a literal `N` punctures the declared
576
- * digit-shaped value pattern);
577
- * · generator-truth — a pattern-typed value row: a fully-anchored enum domain
578
- * (the first legal literal — `status: Draft`) or a
579
- * graph row (hard edge / legend conforming lines);
580
- * · table-header / table-row / scaffold — the table column headers, the data
581
- * rows and the fixed scaffold rows (the version line, the
582
- * table version/date tokens, the fixed structure headings);
583
- * · content — the remaining free-text value positions — the ONLY
584
- * `:::fill` landing class (pure content slots carry zero
585
- * fully-anchored enum / graph elements).
586
- */
587
- #skeletonSlotOf(element: DerivedElement): SlotKind {
588
- // The link-typed anchor slots are the front-matter link keys (`spec` · the
589
- // `parent-program` of plan / phase-spec) — their values render as placeholder
590
- // links (`<…>` targets on the exemption chain), never `:::fill`. The
591
- // enum-typed table cells (a Design-spec cell, a markdown-link
592
- // implementation-plan cell) ride the generator-truth class, never a link
593
- // slot — the home + ref-kind pair keys the class (the frontmatter-home
594
- // anchors are now YAML keys, so the old `\[`-shape probe no longer applies).
595
- if (
596
- element.home === "frontmatter" &&
597
- (element.refKind === "parent-program" || element.refKind === "spec-ref")
598
- )
599
- return "link";
600
- if (
601
- (element.anchor.startsWith("#") || element.anchor === "Task id token") &&
602
- element.valuePattern !== undefined &&
603
- /\\d/.test(element.valuePattern)
604
- )
605
- return "numeric-heading";
606
- // The front-matter version and date rows are fixed scaffold — the same class
607
- // as the table version/date tokens.
608
- if (element.anchor === "version" || element.anchor === "date") return "scaffold";
609
- if (element.home === "graph" || Projector.#isEnumPattern(element.valuePattern))
610
- return "generator-truth";
611
- if (element.home === "table") {
612
- if (element.anchor.endsWith(" columns")) return "table-header";
613
- if (element.anchor.endsWith(" row")) return "table-row";
614
- // The dependency cell is a free-text cell value (`:::fill` — a P->P shape to
615
- // fill, not a structural token) — every other table token (version / date /
616
- // phase id) is fixed scaffold.
617
- if (element.anchor === "Dependency cell") return "content";
618
- return "scaffold";
619
- }
620
- // The front-matter content keys (the title plus the other free-text head
621
- // scalars — author · depends-on · base) are the head's fill positions (`:::fill
622
- // <key>` in the emitted front matter); the remaining heading anchors are fixed
623
- // structure.
624
- if (element.anchor === "title") return "content";
625
- if (element.anchor.startsWith("#")) return "scaffold";
626
- return "content";
627
- }
628
-
629
- /** Whether a declared value pattern is a point-enum form — a bare pipe inside an
630
- * alternative group (escapes stripped first: the declared patterns escape their
631
- * literal metacharacters — `\|` = a table bar, `\[` = a literal bracket — while
632
- * the enum alternatives ride BARE pipes inside unescaped group parens; parens
633
- * inside the character classes are skipped). The strip leaves the character
634
- * classes partially intact — the scan tracks class brackets so a `)` inside
635
- * `[^)]` never closes the group. The first legal literal is the generator truth. */
636
- static #isEnumPattern(valuePattern: string | undefined): boolean {
637
- if (valuePattern === undefined) return false;
638
- const unescaped = valuePattern.replace(/\\./g, "");
639
- let depth = 0;
640
- let inClass = false;
641
- for (const char of unescaped) {
642
- if (inClass) {
643
- if (char === "]") inClass = false;
644
- continue;
645
- }
646
- if (char === "[") {
647
- inClass = true;
648
- continue;
649
- }
650
- if (char === "(") depth += 1;
651
- else if (char === ")") depth -= 1;
652
- else if (char === "|" && depth > 0) return true;
653
- }
654
- return false;
655
- }
656
- }