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