@oscaner-skills/cdd-engine 2.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 (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,109 @@
1
+ // packages/cdd-engine/src-next/contract/judge.ts
2
+ // T4 — the single interpreter's coordinator (design spec §2.1): the Contract
3
+ // class's validate() is the ONLY entry for structural judgment. It loads the
4
+ // parse context through the doc-type parsers (doc.ts — pure parse), composes the
5
+ // per-doc-key invariant strategy set (invariants.ts) as declared data, runs every
6
+ // strategy in order, and aggregates the findings. Judgment dispatch is a record
7
+ // index over the declared strategy set — zero switch-case, zero hand-written
8
+ // judgment branches in this module (the plan's coordinator semantics: the
9
+ // polymorphic strategy family judges, the coordinator assembles).
10
+ import { Words } from "../face/words.js";
11
+ import { declaredRegistries } from "./declare.js";
12
+ import { docTypeParsers } from "./doc.js";
13
+ import { FrontMatterExtractor } from "./frontmatter.js";
14
+ import { ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, HollowInvariant, LinkShapeInvariant, NodeFs, OrderInvariant, PresenceInvariant, ResidueInvariant, SectionScopedDomainInvariant, SelfBoundedInvariant, SiblingScanInvariant, UniquenessInvariant, } from "./invariants.js";
15
+ import { DOC_KEYS, Projector } from "./project.js";
16
+ import { Translator } from "./translate.js";
17
+ /**
18
+ * The contract coordinator — the interpreter's single face. One instance; the
19
+ * strategy set is stateless (each strategy reads its judgment data from the
20
+ * context), so construction is cheap and validates compose safely.
21
+ *
22
+ * The P7 structure-plane canonicalize seam (design spec §2.1) + the T6 front-matter
23
+ * delivery seam (§2.2): the Contract self-holds a Translator, and validate()
24
+ * canonicalizes EVERY body line once at the row source — the normalized view
25
+ * shared by parse and JudgeContext.lines. The split order is RAW-first: the raw
26
+ * content resolves its front-matter head BEFORE any canonicalize (front matter is
27
+ * data — the canonicalize view would silently rewrite registered Chinese aliases
28
+ * inside header values), then the post-fence body lines canonicalize and the SAME
29
+ * typed head rides into parse(lines, head) and JudgeContext.head. Every
30
+ * valuePattern judgment face (presence occurrenceLines · domain carrierLines ·
31
+ * section-scoped · crosslink) matches the view, so the legacy Chinese charter
32
+ * markers (the doc-arch decision-group / upstream-endorsements leaves) match their
33
+ * English canonical element patterns through the recognition face — never a second
34
+ * hand-written zh pattern. The view is never written back: the source document
35
+ * stays byte-identical and the original lines remain in input.content.
36
+ */
37
+ export class Contract {
38
+ /** The per-doc-key policy sets — the declared composition of the strategy family.
39
+ * All thirteen strategies are registry-driven and judge every doc type, so the
40
+ * per-key sets are the same ordered family; the record keying is what a future
41
+ * per-type ordering/selection change would carry. */
42
+ #strategies;
43
+ /** The projection carrier — the derived parse/skeleton faces the judgment reads. */
44
+ #projector;
45
+ /** The row-source translator — the canonicalize seam carrier. One instance over
46
+ * the same locale word table the rest of the plane reads (the recognition face
47
+ * of the P7 translation layer); embedded like the projector, so the production
48
+ * construction points (`new Contract()`) stay argument-free. */
49
+ #translator;
50
+ constructor() {
51
+ this.#strategies = Contract.#buildPolicy();
52
+ this.#projector = new Projector(declaredRegistries);
53
+ this.#translator = new Translator(new Words());
54
+ }
55
+ /** validate(doc) — split, parse, compose, run, aggregate. The single judgment entry.
56
+ * The RAW content resolves its front-matter head first (the data plane — never
57
+ * canonicalized); the post-fence body lines canonicalize ONCE at the row source
58
+ * (the normalized view), and the SAME typed head rides into parse(lines, head)
59
+ * and JudgeContext.head (§2.2's delivery seam — the chain facts the head carries
60
+ * are the same record the invariants judge). The source stays intact. */
61
+ validate(input) {
62
+ const { head, body } = FrontMatterExtractor.split(input.content);
63
+ const lines = body.split("\n").map((line) => this.#translator.canonicalize(line));
64
+ const parsed = docTypeParsers[input.docKey].parse(lines, head);
65
+ const context = {
66
+ docKey: input.docKey,
67
+ parsed,
68
+ head,
69
+ lines,
70
+ path: input.path,
71
+ root: input.root,
72
+ slices: this.#projector.slices()[input.docKey],
73
+ shape: this.#projector.shape()[input.docKey],
74
+ registries: declaredRegistries,
75
+ phaseId: input.phaseId,
76
+ chainDocs: input.chainDocs,
77
+ fs: input.fs ?? new NodeFs(),
78
+ };
79
+ const findings = [];
80
+ for (const strategy of this.#strategies[input.docKey]) {
81
+ findings.push(...strategy.evaluate(context));
82
+ }
83
+ return findings;
84
+ }
85
+ /** The declared strategy composition — one ordered family set per doc key. */
86
+ static #buildPolicy() {
87
+ const family = [
88
+ new PresenceInvariant(),
89
+ new UniquenessInvariant(),
90
+ new DomainInvariant(),
91
+ new CrosslinkInvariant(),
92
+ new OrderInvariant(),
93
+ new ContinuityInvariant(),
94
+ new ResidueInvariant(),
95
+ new HollowInvariant(),
96
+ new SelfBoundedInvariant(),
97
+ new LinkShapeInvariant(),
98
+ new FileExistenceInvariant(),
99
+ new SiblingScanInvariant(),
100
+ new CrossDocChainInvariant(),
101
+ new SectionScopedDomainInvariant(),
102
+ ];
103
+ const policy = {};
104
+ for (const key of DOC_KEYS) {
105
+ policy[key] = family;
106
+ }
107
+ return policy;
108
+ }
109
+ }
@@ -0,0 +1,206 @@
1
+ // packages/cdd-engine/src-next/contract/lint.ts
2
+ // T5 — the reference lint WARN pass (design spec §2.3): an independent observation
3
+ // face that runs at the dispatch gate, never part of the judgment definition.
4
+ // The reference vocabulary it applies is the derived projection (project.ts —
5
+ // `Projector.reference()`, the per-element reference rows) — zero self-copied
6
+ // reference patterns. The lint consumes the SAME doc.ts parse record the dispatch
7
+ // and the graph read (parse once, reuse everywhere), so its observations are
8
+ // anchored on the parsed task blocks and the chain root, never a re-scan of raw
9
+ // text.
10
+ //
11
+ // The WARN families:
12
+ // · missing-edge suspect (plan) — a backward `Task N` / `T<N>` prose reference
13
+ // inside a task's Objective/Acceptance value that has no matching
14
+ // `- **DependsOn**:` declaration. The graph's edge classes never fire here:
15
+ // unregistered targets (missing-id) and self-edges (self-loop) stay silent —
16
+ // a suspect is always an existing task with a lower id whose edge was simply
17
+ // not declared (forward references are legal — no contradiction class).
18
+ //
19
+ // The cross-doc label-drift observation (Class-B `parent-program:` label vs
20
+ // target basename) retired with the ChainLink label face at the front-matter flip
21
+ // (T6) — the chain facts ride the typed head scalars, a link label is not a fact.
22
+ //
23
+ // Every warning is a Warn — a WARN-only observation, never a Finding, never a
24
+ // BLOCK. Module-level exports are types / the class — zero behavior-carrying
25
+ // bare functions (the plan's zero-bare-function discipline).
26
+ import { declaredRegistries } from "./declare.js";
27
+ import { MarkdownPrimitives } from "./doc.js";
28
+ import { Projector } from "./project.js";
29
+ /**
30
+ * The reference-lint pass — the WARN observation face over the derived reference
31
+ * vocabulary. One instance; every reference pattern it applies is read from the
32
+ * projection, never re-typed. The prose scan surface (Objective / Acceptance) is
33
+ * a scanning-semantics decision, tied to the vocabulary by a construction guard
34
+ * that fails loudly if the plan registry renames either prose field.
35
+ */
36
+ export class LintPass extends MarkdownPrimitives {
37
+ /** The derived reference vocabulary — the single source the lint applies. */
38
+ #reference;
39
+ /** The derived `Task prose reference` token pattern (global — matchAll over prose lines). */
40
+ #proseToken;
41
+ /** The derived `DependsOn id` value pattern (whole-token — the declared-edge values). */
42
+ #depIdToken;
43
+ /** The prose-owning task fields of the plan — the scanning-semantics surface. */
44
+ #proseFieldKeys = ["Objective", "Acceptance"];
45
+ constructor() {
46
+ super();
47
+ this.#reference = new Projector(declaredRegistries).reference();
48
+ const planEntries = this.#reference.plan.entries;
49
+ this.#proseToken = new RegExp(this.#valuePatternOf(planEntries, "Task prose reference"), "g");
50
+ this.#depIdToken = new RegExp(this.#valuePatternOf(planEntries, "DependsOn id"));
51
+ for (const key of this.#proseFieldKeys) {
52
+ this.#valuePatternOf(planEntries, `**${key}**`);
53
+ }
54
+ }
55
+ /** run — the single observation entry: one Warn per offending surface. */
56
+ run(input) {
57
+ const warns = [];
58
+ if (input.parsed.docType === "plan") {
59
+ warns.push(...this.#missingEdgeWarns(input, input.parsed));
60
+ warns.push(...this.#numberingAdvisories(input, input.parsed));
61
+ warns.push(...this.#transitiveAdvisories(input, input.parsed));
62
+ }
63
+ return warns;
64
+ }
65
+ // -------------------------------------------------------------------------
66
+ // the missing-edge suspect scan (plan)
67
+ // -------------------------------------------------------------------------
68
+ /** One WARN per task block whose prose references an existing lower task with no edge. */
69
+ #missingEdgeWarns(input, parsed) {
70
+ const warns = [];
71
+ const registered = new Set(parsed.taskBlocks.map((block) => block.id));
72
+ for (const block of parsed.taskBlocks) {
73
+ const declared = this.#declaredEdgesOf(block);
74
+ const suspects = this.#suspectRefsOf(block, declared, registered);
75
+ if (suspects.length === 0)
76
+ continue;
77
+ const list = suspects.map((id) => `Task ${id}`).join(" and ");
78
+ warns.push({
79
+ path: input.path,
80
+ field: `Task ${block.id}`,
81
+ message: `task ${block.id} prose-references ${list} with no matching **DependsOn** declaration — a suspected missing edge (WARN: the author's intent is authoritative, never a gate)`,
82
+ fix: `declare the edge in the block's **DependsOn** line, or treat the reference as prose (task ${list})`,
83
+ kind: "reference-lint",
84
+ });
85
+ }
86
+ return warns;
87
+ }
88
+ /** One WARN per forward reference (a dep on a higher-numbered task) — the numbering
89
+ * read-order advisory (T24: legal after the anti-dependency gate retired, but a
90
+ * hint that the numbering no longer follows the topological reading order). */
91
+ #numberingAdvisories(input, parsed) {
92
+ const warns = [];
93
+ for (const block of parsed.taskBlocks) {
94
+ for (const dep of this.#declaredEdgesOf(block)) {
95
+ if (dep <= block.id)
96
+ continue;
97
+ warns.push({
98
+ path: input.path,
99
+ field: `Task ${block.id}`,
100
+ message: `task ${block.id} depends on the higher-numbered Task ${dep} — legal (forward references), but the numbering no longer follows the topological reading order; consider renumbering (advisory only)`,
101
+ fix: "renumber the pair for a linear reading order, or keep the forward dependency — the engine derives waves from **DependsOn** alone",
102
+ kind: "reference-lint",
103
+ });
104
+ }
105
+ }
106
+ return warns;
107
+ }
108
+ /** One WARN per transitively-redundant declaration (a dep d reachable from another
109
+ * declared dep) — the direct-only advisory: redundant edges are harmless (the
110
+ * waves derive over the closure) but clutter the display, so the engine hints
111
+ * the author to declare direct prerequisites only. */
112
+ #transitiveAdvisories(input, parsed) {
113
+ const warns = [];
114
+ const declared = new Map();
115
+ for (const block of parsed.taskBlocks)
116
+ declared.set(block.id, this.#declaredEdgesOf(block));
117
+ const reachOf = (from) => {
118
+ const seen = new Set();
119
+ const stack = [...(declared.get(from) ?? [])];
120
+ while (stack.length > 0) {
121
+ const current = stack.pop();
122
+ if (seen.has(current))
123
+ continue;
124
+ seen.add(current);
125
+ stack.push(...(declared.get(current) ?? []));
126
+ }
127
+ return seen;
128
+ };
129
+ const reach = new Map();
130
+ for (const id of declared.keys())
131
+ reach.set(id, reachOf(id));
132
+ for (const block of parsed.taskBlocks) {
133
+ for (const dep of declared.get(block.id) ?? []) {
134
+ const redundantVia = [...(declared.get(block.id) ?? [])].find((other) => other !== dep && (reach.get(other) ?? new Set()).has(dep));
135
+ if (redundantVia === undefined)
136
+ continue;
137
+ warns.push({
138
+ path: input.path,
139
+ field: `Task ${block.id}`,
140
+ message: `task ${block.id} depends on Task ${dep}, already reachable via declared dependency Task ${redundantVia} — declare direct prerequisites only (advisory: redundant edges are inert for the wave derivation, but clutter the graph)`,
141
+ fix: `drop ${dep} from the block's **DependsOn** (or keep it — the engine reduces the display, the closure is unchanged)`,
142
+ kind: "reference-lint",
143
+ });
144
+ }
145
+ }
146
+ return warns;
147
+ }
148
+ /** The block's declared edge ids — read from its **DependsOn** VALUE PREFIX only
149
+ * (the first `(`/`(` truncates — a trailing parenthetical's numbers are prose,
150
+ * never an edge; the same §3.8 value-domain contract the graph's extractor keeps). */
151
+ #declaredEdgesOf(block) {
152
+ const edges = new Set();
153
+ const field = block.fields.find((entry) => entry.key === "DependsOn");
154
+ if (field === undefined)
155
+ return edges;
156
+ for (const line of field.lines) {
157
+ const prefix = line.split(/[((]/)[0];
158
+ for (const token of prefix.split(/[,\s]+/)) {
159
+ if (this.#depIdToken.test(token.trim()))
160
+ edges.add(Number(token.trim()));
161
+ }
162
+ }
163
+ return edges;
164
+ }
165
+ /** The backward prose references of a block that exist, are undeclared and are not a
166
+ * code-span citation — the missing-edge suspects. */
167
+ #suspectRefsOf(block, declared, registered) {
168
+ const suspects = [];
169
+ const seenId = new Set();
170
+ for (const field of block.fields) {
171
+ if (!this.#proseFieldKeys.includes(field.key))
172
+ continue;
173
+ for (const line of field.lines) {
174
+ const prose = this.#withoutCodeSpans(line);
175
+ for (const match of prose.matchAll(this.#proseToken)) {
176
+ const id = Number(match[1]);
177
+ if (id >= block.id)
178
+ continue; // forward / self — undeclareable, never a suspect
179
+ if (!registered.has(id))
180
+ continue; // missing-id — the graph's class, never a suspect
181
+ if (declared.has(id) || seenId.has(id))
182
+ continue;
183
+ seenId.add(id);
184
+ suspects.push(id);
185
+ }
186
+ }
187
+ }
188
+ return suspects.sort((a, b) => a - b);
189
+ }
190
+ /** The line with its backtick-delimited inline code spans removed (a span cites a symbol, never prose). */
191
+ #withoutCodeSpans(line) {
192
+ return line.replace(/`+[^`\n]*`+/g, "");
193
+ }
194
+ // -------------------------------------------------------------------------
195
+ // construction helpers
196
+ // -------------------------------------------------------------------------
197
+ /** The value pattern of a registered reference entry — a lookup that fails
198
+ * loudly when the declaration renames an anchor the lint consumes. */
199
+ #valuePatternOf(entries, anchor) {
200
+ const entry = entries.find((row) => row.anchor === anchor);
201
+ if (entry === undefined) {
202
+ throw new Error(`reference-lint requires the registered reference entry "${anchor}"`);
203
+ }
204
+ return entry.valuePattern ?? "";
205
+ }
206
+ }