@oscaner-skills/cdd-engine 2.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 (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -0,0 +1,151 @@
1
+ // packages/cdd-engine/src-next/face/preview.ts
2
+ // P11 T5 — the `--dry-run` preview renderer (spec §3.3): the read-only next-step
3
+ // forecast becomes ONE renderer class instead of a simulated run. The preview states
4
+ // the step the next real invocation would dispatch, the artifacts it would write and
5
+ // the ledger writes it would record — and nothing else: zero repo writes, no round
6
+ // consumed, no child spawned. The retired synthetic dispatch (`() => ({ status:
7
+ // "APPROVED", findings: [] })`) is gone with it — a preview never fabricates a
8
+ // conclusion, so no `status:` / `next:` line is ever printed.
9
+ //
10
+ // The renderer reads the assembled scene (the same DispatchScene the lifecycle
11
+ // dispatch reads — one scene shape, never a second) and names every artifact through
12
+ // RoundNaming (session/round-naming.ts), the ONE naming source the lifecycle's
13
+ // write-back and read-back share (T4): the preview and the real dispatch name the
14
+ // same files by one rule. The `child:` row is the harness contract's own data
15
+ // (face/host.ts) — the host id + the row's invoke argument string — never a
16
+ // detection-dependent spawn.
17
+ //
18
+ // Module-level exports are the class — zero behavior-carrying bare functions.
19
+
20
+ import process from "node:process";
21
+ import type { RepoRoot } from "../infra/root.ts";
22
+ import { RoundNaming } from "../session/round-naming.ts";
23
+ import type { OpenFrame } from "../session/run.ts";
24
+ import type { CliVerb } from "./declare.ts";
25
+ import { HOSTS, HostDetect, type HostId } from "./host.ts";
26
+ import type { DispatchScene, ProcessEnvLike } from "./lifecycle.ts";
27
+
28
+ /** The preview row's label column width — ` ` + the label padded to this width +
29
+ * one space places every value at the same column (`would record:` — the longest
30
+ * label — overflows by its own one character, exactly as the §3.3 block reads). */
31
+ const LABEL_WIDTH = 12;
32
+
33
+ /**
34
+ * Preview — the `--dry-run` read-only preview renderer. One instance renders one
35
+ * invocation's block over the scene the work command already assembled; the host is
36
+ * detected once at construction (the injectable-env adapter over the harness
37
+ * contract's own judgment). Nothing in this class writes, dispatches or records.
38
+ */
39
+ export class Preview {
40
+ readonly #scene: DispatchScene;
41
+ /** The round-naming single source (P11 T4) — the same derivations the lifecycle's
42
+ * write-back and read-back read, so the preview never invents a name. */
43
+ readonly #naming: RoundNaming;
44
+ /** The detected host id ("" when no harness marker matched) — read by the `child:`
45
+ * row only. */
46
+ readonly #host: HostId | "";
47
+
48
+ constructor(opts: { scene: DispatchScene; env?: ProcessEnvLike }) {
49
+ this.#scene = opts.scene;
50
+ this.#naming = new RoundNaming(opts.scene.workspace);
51
+ this.#host = HostDetect.detect(opts.env ?? process.env);
52
+ }
53
+
54
+ /** The invocation's stdout block — the header plus the five rows (§3.3). Every
55
+ * path token is repoRoot-relative (D47's ONE shape — the same basis the round
56
+ * context speaks). No `status:` / `next:` line is emitted: the round's conclusion
57
+ * is not yet decided (printing one would fabricate it) and the cross-round next
58
+ * hop belongs to `cdd board <slug>`. */
59
+ render(verb: CliVerb, frame: OpenFrame): readonly string[] {
60
+ const rows: readonly (readonly [string, string])[] = [
61
+ ["step:", this.#stepOf(frame)],
62
+ ["reads:", this.#readsOf(frame)],
63
+ ["would write:", this.#writesOf(frame)],
64
+ ["would record:", this.#recordsOf(frame)],
65
+ ["child:", this.#childOf()],
66
+ ];
67
+ return [
68
+ `cdd ${verb}: preview (no repo changes)`,
69
+ ...rows.map(([label, value]) => ` ${label.padEnd(LABEL_WIDTH)} ${value}`),
70
+ ];
71
+ }
72
+
73
+ /** The next dispatch step's identity — `<phase> round <round> — <target>`, the
74
+ * target being the wave unit (`wave 1,2`) or the line's own type word. */
75
+ #stepOf(frame: OpenFrame): string {
76
+ return `${frame.phase} round ${frame.round} — ${this.#targetOf(frame)}`;
77
+ }
78
+
79
+ /** The step's target word — the wave-unitary unit (the whole ready batch) on the
80
+ * task face, the line type elsewhere. */
81
+ #targetOf(frame: OpenFrame): string {
82
+ return frame.target.kind === "wave" ? `wave ${frame.target.tasks.join(",")}` : frame.type;
83
+ }
84
+
85
+ /** The round's read input — the wave face's brief (the ONE engine-rendered brief
86
+ * the real dispatch re-extracts from the CURRENT plan; the preview does not render
87
+ * it, so the row states what that render would produce) and the doc/branch faces'
88
+ * judged document. */
89
+ #readsOf(frame: OpenFrame): string {
90
+ if (frame.target.kind === "wave") {
91
+ const brief = this.#rel(this.#naming.brief(frame.target.tasks.join(",")));
92
+ return `${brief} (would re-render from the current plan)`;
93
+ }
94
+ if (frame.target.kind === "plan" || frame.target.kind === "spec")
95
+ return this.#rel(frame.target.doc);
96
+ return this.#rel(this.#scene.planPath ?? "");
97
+ }
98
+
99
+ /** The artifacts the round would write — the frame's prescribed output set (the
100
+ * handoff carrier, the round report and the work faces' test evidence), named by
101
+ * the ONE naming source. A slot the frame's family does not consume (a review
102
+ * round prescribes no evidence file) is dropped, never rendered blank. */
103
+ #writesOf(frame: OpenFrame): string {
104
+ return [
105
+ this.#scene.ledger.handoffPath(this.#naming.op(frame), frame.type, frame.params),
106
+ this.#naming.report(frame),
107
+ this.#naming.evidence(frame),
108
+ ]
109
+ .filter((artifact) => artifact !== "")
110
+ .map((artifact) => this.#rel(artifact))
111
+ .join(" · ");
112
+ }
113
+
114
+ /** The ledger writes the round would record — the progress cycle (the frame's OWN
115
+ * round identity, never a flattened ordinal) plus, on a completed review, the
116
+ * reviewed-revision write-back. The three legs are `#bookkeep`'s own: the doc line
117
+ * binds its document's revision, the wave line its RENDERED brief's, and the
118
+ * branch line binds none (its review judges the live tree). */
119
+ #recordsOf(frame: OpenFrame): string {
120
+ const parts = [`progress.waves["${frame.key}"].rounds.${frame.phase} += [${frame.round}]`];
121
+ if (frame.phase === "review") {
122
+ if (frame.target.kind === "wave") parts.push("reviewedRevision(brief)");
123
+ else if (frame.target.kind === "plan" || frame.target.kind === "spec")
124
+ parts.push("reviewedRevision(doc)");
125
+ }
126
+ return parts.join(" · ");
127
+ }
128
+
129
+ /** The child invocation the real run would spawn — `<HostId> <invoke>`: the host
130
+ * id then the harness row's invoke argument string verbatim (the binary name is a
131
+ * separate row column and never rides the invoke value). With no host detected the
132
+ * real run would BLOCK before any spawn — the row states that literal rather than
133
+ * indexing an absent host row. */
134
+ #childOf(): string {
135
+ if (this.#host === "") return "(no host detected — real run would BLOCK)";
136
+ return `${this.#host} ${HOSTS[this.#host].invoke}`;
137
+ }
138
+
139
+ /** The repoRoot-relative form of one path token (D47). The empty value stays
140
+ * empty — a dropped slot is never rendered as the repo root. */
141
+ #rel(value: string): string {
142
+ return value === "" ? "" : this.#repoRootValue().relativize(value);
143
+ }
144
+
145
+ /** The repo-basis value object of this scene — the ONE conversion entry every path
146
+ * token normalizes through (the workspace root's OWN value object, never
147
+ * re-wrapped here). */
148
+ #repoRootValue(): RepoRoot {
149
+ return this.#scene.workspace.root.basis;
150
+ }
151
+ }
@@ -75,7 +75,10 @@ export class CommandTreeBuilder {
75
75
  // same thrown errors.
76
76
  this.program.exitOverride();
77
77
  this.program.description("the CDD engine's command line");
78
- this.program.addHelpText("afterAll", "program flags (accepted at any position): --dry-run");
78
+ this.program.addHelpText(
79
+ "afterAll",
80
+ "program flags (accepted at any position): --dry-run (implement/review/fix only)",
81
+ );
79
82
  this.#bindProgramScopes(this.program);
80
83
  this.#injectProgramExamples();
81
84
  for (const spec of CLI_COMMANDS) this.#projectCommand(spec);
@@ -19,6 +19,7 @@
19
19
  // declared constants from session/next.ts, rendered by reference, never restated.
20
20
  // Module-level exports are the class — zero behavior-carrying bare functions.
21
21
 
22
+ import type { RepoRoot } from "../infra/root.ts";
22
23
  import type { RouteTarget } from "../session/faces.ts";
23
24
  import { FIX_READBACK_SUFFIX, type Route } from "../session/next.ts";
24
25
  import { REFS } from "./host.ts";
@@ -46,11 +47,30 @@ export class RouteRenderer {
46
47
  /** The host harness id — the skill-ref resolution key of the handoff/`done`
47
48
  * pipeline lookup (REFS[ref][host]; `""` falls back to the claude form). */
48
49
  readonly #host: string;
50
+ /** The repo-basis value object the literal's embedded path values normalize
51
+ * through (T1 `RepoRoot` · D47) — the ONE conversion exit; `null` (the
52
+ * hermetic-test default) passes values through unchanged. */
53
+ readonly #root: RepoRoot | null;
49
54
 
50
- constructor(words: Words, channels: Readonly<Record<string, RouteChannelRow>> = {}, host = "") {
55
+ constructor(
56
+ words: Words,
57
+ channels: Readonly<Record<string, RouteChannelRow>> = {},
58
+ host = "",
59
+ root: RepoRoot | null = null,
60
+ ) {
51
61
  this.#words = words;
52
62
  this.#channels = channels;
53
63
  this.#host = host;
64
+ this.#root = root;
65
+ }
66
+
67
+ /** One embedded path value in the literal — normalized to the repoRoot-relative
68
+ * shape through the ONE value object (D47 · the ONE basis; a `null` root — the
69
+ * hermetic default — short-circuits). Every `--plan`/`--reviews`/doc-id in the
70
+ * rendered argv passes through here, so the board's `next:` and the engine's
71
+ * `next:` are byte-identical by construction. */
72
+ #rel(value: string): string {
73
+ return this.#root === null ? value : this.#root.relativize(value);
54
74
  }
55
75
 
56
76
  /** render(route, target) → the `next:` value: the complete executable command (a
@@ -82,10 +102,11 @@ export class RouteRenderer {
82
102
  }
83
103
 
84
104
  /** The plan path of the literal — the frame's plan fact (the implement literal's
85
- * required `--plan`), the `<plan>` placeholder when the fact is absent (the bare
86
- * fallback face — the mirror of the crash-resume's `<plan>` seed). */
105
+ * required `--plan`), normalized to the repoRoot-relative shape (D47); the
106
+ * `<plan>` placeholder when the fact is absent (the bare fallback face — the
107
+ * mirror of the crash-resume's `<plan>` seed). */
87
108
  #planOf(target?: RouteTarget | null): string {
88
- return target?.plan ?? "<plan>";
109
+ return target?.plan === undefined ? "<plan>" : this.#rel(target.plan);
89
110
  }
90
111
 
91
112
  /** The review hop's literal — `review --type <wave|spec|plan|branch> <type-arg>`
@@ -101,10 +122,10 @@ export class RouteRenderer {
101
122
  return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${target!.id} ${this.#flag("plan")} ${this.#planOf(target)}`;
102
123
  }
103
124
  if (type === "spec") {
104
- return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${target!.id}`;
125
+ return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${this.#rel(target!.id)}`;
105
126
  }
106
127
  if (type === "plan") {
107
- return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${target!.id}`;
128
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(target!.id)}`;
108
129
  }
109
130
  if (type === "branch") {
110
131
  // The branch re-review literal carries only the workspace-identity `--plan` —
@@ -115,29 +136,33 @@ export class RouteRenderer {
115
136
  return verb;
116
137
  }
117
138
 
118
- /** The one-way fix hop's literal — `fix --type <type> <type-arg> --findings <path>
119
- * <readback>` (the readback suffix the declared constant, rendered by reference). */
139
+ /** The one-way fix hop's literal — `fix --type <type> <type-arg> --reviews <path>
140
+ * <readback>` (the readback suffix the declared constant, rendered by reference).
141
+ * Every embedded path value (the doc-id for the spec/plan faces · `--reviews`)
142
+ * is normalized to the repoRoot-relative shape (D47); the wave face's `<type-arg>`
143
+ * is a task key, not a path — passed through as-is. */
120
144
  #fixText(route: Extract<Route, { kind: "fix" }>, target?: RouteTarget | null): string {
121
- if (route.findings === undefined) return this.#words.routeWord("fix");
145
+ if (route.reviews === undefined) return this.#words.routeWord("fix");
122
146
  const verb = this.#words.routeWord("fix");
123
147
  const type = target?.type ?? null;
124
148
  const id = target?.id ?? "";
149
+ const reviews = this.#rel(route.reviews);
125
150
  if (type === "wave") {
126
- return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
151
+ return `${verb} ${this.#flag("type")} wave ${this.#flag("tasks")} ${id} ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
127
152
  }
128
153
  if (type === "spec") {
129
- return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${id} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
154
+ return `${verb} ${this.#flag("type")} spec ${this.#flag("spec")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
130
155
  }
131
156
  if (type === "plan") {
132
- return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${id} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
157
+ return `${verb} ${this.#flag("type")} plan ${this.#flag("plan")} ${this.#rel(id)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
133
158
  }
134
159
  if (type === "branch") {
135
160
  // The branch fix literal carries the workspace-identity `--plan` (isomorphic
136
161
  // with the wave fix branch — a plan-less target resolves to the empty
137
162
  // ref.short() directory, the workspace double identity).
138
- return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
163
+ return `${verb} ${this.#flag("type")} branch ${this.#flag("plan")} ${this.#planOf(target)} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
139
164
  }
140
- return `${verb} ${this.#flag("findings")} ${route.findings} ${FIX_READBACK_SUFFIX}`;
165
+ return `${verb} ${this.#flag("reviews")} ${reviews} ${FIX_READBACK_SUFFIX}`;
141
166
  }
142
167
 
143
168
  /** The face-to-face handoff render — the pipeline entry: a `ref` resolves