@oscaner-skills/cdd-engine 4.1.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +39 -9
  2. package/README.zh-CN.md +44 -9
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +401 -131
  25. package/dist/face/capsule.js +66 -89
  26. package/dist/face/cli.js +174 -48
  27. package/dist/face/declare.js +59 -23
  28. package/dist/face/gate.js +117 -40
  29. package/dist/face/host.js +9 -35
  30. package/dist/face/init.js +108 -0
  31. package/dist/face/lifecycle.js +540 -123
  32. package/dist/face/plugins.js +73 -0
  33. package/dist/face/preview.js +43 -10
  34. package/dist/face/projection.js +3 -3
  35. package/dist/face/route-render.js +51 -21
  36. package/dist/face/termination.js +135 -261
  37. package/dist/face/words.js +134 -12
  38. package/dist/infra/atomic.js +15 -0
  39. package/dist/infra/git.js +25 -0
  40. package/dist/infra/proc.js +150 -0
  41. package/dist/infra/round-log.js +104 -0
  42. package/dist/infra/runtime.js +16 -4
  43. package/dist/infra/workspace.js +7 -2
  44. package/dist/render/brief.js +15 -17
  45. package/dist/render/skeleton.js +41 -28
  46. package/dist/render/templates.js +128 -84
  47. package/dist/session/faces.js +47 -20
  48. package/dist/session/graph.js +13 -37
  49. package/dist/session/handoff-schema.js +16 -8
  50. package/dist/session/inflight.js +282 -0
  51. package/dist/session/ledger.js +581 -136
  52. package/dist/session/line-identity.js +33 -0
  53. package/dist/session/next.js +138 -80
  54. package/dist/session/preflight.js +276 -68
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +317 -78
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
  59. package/dist/infra/process.js +0 -22
@@ -1,151 +1,53 @@
1
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.
2
+ // P21 §7.5 — the home-driven extractors, now selector resolution. Each class
3
+ // serves one home surface (design-body · section/facet) and answers the same
4
+ // question it always did — "which nodes of this document carry my elements?" —
5
+ // but it answers it by RESOLVING the registry element's declared `selector`
6
+ // against the ONE markdown tree (markdown-tree.ts), never by scanning raw lines
7
+ // with a hand-written per-home grammar. WHICH anchors belong to a home, and WHERE
8
+ // each one sits, both come from the registry (D26 single source).
9
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.
10
+ // The unified entry — extract(registry, tree) — maps each served anchor to the
11
+ // texts of its resolved occurrences, in document order.
12
+ //
13
+ // Module-level exports are types / the classes — zero behavior-carrying bare
14
+ // functions (the plan's zero-bare-function discipline).
15
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.
16
+ * The home-extractor base — the shared selector resolution every home builds on.
17
+ * Stateless by design: `extract` reads the injected registry and tree per call, so
18
+ * one shared instance per home services every consumer.
20
19
  */
21
20
  export class HomeExtractor {
22
21
  /** The registered elements of one served home surface. */
23
22
  elementsOf(registry, home) {
24
23
  return registry.elements.filter((element) => element.home === home);
25
24
  }
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
- }));
25
+ /** Resolve every served anchor's declared selector against the tree — the ONE
26
+ * extraction path (no home re-declares a locating grammar). An anchor with no
27
+ * occurrence is absent from the map. */
28
+ collect(registry, tree, homes) {
76
29
  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;
30
+ for (const home of homes) {
31
+ for (const element of this.elementsOf(registry, home)) {
32
+ const hits = tree.occurrences(element.selector).map((node) => node.text);
33
+ if (hits.length > 0)
34
+ out[element.anchor] = hits;
88
35
  }
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
36
  }
107
37
  return out;
108
38
  }
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
39
  }
126
40
  /**
127
41
  * The design-body extractor — the double-layer `### N.` group / `#### N.M` item
128
42
  * 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.
43
+ * numbered-heading decomposition (the number token before the dot/space and the
44
+ * text after) lives here — the parse face consumes it; the LOCATION of each leaf
45
+ * is the element's declared selector.
131
46
  */
132
47
  export class DesignBodyExtractor extends HomeExtractor {
133
48
  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;
49
+ extract(registry, tree) {
50
+ return this.collect(registry, tree, this.homes);
149
51
  }
150
52
  /** One `### N.` group heading's number and text (the digit before the dot, the text after). */
151
53
  groupOf(heading) {
@@ -178,202 +80,33 @@ export class DesignBodyExtractor extends HomeExtractor {
178
80
  }
179
81
  }
180
82
  /**
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.
83
+ * The heading scanner — the section/facet home's registered heading anchors. The
84
+ * section surface's fixed structure rule (only `##`-ranked headings are sections)
85
+ * reads the tree's heading nodes; WHICH `##` heading is a declared section comes
86
+ * from the registry's declared selectors.
294
87
  */
295
88
  export class HeadingScanner extends HomeExtractor {
296
89
  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) {
90
+ extract(registry, tree) {
91
+ return this.collect(registry, tree, this.homes);
92
+ }
93
+ /** The registered rank-2 section headings of a document, in document order —
94
+ * every rank-2 heading a declared element's selector claims, whichever home owns
95
+ * it (a section-home heading, the conditional-home headings and the design-body
96
+ * `## Design` are all section surfaces). A heading whose text is registered in no
97
+ * home (an undeclared prose section) is not a section. */
98
+ sectionsOf(registry, tree) {
344
99
  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;
100
+ for (const section of tree.sections()) {
101
+ if (!this.#declared(registry, tree, section.text))
358
102
  continue;
359
- }
360
- if (openHeading !== null)
361
- openLines.push(line);
103
+ out.push({ heading: section.text, lines: section.lines });
362
104
  }
363
- close();
364
105
  return out;
365
106
  }
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;
107
+ /** Whether a rank-2 heading line is a declared section surface — a registry
108
+ * element's `heading` selector accepts it. */
109
+ #declared(registry, tree, heading) {
110
+ return registry.elements.some((element) => element.selector.walk === "heading" && tree.matches(element.selector, heading));
378
111
  }
379
112
  }