@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.
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +141 -0
- package/dist/face/cli.js +891 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +603 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +482 -0
- package/dist/face/words.js +220 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +441 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -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
|
-
}
|