@oscaner-skills/cdd-engine 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,209 @@
1
+ // packages/cdd-engine/src-next/contract/frontmatter.ts
2
+ // T1 — the front-matter head extraction chain (design spec §2.1/§2.2): a typed
3
+ // head value object plus a thin `---` fence split over the `yaml` engine. The
4
+ // extractor reads the RAW content (never the canonicalize view — front matter is
5
+ // data, not structure; the canonicalized view would silently rewrite registered
6
+ // Chinese aliases inside header values). The registry keeps the declared value
7
+ // shapes (spec §2.3); this file only carries the parse channel (fence split +
8
+ // `yaml.parse`) and the typed accessors.
9
+ //
10
+ // Zero bare functions and zero new regexes are hard guarantees of this module:
11
+ // the line split/join and the parse-error message slices are hand-rolled string
12
+ // walks, and the YAML engine does all value parsing.
13
+ import { LineCounter, parse } from "yaml";
14
+ /** A front-matter YAML parse failure — the typed, position-carrying reason a
15
+ * `FrontMatterExtractor.split` did not produce a head (D1, the position-carrying error contract:
16
+ * the extractor never swallows a parse error into a null head — the review gate
17
+ * surfaces the real failure, `yaml`'s `YAMLParseError` fed through a `LineCounter`
18
+ * carries the line/column for free, we only stop throwing it away). */
19
+ export class FrontMatterParseError {
20
+ /** The one-based line of the failure inside the front-matter block. */
21
+ line;
22
+ /** The one-based column of the failure on that line. */
23
+ column;
24
+ /** The engine's reason, without the position clause (`Unexpected scalar at node
25
+ * end` — the position rides the typed fields, never a re-parse of the message). */
26
+ reason;
27
+ /** The offending front-matter source line (the human-facing excerpt). */
28
+ source;
29
+ constructor(line, column, reason, source) {
30
+ this.line = line;
31
+ this.column = column;
32
+ this.reason = reason;
33
+ this.source = source;
34
+ }
35
+ }
36
+ /** A parsed front-matter head — the typed accessor surface over the YAML record.
37
+ * A missing key, a non-scalar value (a list, a mapping, a bare number) and an
38
+ * unparseable block all read as `null`: the head carries only scalar facts. An
39
+ * UNPARSEABLE block additionally carries its `parseError` — the gate distinguishes
40
+ * a genuinely absent key from a malformed block (D1, the false-positive fix). */
41
+ export class FrontMatterHead {
42
+ /** The parsed front-matter record, or null when no head was extracted. */
43
+ #data;
44
+ /** The front-matter parse failure that prevented a head, or null. */
45
+ #parseError;
46
+ /** Wrap one parsed front-matter record (null for "no head"); the parse error the
47
+ * head carries when the block could not be parsed (null by default). */
48
+ constructor(data, parseError = null) {
49
+ this.#data = data;
50
+ this.#parseError = parseError;
51
+ }
52
+ /** The front-matter parse failure, or null when the block parsed (or no head). */
53
+ get parseError() {
54
+ return this.#parseError;
55
+ }
56
+ /** The scalar value of one front-matter key — null for a missing key, a
57
+ * non-scalar YAML value (list / mapping / number / boolean) or a null literal. */
58
+ value(key) {
59
+ if (this.#data === null)
60
+ return null;
61
+ const raw = this.#data[key];
62
+ if (typeof raw !== "string")
63
+ return null;
64
+ return raw;
65
+ }
66
+ /** The document title (`title:`). */
67
+ get title() {
68
+ return this.value("title");
69
+ }
70
+ /** The machine doc-type identity (`doc-type:`) — a `DOC_TYPE_VALUES` member in a conforming document. */
71
+ get docType() {
72
+ return this.value("doc-type");
73
+ }
74
+ /** The version token (`version:`, the `v<major>.<minor>` form). */
75
+ get version() {
76
+ return this.value("version");
77
+ }
78
+ /** The ISO date (`date:`, the `yyyy-mm-dd` form). */
79
+ get date() {
80
+ return this.value("date");
81
+ }
82
+ /** The status literal (`status:`, the declared per-doc-type enum). */
83
+ get status() {
84
+ return this.value("status");
85
+ }
86
+ /** The author line (`author:`). */
87
+ get author() {
88
+ return this.value("author");
89
+ }
90
+ /** The plan's design-spec target path (`spec:`). */
91
+ get spec() {
92
+ return this.value("spec");
93
+ }
94
+ /** The Class-B parent-overall target path (`parent-program:`). */
95
+ get parentProgram() {
96
+ return this.value("parent-program");
97
+ }
98
+ /** The Class-B version token (`parent-version:`, the `v<major>.<minor>` form). */
99
+ get parentVersion() {
100
+ return this.value("parent-version");
101
+ }
102
+ /** The `depends-on:` front-matter key value. */
103
+ get dependsOn() {
104
+ return this.value("depends-on");
105
+ }
106
+ /** The plan base-line value (`base:`). */
107
+ get base() {
108
+ return this.value("base");
109
+ }
110
+ /** The single-spec issues line (`issues:`). */
111
+ get issues() {
112
+ return this.value("issues");
113
+ }
114
+ }
115
+ /** The front-matter split of a document — the fence split + `yaml.parse` (spec
116
+ * §2.2's selection: one YAML engine for the whole repo, a ~10-line fence split,
117
+ * no front-matter library). Reads the RAW original content verbatim; the body is
118
+ * everything after the second `---` fence. */
119
+ // biome-ignore lint/complexity/noStaticOnlyClass: the plan-mandated static split surface — the zero-bare-function discipline admits no standalone split helpers.
120
+ export class FrontMatterExtractor {
121
+ /** Split one document into its typed head and body. With no opening fence on
122
+ * line zero, no closing fence, an unparseable block or a non-record block,
123
+ * every head value reads null and the body is the original content. An
124
+ * UNPARSEABLE block (D1) additionally carries its `FrontMatterParseError` on
125
+ * the head — the failure is typed and positioned, never a silent null. */
126
+ static split(content) {
127
+ const lines = FrontMatterExtractor.lineSplit(content);
128
+ if (lines.length === 0 || lines[0].trim() !== "---") {
129
+ return { head: new FrontMatterHead(null), body: content };
130
+ }
131
+ const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
132
+ if (closing === -1)
133
+ return { head: new FrontMatterHead(null), body: content };
134
+ const yamlLines = lines.slice(1, closing);
135
+ const yamlText = FrontMatterExtractor.lineJoin(yamlLines);
136
+ const lineCounter = new LineCounter();
137
+ let parsed;
138
+ try {
139
+ parsed = parse(yamlText, { lineCounter });
140
+ }
141
+ catch (err) {
142
+ return {
143
+ // D1: the parse failure travels as a typed, positioned error — the gate
144
+ // reports the real YAML failure, never the "no doc-type" misread a null
145
+ // head would otherwise trigger.
146
+ head: new FrontMatterHead(null, FrontMatterExtractor.#parseErrorOf(err, yamlLines)),
147
+ body: content,
148
+ };
149
+ }
150
+ // A non-record parse (a scalar block, a sequence) is not a head — every
151
+ // value reads null and the body stays the original content. A null parse
152
+ // (an empty front-matter block) yields the empty head with the post-fence
153
+ // body: the fence split itself succeeded.
154
+ if (parsed !== null && (typeof parsed !== "object" || Array.isArray(parsed))) {
155
+ return { head: new FrontMatterHead(null), body: content };
156
+ }
157
+ return {
158
+ head: new FrontMatterHead(parsed),
159
+ body: FrontMatterExtractor.lineJoin(lines.slice(closing + 1)),
160
+ };
161
+ }
162
+ /** One thrown YAML parse error → the typed failure: the position from the
163
+ * engine's `linePos` (fed by the `LineCounter`), the reason without its
164
+ * position clause (string ops — this module carries zero regexes) and the
165
+ * offending source line from the block itself. */
166
+ static #parseErrorOf(err, yamlLines) {
167
+ const message = err instanceof Error ? err.message : "YAML parse error";
168
+ // The engine's message head ends with " at line <n>, column <m>: " — the
169
+ // position is a typed field below, so the reason drops the clause. Both
170
+ // slices are hand-rolled string walks: this module carries zero regexes and
171
+ // the Task 1 checkable also pins the whole `String#split` family to zero.
172
+ const reason = FrontMatterExtractor.#beforeFirst(FrontMatterExtractor.#beforeFirst(message, "\n"), " at line ").trim();
173
+ const position = err.linePos?.[0];
174
+ const line = position?.line ?? 0;
175
+ const source = line > 0 ? (yamlLines[line - 1] ?? "") : "";
176
+ return new FrontMatterParseError(line, position?.col ?? 0, reason, source);
177
+ }
178
+ /** The text before the first occurrence of `separator` — the hand-rolled
179
+ * slice (the whole string on no occurrence), the string-walk counterpart of
180
+ * the retired `String#split` calls. */
181
+ static #beforeFirst(text, separator) {
182
+ const index = text.indexOf(separator);
183
+ return index === -1 ? text : text.slice(0, index);
184
+ }
185
+ /** Split a document into its lines — the hand-rolled split (the zero-regex
186
+ * discipline bans `String#split`'s word here). */
187
+ static lineSplit(content) {
188
+ const lines = [];
189
+ let start = 0;
190
+ for (let index = 0; index < content.length; index++) {
191
+ if (content[index] !== "\n")
192
+ continue;
193
+ lines.push(content.slice(start, index));
194
+ start = index + 1;
195
+ }
196
+ lines.push(content.slice(start));
197
+ return lines;
198
+ }
199
+ /** Join lines with single `\n` separators — the hand-rolled join. */
200
+ static lineJoin(lines) {
201
+ let out = "";
202
+ for (let index = 0; index < lines.length; index++) {
203
+ if (index > 0)
204
+ out += "\n";
205
+ out += lines[index];
206
+ }
207
+ return out;
208
+ }
209
+ }
@@ -0,0 +1,379 @@
1
+ // packages/cdd-engine/src-next/contract/home-extractors.ts
2
+ // T3 — the home-driven generic extractors (design spec §3.2): one class per home
3
+ // surface. Each class implements the FIXED structural rule of its home (the task
4
+ // block head + `- **Key**:` fields + `- ` steps, the numbered design headings,
5
+ // the graph edge lines, the table rows, the section/facet headings); WHICH
6
+ // anchors belong to the home comes from the injected registry — the registry
7
+ // stays the single knowledge source (D26), and the hand-written per-anchor
8
+ // grammars of the old parse face (contract/doc.ts) are retired.
9
+ //
10
+ // The unified entry — extract(registry, lines) — maps each served anchor to the
11
+ // occurrence lines/segments of that element in the document (document order;
12
+ // graph edges are matched and carried on their trimmed form). Where a home's
13
+ // structure rule further decomposes an occurrence (the design numbered-heading
14
+ // number/text split), the extractor owns the decomposition too.
15
+ /**
16
+ * The home-extractor base — the shared anchor-roster and the declared-pattern
17
+ * application both classes build on. Stateless by design: `extract` reads the
18
+ * injected registry and lines per call, so one shared instance per home services
19
+ * every consumer.
20
+ */
21
+ export class HomeExtractor {
22
+ /** The registered elements of one served home surface. */
23
+ elementsOf(registry, home) {
24
+ return registry.elements.filter((element) => element.home === home);
25
+ }
26
+ /** The element's declared value pattern compiled — the "already-declared
27
+ * value-pattern application" primitive (never a second hand-written grammar). */
28
+ patternOf(element) {
29
+ return element.valuePattern === undefined ? undefined : new RegExp(element.valuePattern);
30
+ }
31
+ /** Append one occurrence line under an anchor — the shared map-bucket push
32
+ * (the `??=` short-hand rewritten to keep assignments out of expressions). */
33
+ appendBucket(out, anchor, line) {
34
+ let bucket = out[anchor];
35
+ if (bucket === undefined) {
36
+ bucket = [];
37
+ out[anchor] = bucket;
38
+ }
39
+ bucket.push(line);
40
+ }
41
+ }
42
+ /**
43
+ * The task extractor — the task home's structure rule: the `### Task N:` block
44
+ * head (with the id token it carries), the `- **Key**:` field markers and the
45
+ * `- ` step bullets / `— checkable:` clauses. The same generic walk serves the
46
+ * task-block / task-field / task-step homes; which anchors belong to each comes
47
+ * from the registry.
48
+ */
49
+ export class TaskExtractor extends HomeExtractor {
50
+ homes = ["task-block", "task-field", "task-step"];
51
+ extract(registry, lines) {
52
+ // The task block head — the declared `### Task N:` anchor yields, aligned, the
53
+ // block-head lines and the id tokens they carry (the `Task id token` vocabulary
54
+ // rides on the head; its grammar is the block-head structure — the digit run in
55
+ // the anchor's `N` slot).
56
+ const blockHead = this.elementsOf(registry, "task-block").find((element) => element.anchor === "### Task N:");
57
+ const blockPattern = blockHead === undefined ? undefined : this.patternOf(blockHead);
58
+ // The field markers — each declared `- **Key**:` anchor's own line form. Only
59
+ // the bold-key anchors are markers at the LINE level (the task-field structure
60
+ // rule: a field is a `- **Key**:` bullet); the value-shape anchors of the same
61
+ // home (`File path token` · `DependsOn none` · …) describe CELL content and
62
+ // never occur as whole lines — the judgment plane scopes them to field cells.
63
+ const fieldAnchors = this.elementsOf(registry, "task-field")
64
+ .filter((element) => element.anchor.startsWith("**"))
65
+ .map((element) => ({
66
+ anchor: element.anchor,
67
+ pattern: this.patternOf(element),
68
+ }));
69
+ // The step lines — scoped to the `**Steps**` field's continuation lines (the
70
+ // task home's structure rule: the block head owns the `- **Key**:` fields,
71
+ // the steps ride inside the Steps field), matched on their trimmed form.
72
+ const stepAnchors = this.elementsOf(registry, "task-step").map((element) => ({
73
+ anchor: element.anchor,
74
+ pattern: this.patternOf(element),
75
+ }));
76
+ const out = {};
77
+ const headings = [];
78
+ const ids = [];
79
+ let inStepsField = false;
80
+ for (const line of lines) {
81
+ if (blockPattern?.test(line) === true) {
82
+ headings.push(line);
83
+ const id = blockHead === undefined ? null : this.#taskIdOf(line, blockHead.anchor);
84
+ if (id !== null && ids.length < headings.length)
85
+ ids.push(id);
86
+ inStepsField = false;
87
+ continue;
88
+ }
89
+ const field = fieldAnchors.find((candidate) => candidate.pattern?.test(line) === true);
90
+ if (field !== undefined) {
91
+ this.appendBucket(out, field.anchor, line);
92
+ inStepsField = field.anchor === "**Steps**";
93
+ continue;
94
+ }
95
+ if (!inStepsField)
96
+ continue;
97
+ for (const candidate of stepAnchors) {
98
+ if (candidate.pattern?.test(line.trim()) !== true)
99
+ continue;
100
+ this.appendBucket(out, candidate.anchor, line);
101
+ }
102
+ }
103
+ if (headings.length > 0) {
104
+ out["### Task N:"] = headings;
105
+ out["Task id token"] = ids;
106
+ }
107
+ return out;
108
+ }
109
+ /** The task number of one `### Task N:` heading — the digit run in the declared
110
+ * block-head anchor's `N` slot (no second grammar: the slot position is the
111
+ * anchor's own structure). */
112
+ #taskIdOf(heading, blockHeadAnchor) {
113
+ const idSlot = blockHeadAnchor.indexOf("N");
114
+ if (idSlot === -1)
115
+ return null;
116
+ const prefix = blockHeadAnchor.slice(0, idSlot);
117
+ const rest = heading.slice(prefix.length);
118
+ let end = 0;
119
+ while (end < rest.length && rest[end] >= "0" && rest[end] <= "9")
120
+ end += 1;
121
+ if (end === 0)
122
+ return null;
123
+ return rest.slice(0, end);
124
+ }
125
+ }
126
+ /**
127
+ * The design-body extractor — the double-layer `### N.` group / `#### N.M` item
128
+ * headings and the `## Design` / `### Acceptance criteria` leaves. The
129
+ * numbered-heading structure rule (the number token before the dot/space and the
130
+ * text after) lives here — the parse face consumes the decomposition.
131
+ */
132
+ export class DesignBodyExtractor extends HomeExtractor {
133
+ homes = ["design-body"];
134
+ extract(registry, lines) {
135
+ const out = {};
136
+ for (const element of this.elementsOf(registry, "design-body")) {
137
+ const pattern = this.patternOf(element);
138
+ if (pattern === undefined)
139
+ continue;
140
+ const hits = [];
141
+ for (const line of lines) {
142
+ if (pattern.test(line))
143
+ hits.push(line);
144
+ }
145
+ if (hits.length > 0)
146
+ out[element.anchor] = hits;
147
+ }
148
+ return out;
149
+ }
150
+ /** One `### N.` group heading's number and text (the digit before the dot, the text after). */
151
+ groupOf(heading) {
152
+ return this.#splitHeading(heading, "### ".length, true);
153
+ }
154
+ /** One `#### N.M` item heading's composite number and text (the token before the first space, the text after). */
155
+ itemOf(heading) {
156
+ return this.#splitHeading(heading, "#### ".length, false);
157
+ }
158
+ /** The shared numbered-heading split — the number token ends at the first dot
159
+ * (group form) or the first space (item form); the text is the trimmed rest. */
160
+ #splitHeading(heading, prefixLength, dotTerminated) {
161
+ const payload = heading.slice(prefixLength);
162
+ let end = 0;
163
+ while (end < payload.length) {
164
+ const char = payload[end];
165
+ if (dotTerminated && char === ".")
166
+ break;
167
+ if (!dotTerminated && (char === " " || char === "\t"))
168
+ break;
169
+ end += 1;
170
+ }
171
+ const number = payload.slice(0, end);
172
+ if (end >= payload.length)
173
+ return { number, heading: "" };
174
+ let text = payload.slice(end);
175
+ if (dotTerminated && text.startsWith("."))
176
+ text = text.slice(1);
177
+ return { number, heading: text.trim() };
178
+ }
179
+ }
180
+ /**
181
+ * The graph extractor — the `P1 -> P2` edge lines of the `home: "graph"` anchors.
182
+ * The edge/legend line forms are the declared value patterns; the from/to token
183
+ * grammar stays the parse face's preserved graph-edge primitive.
184
+ */
185
+ export class GraphExtractor extends HomeExtractor {
186
+ homes = ["graph"];
187
+ extract(registry, lines) {
188
+ const out = {};
189
+ for (const element of this.elementsOf(registry, "graph")) {
190
+ const pattern = this.patternOf(element);
191
+ if (pattern === undefined)
192
+ continue;
193
+ const hits = [];
194
+ // Edge lines are matched and carried on their trimmed form — the graph
195
+ // block's raw lines may carry leading indentation the declared patterns
196
+ // don't allow.
197
+ for (const line of lines) {
198
+ const trimmed = line.trim();
199
+ if (pattern.test(trimmed))
200
+ hits.push(trimmed);
201
+ }
202
+ if (hits.length > 0)
203
+ out[element.anchor] = hits;
204
+ }
205
+ return out;
206
+ }
207
+ }
208
+ /**
209
+ * The table extractor — the declared table anchors' column-header and data rows.
210
+ * Matching rides the declared row value patterns; the separator-row skip mirrors
211
+ * the parse face's table-split primitive.
212
+ */
213
+ export class TableExtractor extends HomeExtractor {
214
+ homes = ["table"];
215
+ extract(registry, lines) {
216
+ const out = {};
217
+ for (const element of this.elementsOf(registry, "table")) {
218
+ const pattern = this.patternOf(element);
219
+ if (pattern === undefined)
220
+ continue;
221
+ const hits = [];
222
+ for (const line of lines) {
223
+ const trimmed = line.trim();
224
+ if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
225
+ continue;
226
+ if (TableExtractor.isSeparatorRow(trimmed))
227
+ continue;
228
+ if (pattern.test(trimmed))
229
+ hits.push(trimmed);
230
+ }
231
+ if (hits.length > 0)
232
+ out[element.anchor] = hits;
233
+ }
234
+ return out;
235
+ }
236
+ /** The separator row of a markdown table — `|` and only `-` / `:` / `|` /
237
+ * whitespace between the wrapper bars (same rule as the table-split primitive). */
238
+ static isSeparatorRow(trimmed) {
239
+ for (let index = 1; index < trimmed.length - 1; index++) {
240
+ const char = trimmed[index];
241
+ if (char === "-" || char === ":" || char === "|" || char === " " || char === "\t") {
242
+ continue;
243
+ }
244
+ return false;
245
+ }
246
+ return trimmed.length > 2;
247
+ }
248
+ /** Whether a line is a markdown table line — a `|`-wrapped row. */
249
+ static isTableLine(trimmed) {
250
+ return trimmed.startsWith("|") && trimmed.endsWith("|");
251
+ }
252
+ /** The table lines of a line run in document order — the table home's fixed
253
+ * structural rule (a `|`-wrapped row, the separator row excluded). The parse
254
+ * face's table reader consumes this so the table-line / separator knowledge
255
+ * lives here once, never re-derived at the parse face. */
256
+ tableLinesOf(lines) {
257
+ const out = [];
258
+ for (const line of lines) {
259
+ const trimmed = line.trim();
260
+ if (!TableExtractor.isTableLine(trimmed))
261
+ continue;
262
+ if (TableExtractor.isSeparatorRow(trimmed))
263
+ continue;
264
+ out.push(trimmed);
265
+ }
266
+ return out;
267
+ }
268
+ /** The declared column-header line of a line run — the first table line the
269
+ * registry's `… columns` anchors claim (their declared column vocabulary), or
270
+ * null when the section's table declares no column anchor. The parse face
271
+ * consumes this so the declared-home set, not a positional guess, identifies
272
+ * the header row. */
273
+ headerLineOf(registry, lines) {
274
+ const tableLines = this.tableLinesOf(lines);
275
+ for (const element of this.elementsOf(registry, "table")) {
276
+ if (!element.anchor.endsWith(" columns"))
277
+ continue;
278
+ const pattern = this.patternOf(element);
279
+ if (pattern === undefined)
280
+ continue;
281
+ for (const line of tableLines) {
282
+ if (pattern.test(line))
283
+ return line;
284
+ }
285
+ }
286
+ return null;
287
+ }
288
+ }
289
+ /**
290
+ * The heading scanner — the section/facet home's registered heading anchors.
291
+ * The heading rank derives from the anchor's own leading `#` count and the
292
+ * occurrence must carry the same rank: a line is an occurrence only when it is a
293
+ * heading of the declared rank AND its declared value shape accepts it.
294
+ */
295
+ export class HeadingScanner extends HomeExtractor {
296
+ homes = ["section", "facet"];
297
+ extract(registry, lines) {
298
+ const out = {};
299
+ for (const element of this.elementsOf(registry, "section").concat(this.elementsOf(registry, "facet"))) {
300
+ const rank = HeadingScanner.#rankOf(element.anchor);
301
+ if (rank === null)
302
+ continue;
303
+ const pattern = this.patternOf(element);
304
+ const hits = [];
305
+ for (const line of lines) {
306
+ if (HeadingScanner.#rankOf(line) !== rank)
307
+ continue;
308
+ if (pattern === undefined ? line.startsWith(element.anchor) : pattern.test(line)) {
309
+ hits.push(line);
310
+ }
311
+ }
312
+ if (hits.length > 0)
313
+ out[element.anchor] = hits;
314
+ }
315
+ return out;
316
+ }
317
+ /** The registered rank-2 section headings of a line run, in document order —
318
+ * the section surface's fixed structure rule (only `##`-ranked headings are
319
+ * sections) over every registry anchor declared at that rank, whichever home
320
+ * owns it (a section-home heading, the conditional-home headings and the
321
+ * design-body `## Design` are all section surfaces). A heading whose text is
322
+ * registered in no home (an undeclared prose section) is not a section. */
323
+ sectionsOf(registry, lines) {
324
+ const declared = new Set();
325
+ for (const element of registry.elements) {
326
+ if (HeadingScanner.#rankOf(element.anchor) !== 2)
327
+ continue;
328
+ const pattern = this.patternOf(element);
329
+ for (const line of lines) {
330
+ if (HeadingScanner.#rankOf(line) !== 2)
331
+ continue;
332
+ if (pattern === undefined ? line.startsWith(element.anchor) : pattern.test(line)) {
333
+ declared.add(line);
334
+ }
335
+ }
336
+ }
337
+ return HeadingScanner.#sectionBlocks(lines, declared);
338
+ }
339
+ /** The `##` block walk — a declared rank-2 heading line opens a section that
340
+ * runs to the next rank-2 heading (the shape the parse face hands its
341
+ * consumers); an undeclared rank-2 heading closes the open section without
342
+ * opening one. */
343
+ static #sectionBlocks(lines, declared) {
344
+ const out = [];
345
+ let openHeading = null;
346
+ let openLines = [];
347
+ const close = () => {
348
+ if (openHeading !== null)
349
+ out.push({ heading: openHeading, lines: openLines });
350
+ openHeading = null;
351
+ openLines = [];
352
+ };
353
+ for (const line of lines) {
354
+ if (HeadingScanner.#rankOf(line) === 2) {
355
+ close();
356
+ if (declared.has(line))
357
+ openHeading = line;
358
+ continue;
359
+ }
360
+ if (openHeading !== null)
361
+ openLines.push(line);
362
+ }
363
+ close();
364
+ return out;
365
+ }
366
+ /** The heading rank of a heading line/anchor literal — the count of leading
367
+ * `#`s followed by whitespace (the heading-rank primitive), or null. */
368
+ static #rankOf(text) {
369
+ let rank = 0;
370
+ while (rank < text.length && text[rank] === "#")
371
+ rank += 1;
372
+ if (rank === 0 || rank > 4)
373
+ return null;
374
+ const next = text[rank];
375
+ if (next !== undefined && next !== " " && next !== "\t")
376
+ return null;
377
+ return rank;
378
+ }
379
+ }