@oscaner-skills/cdd-engine 1.0.0 → 3.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.
Files changed (120) hide show
  1. package/README.md +11 -10
  2. package/README.zh-CN.md +11 -10
  3. package/package.json +16 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  6. package/src-next/__tests__/floor.guard.test.ts +69 -0
  7. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  8. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  9. package/src-next/__tests__/smoke.integration.test.ts +185 -0
  10. package/src-next/__tests__/support/strip-comments.ts +99 -0
  11. package/src-next/__tests__/zero-dep.test.ts +94 -0
  12. package/src-next/bin.ts +61 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
  16. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
  19. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
  20. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
  21. package/src-next/contract/__tests__/declare.test.ts +481 -0
  22. package/src-next/contract/__tests__/doc.test.ts +527 -0
  23. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  24. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  25. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  26. package/src-next/contract/__tests__/judge.test.ts +1111 -0
  27. package/src-next/contract/__tests__/lint.test.ts +324 -0
  28. package/src-next/contract/__tests__/project.test.ts +460 -0
  29. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  30. package/src-next/contract/__tests__/translate.test.ts +96 -0
  31. package/src-next/contract/declare.ts +1071 -0
  32. package/src-next/contract/doc.ts +816 -0
  33. package/src-next/contract/frontmatter.ts +233 -0
  34. package/src-next/contract/home-extractors.ts +397 -0
  35. package/src-next/contract/invariants.ts +1413 -0
  36. package/src-next/contract/judge.ts +151 -0
  37. package/src-next/contract/lint.ts +239 -0
  38. package/src-next/contract/project.ts +656 -0
  39. package/src-next/contract/skill-anatomy.ts +301 -0
  40. package/src-next/contract/translate.ts +113 -0
  41. package/src-next/face/__tests__/board-view.test.ts +1151 -0
  42. package/src-next/face/__tests__/capsule.test.ts +300 -0
  43. package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
  44. package/src-next/face/__tests__/cli.test.ts +4897 -0
  45. package/src-next/face/__tests__/face.test.ts +289 -0
  46. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  47. package/src-next/face/__tests__/host.test.ts +24 -0
  48. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  49. package/src-next/face/__tests__/negation.ts +6 -0
  50. package/src-next/face/__tests__/preview.test.ts +374 -0
  51. package/src-next/face/__tests__/projection.test.ts +303 -0
  52. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  53. package/src-next/face/__tests__/termination.test.ts +650 -0
  54. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  55. package/src-next/face/artifacts.ts +248 -0
  56. package/src-next/face/board-view.ts +652 -0
  57. package/src-next/face/capsule.ts +163 -0
  58. package/src-next/face/cli.ts +1028 -0
  59. package/src-next/face/declare.ts +323 -0
  60. package/src-next/face/gate.ts +171 -0
  61. package/src-next/face/graph-view.ts +74 -0
  62. package/src-next/face/host.ts +302 -0
  63. package/src-next/face/lifecycle.ts +725 -0
  64. package/src-next/face/preview.ts +151 -0
  65. package/src-next/face/projection.ts +285 -0
  66. package/src-next/face/route-render.ts +185 -0
  67. package/src-next/face/termination.ts +573 -0
  68. package/src-next/face/words.ts +314 -0
  69. package/src-next/infra/__tests__/infra.test.ts +333 -0
  70. package/src-next/infra/__tests__/root.test.ts +56 -0
  71. package/src-next/infra/config.ts +42 -0
  72. package/src-next/infra/doc-roots.ts +29 -0
  73. package/src-next/infra/git.ts +39 -0
  74. package/src-next/infra/process.ts +34 -0
  75. package/src-next/infra/root.ts +73 -0
  76. package/src-next/infra/runtime.ts +132 -0
  77. package/src-next/infra/workspace.ts +322 -0
  78. package/src-next/render/__tests__/render.test.ts +550 -0
  79. package/src-next/render/__tests__/skeleton.test.ts +684 -0
  80. package/src-next/render/brief.ts +121 -0
  81. package/src-next/render/issue-body.ts +162 -0
  82. package/src-next/render/skeleton.ts +502 -0
  83. package/src-next/render/templates.ts +645 -0
  84. package/src-next/session/__tests__/graph.test.ts +277 -0
  85. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  86. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  87. package/src-next/session/__tests__/ledger.test.ts +745 -0
  88. package/src-next/session/__tests__/next.test.ts +460 -0
  89. package/src-next/session/__tests__/preflight.test.ts +545 -0
  90. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  91. package/src-next/session/__tests__/run.test.ts +1026 -0
  92. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  93. package/src-next/session/__tests__/wave.test.ts +476 -0
  94. package/src-next/session/faces.ts +110 -0
  95. package/src-next/session/graph.ts +411 -0
  96. package/src-next/session/handoff-schema.ts +373 -0
  97. package/src-next/session/ledger.ts +1076 -0
  98. package/src-next/session/next.ts +293 -0
  99. package/src-next/session/preflight.ts +271 -0
  100. package/src-next/session/round-naming.ts +84 -0
  101. package/src-next/session/run.ts +610 -0
  102. package/src-next/session/state.ts +30 -0
  103. package/src-next/session/wave.ts +139 -0
  104. package/templates/report/issue-body.json +17 -65
  105. package/dist/chunks/branch.mjs +0 -480
  106. package/dist/chunks/docs.mjs +0 -253
  107. package/dist/chunks/task.mjs +0 -913
  108. package/dist/cli.mjs +0 -5457
  109. package/dist/documents/schema/add-phase-protocol.json +0 -126
  110. package/dist/documents/schema/overall.json +0 -361
  111. package/dist/documents/schema/phase-spec.json +0 -145
  112. package/dist/documents/schema/plan.json +0 -191
  113. package/dist/documents/schema/skill-anatomy.json +0 -233
  114. package/dist/resources/harness-registry.json +0 -49
  115. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  116. package/templates/engine-config.json +0 -302
  117. package/templates/schema/cache-profile-schema.json +0 -23
  118. package/templates/schema/docs-handoff-schema.json +0 -129
  119. package/templates/schema/task-handoff-schema.json +0 -332
  120. package/templates/template-contract.json +0 -231
@@ -0,0 +1,121 @@
1
+ // packages/cdd-engine/src-next/render/brief.ts
2
+ // T12 — BriefRenderer: the task-brief renderer. The brief materializes the
3
+ // dispatch's `### Task N:` sections from a plan: extraction rides the contract
4
+ // parse face (doc.ts PlanDocType.parse — the same task-block parse instance the
5
+ // graph and the dispatch reuse), the step surface carries the `— checkable:`
6
+ // clause (the dispatch contract's evidence gate), and the rendered brief appends
7
+ // the plan's `## Constraints` section (the complete plan mirror). The checkable
8
+ // gate blocks step surfaces that carry a step
9
+ // with no checkable clause; a requested task with no matching heading blocks the
10
+ // whole render (the group-level out-of-bounds contract).
11
+
12
+ import type { TaskStep } from "../contract/doc.ts";
13
+ import { PlanDocType } from "../contract/doc.ts";
14
+
15
+ /** One parsed task-block field of the brief. */
16
+ export interface BriefField {
17
+ key: string;
18
+ lines: readonly string[];
19
+ }
20
+
21
+ /** One parsed task block of the brief — the plan's block + its checkable verdict. */
22
+ export interface BriefTask {
23
+ /** The task number. */
24
+ id: number;
25
+ /** The `### Task N: …` heading line verbatim. */
26
+ heading: string;
27
+ /** The block's keyed fields in document order. */
28
+ fields: readonly BriefField[];
29
+ /** The parsed `**Steps**` bullets. */
30
+ steps: readonly TaskStep[];
31
+ /** Whether every step carries a `— checkable:` clause. */
32
+ checkableComplete: boolean;
33
+ /** The step actions whose `— checkable:` clause is missing. */
34
+ missingCheckables: readonly string[];
35
+ }
36
+
37
+ /** The extraction outcome — the requested briefs + the out-of-bounds task ids. */
38
+ export interface BriefExtraction {
39
+ data: readonly BriefTask[];
40
+ missing: readonly number[];
41
+ }
42
+
43
+ /**
44
+ * The brief single renderer — pure data + content (no direct file system writes;
45
+ * the caller/CLI writes the rendered content into the workspace).
46
+ */
47
+ export class BriefRenderer {
48
+ readonly #parser: PlanDocType;
49
+
50
+ constructor(parser = new PlanDocType("plan")) {
51
+ this.#parser = parser;
52
+ }
53
+
54
+ /** The task-heading slices of the plan parse face (the render's parse-face consumption). */
55
+ taskHeadingPattern(): RegExp | undefined {
56
+ return this.#parser.slices.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
57
+ }
58
+
59
+ /** Extract the requested task blocks from a plan's content — the brief data. */
60
+ extract(planContent: string, tasks: readonly number[]): BriefExtraction {
61
+ const parsed = this.#parser.parse(planContent.split("\n"));
62
+ const byId = new Map(parsed.taskBlocks.map((block) => [block.id, block]));
63
+ const missing: number[] = [];
64
+ const data: BriefTask[] = [];
65
+ for (const id of new Set(tasks)) {
66
+ const block = byId.get(id);
67
+ if (block === undefined) {
68
+ missing.push(id);
69
+ continue;
70
+ }
71
+ const steps = block.steps;
72
+ const missingCheckables = steps
73
+ .filter((step) => step.checkable === null)
74
+ .map((step) => step.action);
75
+ data.push({
76
+ id: block.id,
77
+ heading: block.heading,
78
+ fields: block.fields,
79
+ steps,
80
+ checkableComplete: missingCheckables.length === 0,
81
+ missingCheckables,
82
+ });
83
+ }
84
+ return { data, missing };
85
+ }
86
+
87
+ /** Render the brief content — the requested task sections + the plan's
88
+ * `## Constraints` section (the complete plan mirror). Any requested task without
89
+ * a heading blocks the whole render (out-of-bounds). */
90
+ render(planContent: string, tasks: readonly number[]): string {
91
+ const { data, missing } = this.extract(planContent, tasks);
92
+ if (missing.length > 0) {
93
+ throw new Error(
94
+ `task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`,
95
+ );
96
+ }
97
+ const lines = planContent.split("\n");
98
+ const sections = data.map((task) =>
99
+ this.#rawSection(lines, (line) => line.startsWith(`### Task ${task.id}:`)),
100
+ );
101
+ const constraints = this.#rawSection(lines, (line) => line.trimEnd() === "## Constraints");
102
+ const body =
103
+ constraints === "" ? sections.join("\n\n") : `${sections.join("\n\n")}\n\n${constraints}`;
104
+ return `${body}\n`;
105
+ }
106
+
107
+ /** The shared heading slice — from the first line a matcher accepts to the next
108
+ * heading line ("" when nothing matches). Both the `### Task N:` sections and the
109
+ * `## Constraints` mirror render through this one shape. */
110
+ #rawSection(lines: readonly string[], match: (line: string) => boolean): string {
111
+ const start = lines.findIndex(match);
112
+ if (start === -1) return "";
113
+ const out: string[] = [];
114
+ for (let i = start; i < lines.length; i++) {
115
+ const line = lines[i];
116
+ if (i > start && /^#/.test(line)) break;
117
+ out.push(line);
118
+ }
119
+ return out.join("\n").replace(/\s+$/, "");
120
+ }
121
+ }
@@ -0,0 +1,162 @@
1
+ // packages/cdd-engine/src-next/render/issue-body.ts
2
+ // T19 — IssueBodyRenderer (the P7 translation-system render landing): the aggregate
3
+ // issue body's steady renderer, relocated from face/cli.ts (T11's composition root
4
+ // only assembles it — the renderer owns no CLI). The language/label plane is
5
+ // data-driven:
6
+ //
7
+ // · the finding-type vocabulary is the renderer's declared steady set (bug /
8
+ // enhancement / chore — the input contract's type domain);
9
+ // · the language vocabulary is the word table's locale key projection (the langs
10
+ // derivation — localeKeys(), never a hardcoded list);
11
+ // · every label the body emits rides the word table's locale rows through the
12
+ // Translator (the bidirectional layer — localize(canonical, locale) renders the
13
+ // locale-normalized output). The capsule machine face (status · next: ·
14
+ // CDD_BLOCKED:) is deliberately NOT in the locale rows — English-constant, never
15
+ // localized.
16
+ //
17
+ // Module-level exports are types / the class — zero behavior-carrying bare functions.
18
+
19
+ import type { Translator, WordLocaleFace } from "../contract/translate.ts";
20
+ import { ISSUE_TYPES } from "../face/words.ts";
21
+
22
+ /** One finding row of the issue-report input. */
23
+ export interface ReportFindingInput {
24
+ type: string;
25
+ lang: string;
26
+ context: string;
27
+ problem: string;
28
+ impact: string;
29
+ suggestedFix: string;
30
+ meta: { skill: string; step: string };
31
+ }
32
+
33
+ /** The issue-report input contract — the stdin findings plane. */
34
+ export interface IssueReportInput {
35
+ harness: string;
36
+ findings: readonly ReportFindingInput[];
37
+ related?: {
38
+ open?: readonly { issue: number; component: string; reason: string }[];
39
+ closed?: readonly { issue: number }[];
40
+ program?: { issue: number };
41
+ };
42
+ }
43
+
44
+ /**
45
+ * The issue-body renderer — the aggregate issue body's steady renderer (the finding
46
+ * type/lang vocabularies and the segment labels live on the declared data — the type
47
+ * set on the renderer, the locale keys + label rows on the word table, never a second
48
+ * source): Session block → per-finding four-segment blocks with attribution → Dedup
49
+ * (open hits) → Related (closed hits + program). Pure deterministic text.
50
+ */
51
+ export class IssueBodyRenderer {
52
+ /** The finding-type vocabulary (the canonical type set) — the word table's
53
+ * `ISSUE_TYPES` (derived from the issue-label rows, the ONE type source), never a
54
+ * second hand-written list. */
55
+ readonly types: readonly string[] = ISSUE_TYPES;
56
+ /** The four text-segment keys, in the render order. */
57
+ readonly #segments: readonly string[] = ["context", "problem", "impact", "suggestedFix"];
58
+ /** The word table's locale face — the langs projection + the label rows. */
59
+ readonly #words: WordLocaleFace;
60
+ /** The translation layer — the label rows localize through it (locale-normalized render). */
61
+ readonly #translator: Translator;
62
+
63
+ constructor(words: WordLocaleFace, translator: Translator) {
64
+ this.#words = words;
65
+ this.#translator = translator;
66
+ }
67
+
68
+ /** The rendered language vocabulary — the word table's locale key projection (the
69
+ * langs derivation: a locale-key change in the word table re-projects this face). */
70
+ langs(): readonly string[] {
71
+ return this.#words.localeKeys();
72
+ }
73
+
74
+ /** The canonical `meta` bullet lines of one finding (the two attribution rows). */
75
+ #metaOf(meta: { skill: string; step: string }): string {
76
+ return `- Skill: ${meta.skill}\n- Step: ${meta.step}`;
77
+ }
78
+
79
+ /** One finding's segment label — the word table's label row localized to the
80
+ * finding's lang (localize(canonical, locale); an unknown row — impossible under
81
+ * the completeness pin — falls back to the canonical English face). */
82
+ #labelOf(finding: ReportFindingInput, segment: string): string {
83
+ const row = this.#words.localeRow(`${finding.type}.${segment}`);
84
+ if (row === null) return segment;
85
+ return this.#translator.localize(row.en, finding.lang) ?? row.en;
86
+ }
87
+
88
+ /** One finding's block — the four labeled segments plus the attribution. */
89
+ #findingOf(finding: ReportFindingInput): string {
90
+ const parts = this.#segments.map(
91
+ (segment) =>
92
+ `${this.#labelOf(finding, segment)}\n\n${String(finding[segment as keyof ReportFindingInput])}`,
93
+ );
94
+ return [...parts, this.#metaOf(finding.meta)].join("\n\n");
95
+ }
96
+
97
+ /** Render the aggregate issue body — deterministic: the Session block (harness
98
+ * line), the findings in input order, then the Dedup / Related tails. */
99
+ renderBody(input: IssueReportInput): string {
100
+ const parts: string[] = [`# CDD aggregate issue\n\n- Harness: ${input.harness}`];
101
+ for (const finding of input.findings) parts.push(this.#findingOf(finding));
102
+ const open = input.related?.open ?? [];
103
+ if (open.length > 0) {
104
+ parts.push(
105
+ `## Dedup\n${open.map((hit) => `- Dedup → #${hit.issue} (open):${hit.component} · ${hit.reason}`).join("\n")}`,
106
+ );
107
+ }
108
+ const closed = input.related?.closed ?? [];
109
+ const program = input.related?.program;
110
+ if (closed.length > 0 || program !== undefined) {
111
+ const lines: string[] = [];
112
+ for (const hit of closed) lines.push(`- Regression / follow-up of #${hit.issue} (closed)`);
113
+ if (program !== undefined) lines.push(`- Program: #${program.issue}`);
114
+ parts.push(`## Related\n${lines.join("\n")}`);
115
+ }
116
+ return parts.join("\n\n");
117
+ }
118
+
119
+ /** Input-shape validation — the E-3 early-report contract (field paths, empty =
120
+ * pass). The canonical type set and the word-table locale projection are the single
121
+ * declared vocabularies. */
122
+ validateInput(raw: unknown): string[] {
123
+ const errors: string[] = [];
124
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw))
125
+ return ["input: expected an object with harness / findings / related?"];
126
+ const input = raw as { harness?: unknown; findings?: unknown; related?: unknown };
127
+ if (typeof input.harness !== "string" || input.harness.length === 0)
128
+ errors.push("harness: non-empty string required");
129
+ if (!Array.isArray(input.findings) || input.findings.length === 0) {
130
+ errors.push("findings: non-empty array of findings required");
131
+ } else {
132
+ input.findings.forEach((rawFinding, i) => {
133
+ const finding = rawFinding as Record<string, unknown> | null;
134
+ const base = `findings[${i}]`;
135
+ if (typeof finding !== "object" || finding === null) {
136
+ errors.push(
137
+ `${base}: object with type/lang/context/problem/impact/suggestedFix/meta expected`,
138
+ );
139
+ return;
140
+ }
141
+ if (!this.types.includes(String(finding.type)))
142
+ errors.push(`${base}.type: must be one of ${this.types.join(" | ")}`);
143
+ if (!this.langs().includes(String(finding.lang)))
144
+ errors.push(`${base}.lang: must be one of ${this.langs().join(" | ")}`);
145
+ for (const field of this.#segments) {
146
+ if (typeof finding[field] !== "string" || (finding[field] as string).length === 0)
147
+ errors.push(`${base}.${field}: non-empty string required`);
148
+ }
149
+ const meta = finding.meta as Record<string, unknown> | null | undefined;
150
+ if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
151
+ errors.push(`${base}.meta: object with skill / step required`);
152
+ } else {
153
+ if (typeof meta.skill !== "string" || meta.skill.length === 0)
154
+ errors.push(`${base}.meta.skill: non-empty string required`);
155
+ if (typeof meta.step !== "string" || meta.step.length === 0)
156
+ errors.push(`${base}.meta.step: non-empty string required`);
157
+ }
158
+ });
159
+ }
160
+ return errors;
161
+ }
162
+ }