@oscaner-skills/cdd-engine 1.0.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -8
- package/README.zh-CN.md +9 -8
- package/package.json +15 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/smoke.integration.test.ts +202 -0
- package/src-next/__tests__/zero-dep.test.ts +134 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
- package/src-next/contract/__tests__/declare.test.ts +242 -0
- package/src-next/contract/__tests__/doc.test.ts +358 -0
- package/src-next/contract/__tests__/judge.test.ts +873 -0
- package/src-next/contract/__tests__/lint.test.ts +314 -0
- package/src-next/contract/__tests__/project.test.ts +419 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +983 -0
- package/src-next/contract/doc.ts +753 -0
- package/src-next/contract/invariants.ts +1268 -0
- package/src-next/contract/judge.ts +142 -0
- package/src-next/contract/lint.ts +275 -0
- package/src-next/contract/project.ts +596 -0
- package/src-next/contract/skill-anatomy.ts +273 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +948 -0
- package/src-next/face/__tests__/capsule.test.ts +276 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
- package/src-next/face/__tests__/cli.test.ts +4643 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/projection.test.ts +301 -0
- package/src-next/face/__tests__/sync-runner.test.ts +70 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +195 -0
- package/src-next/face/board-view.ts +662 -0
- package/src-next/face/capsule.ts +149 -0
- package/src-next/face/cli.ts +819 -0
- package/src-next/face/declare.ts +326 -0
- package/src-next/face/gate.ts +170 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +326 -0
- package/src-next/face/lifecycle.ts +700 -0
- package/src-next/face/projection.ts +282 -0
- package/src-next/face/route-render.ts +160 -0
- package/src-next/face/words.ts +296 -0
- package/src-next/infra/__tests__/infra.test.ts +287 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/runtime.ts +185 -0
- package/src-next/infra/workspace.ts +232 -0
- package/src-next/render/__tests__/render.test.ts +499 -0
- package/src-next/render/__tests__/skeleton.test.ts +466 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +159 -0
- package/src-next/render/skeleton.ts +437 -0
- package/src-next/render/templates.ts +650 -0
- package/src-next/session/__tests__/graph.test.ts +270 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +744 -0
- package/src-next/session/__tests__/next.test.ts +368 -0
- package/src-next/session/__tests__/preflight.test.ts +491 -0
- package/src-next/session/__tests__/run.test.ts +1014 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +469 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1004 -0
- package/src-next/session/next.ts +192 -0
- package/src-next/session/preflight.ts +240 -0
- package/src-next/session/run.ts +606 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +18 -20
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -0,0 +1,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
|
+
}
|