@oscaner-skills/cdd-engine 3.0.0 → 3.1.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.
- package/{src-next/bin.ts → dist/bin.js} +18 -21
- package/dist/contract/declare.js +998 -0
- package/dist/contract/doc.js +565 -0
- package/dist/contract/frontmatter.js +209 -0
- package/dist/contract/home-extractors.js +379 -0
- package/dist/contract/invariants.js +1030 -0
- package/dist/contract/judge.js +109 -0
- package/dist/contract/lint.js +206 -0
- package/dist/contract/project.js +371 -0
- package/dist/contract/skill-anatomy.js +156 -0
- package/dist/contract/translate.js +85 -0
- package/dist/face/artifacts.js +189 -0
- package/dist/face/board-view.js +522 -0
- package/dist/face/capsule.js +149 -0
- package/dist/face/cli.js +893 -0
- package/dist/face/declare.js +241 -0
- package/dist/face/gate.js +158 -0
- package/dist/face/graph-view.js +66 -0
- package/dist/face/host.js +211 -0
- package/dist/face/lifecycle.js +702 -0
- package/dist/face/preview.js +136 -0
- package/dist/face/projection.js +259 -0
- package/dist/face/route-render.js +162 -0
- package/dist/face/termination.js +504 -0
- package/dist/face/words.js +258 -0
- package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
- package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
- package/dist/infra/git.js +37 -0
- package/dist/infra/process.js +22 -0
- package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
- package/dist/infra/runtime.js +85 -0
- package/dist/infra/workspace.js +276 -0
- package/dist/render/brief.js +82 -0
- package/dist/render/issue-body.js +129 -0
- package/dist/render/skeleton.js +434 -0
- package/dist/render/templates.js +520 -0
- package/dist/session/faces.js +38 -0
- package/dist/session/graph.js +309 -0
- package/dist/session/handoff-schema.js +295 -0
- package/dist/session/ledger.js +762 -0
- package/dist/session/next.js +211 -0
- package/dist/session/preflight.js +194 -0
- package/dist/session/round-naming.js +73 -0
- package/dist/session/run.js +453 -0
- package/dist/session/state.js +8 -0
- package/dist/session/wave.js +92 -0
- package/package.json +5 -5
- package/src-next/__tests__/bin.test.ts +0 -128
- package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
- package/src-next/__tests__/floor.guard.test.ts +0 -69
- package/src-next/__tests__/issue-body.guard.test.ts +0 -66
- package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
- package/src-next/__tests__/smoke.integration.test.ts +0 -185
- package/src-next/__tests__/support/strip-comments.ts +0 -99
- package/src-next/__tests__/zero-dep.test.ts +0 -94
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
- package/src-next/contract/__tests__/declare.test.ts +0 -481
- package/src-next/contract/__tests__/doc.test.ts +0 -527
- package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
- package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
- package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
- package/src-next/contract/__tests__/judge.test.ts +0 -1111
- package/src-next/contract/__tests__/lint.test.ts +0 -324
- package/src-next/contract/__tests__/project.test.ts +0 -460
- package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
- package/src-next/contract/__tests__/translate.test.ts +0 -96
- package/src-next/contract/declare.ts +0 -1071
- package/src-next/contract/doc.ts +0 -816
- package/src-next/contract/frontmatter.ts +0 -233
- package/src-next/contract/home-extractors.ts +0 -397
- package/src-next/contract/invariants.ts +0 -1413
- package/src-next/contract/judge.ts +0 -151
- package/src-next/contract/lint.ts +0 -239
- package/src-next/contract/project.ts +0 -656
- package/src-next/contract/skill-anatomy.ts +0 -301
- package/src-next/contract/translate.ts +0 -113
- package/src-next/face/__tests__/board-view.test.ts +0 -1151
- package/src-next/face/__tests__/capsule.test.ts +0 -300
- package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
- package/src-next/face/__tests__/cli.test.ts +0 -4897
- package/src-next/face/__tests__/face.test.ts +0 -289
- package/src-next/face/__tests__/graph-view.test.ts +0 -61
- package/src-next/face/__tests__/host.test.ts +0 -24
- package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
- package/src-next/face/__tests__/negation.ts +0 -6
- package/src-next/face/__tests__/preview.test.ts +0 -374
- package/src-next/face/__tests__/projection.test.ts +0 -303
- package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
- package/src-next/face/__tests__/termination.test.ts +0 -650
- package/src-next/face/__tests__/words.guard.test.ts +0 -93
- package/src-next/face/artifacts.ts +0 -248
- package/src-next/face/board-view.ts +0 -652
- package/src-next/face/capsule.ts +0 -163
- package/src-next/face/cli.ts +0 -1028
- package/src-next/face/declare.ts +0 -323
- package/src-next/face/gate.ts +0 -171
- package/src-next/face/graph-view.ts +0 -74
- package/src-next/face/host.ts +0 -302
- package/src-next/face/lifecycle.ts +0 -725
- package/src-next/face/preview.ts +0 -151
- package/src-next/face/projection.ts +0 -285
- package/src-next/face/route-render.ts +0 -185
- package/src-next/face/termination.ts +0 -573
- package/src-next/face/words.ts +0 -314
- package/src-next/infra/__tests__/infra.test.ts +0 -333
- package/src-next/infra/__tests__/root.test.ts +0 -56
- package/src-next/infra/git.ts +0 -39
- package/src-next/infra/process.ts +0 -34
- package/src-next/infra/runtime.ts +0 -132
- package/src-next/infra/workspace.ts +0 -322
- package/src-next/render/__tests__/render.test.ts +0 -550
- package/src-next/render/__tests__/skeleton.test.ts +0 -684
- package/src-next/render/brief.ts +0 -121
- package/src-next/render/issue-body.ts +0 -162
- package/src-next/render/skeleton.ts +0 -502
- package/src-next/render/templates.ts +0 -645
- package/src-next/session/__tests__/graph.test.ts +0 -277
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
- package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
- package/src-next/session/__tests__/ledger.test.ts +0 -745
- package/src-next/session/__tests__/next.test.ts +0 -460
- package/src-next/session/__tests__/preflight.test.ts +0 -545
- package/src-next/session/__tests__/round-naming.test.ts +0 -142
- package/src-next/session/__tests__/run.test.ts +0 -1026
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
- package/src-next/session/__tests__/wave.test.ts +0 -476
- package/src-next/session/faces.ts +0 -110
- package/src-next/session/graph.ts +0 -411
- package/src-next/session/handoff-schema.ts +0 -373
- package/src-next/session/ledger.ts +0 -1076
- package/src-next/session/next.ts +0 -293
- package/src-next/session/preflight.ts +0 -271
- package/src-next/session/round-naming.ts +0 -84
- package/src-next/session/run.ts +0 -610
- package/src-next/session/state.ts +0 -30
- package/src-next/session/wave.ts +0 -139
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/infra/workspace.ts
|
|
2
|
+
// T12 — the workspace data plane: the WorkspaceRoot + Workspace pair owns every
|
|
3
|
+
// on-disk workspace concern of the new tree.
|
|
4
|
+
// WorkspaceRoot — the repo-scoped workspace base (`<repoRoot>/<workspaceRoot>`,
|
|
5
|
+
// one dispatch family's home; the segment single-sources the engine config's
|
|
6
|
+
// handoffNamespace.workspaceRoot and is never a hard-coded literal).
|
|
7
|
+
// Workspace — one dispatch workspace (`<base>/<slug>/`): ensure() mkdirs the
|
|
8
|
+
// slug dir, readJson/writeJson are the JSON read/write pair (mkdir before
|
|
9
|
+
// write; readJson is tri-state — ok / missing / malformed), readJsonLenient is
|
|
10
|
+
// the sub-agent-authored draft face (jsonc-parser + trailing-comma/comment
|
|
11
|
+
// tolerance — a child-LLM slip never voids a round, a real break still reports
|
|
12
|
+
// malformed; D39), resolve() is the
|
|
13
|
+
// child-path single fact, slugFromDoc is the doc-file → slug derivation
|
|
14
|
+
// (`-design`/`-plan` suffix strip), docsOfSlug is the slug → doc-tree reverse
|
|
15
|
+
// derivation (the board's file-system-only truth, phase-suffix parse included).
|
|
16
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
17
|
+
import path from "node:path";
|
|
18
|
+
import { parse } from "jsonc-parser";
|
|
19
|
+
import { RepoRoot } from "./root.js";
|
|
20
|
+
import { ENGINE_RUNTIME } from "./runtime.js";
|
|
21
|
+
/** The slug phase-suffix syntax — the trailing `-p<major>(.<minor>)*` segment
|
|
22
|
+
* (spec §3.2 ⑬). This is the ONE source of the phase-suffix grammar: both the
|
|
23
|
+
* suffix parse (`Workspace.phaseSuffixOf`, the `-p…$` form) and the board's
|
|
24
|
+
* suffix-only match (`BoardView.scanPhases`, the `^p…$` form) compose their
|
|
25
|
+
* patterns from this fragment. (Distinct from the doc-contract design-unit value
|
|
26
|
+
* syntax `P\d+(\.\d+)*-design` — uppercase + `-design` tail — which is another
|
|
27
|
+
* fact, never merged here.) */
|
|
28
|
+
export const PHASE_SUFFIX_CORE = "p\\d+(?:\\.\\d+)*";
|
|
29
|
+
/** The phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment captured
|
|
30
|
+
* as the named `suffix` group (composed from PHASE_SUFFIX_CORE: the ONE grammar). */
|
|
31
|
+
const PHASE_SUFFIX_TAIL = new RegExp(`(?<program>.+?)(?<suffix>-${PHASE_SUFFIX_CORE})$`);
|
|
32
|
+
/** The suffix-only match — a bare `<major>(.<minor>)*` phase path (composed from
|
|
33
|
+
* the SAME PHASE_SUFFIX_CORE; the board's scan uses this form). */
|
|
34
|
+
export const PHASE_SUFFIX_BARE = new RegExp(`^${PHASE_SUFFIX_CORE}$`);
|
|
35
|
+
/** The persisted path-field keys — the JSON fields whose value is a PATH (the
|
|
36
|
+
* progress.json `reviewedRevision.doc` / `.plan` layers · the base.json `plan`
|
|
37
|
+
* field). The read-time normalization (P9 T4 §2.11) relativizes exactly these
|
|
38
|
+
* values, never an arbitrary string (a carrier's `notes` prose is never treated as
|
|
39
|
+
* a path). */
|
|
40
|
+
const PERSISTED_PATH_KEYS = new Set(["doc", "plan"]);
|
|
41
|
+
/** The repo-scoped workspace base — `<repoRoot>/<workspaceRoot>`. */
|
|
42
|
+
export class WorkspaceRoot {
|
|
43
|
+
repoRoot;
|
|
44
|
+
/** The repo-basis value object (T1 `RepoRoot`) — constructed ONCE here, at the
|
|
45
|
+
* workspace's own boundary, and shared by every reader that needs the basis
|
|
46
|
+
* (the ledger's write/read normalization, the CLI's capsule/graph render, the
|
|
47
|
+
* board's doc cells): the single repo-basis fact is threaded as the value object,
|
|
48
|
+
* never re-wrapped per call (branch-review-1 F2 — Data Clumps / Primitive
|
|
49
|
+
* Obsession: one basis, one form). */
|
|
50
|
+
basis;
|
|
51
|
+
path;
|
|
52
|
+
constructor(repoRoot, workspaceRoot) {
|
|
53
|
+
this.repoRoot = repoRoot;
|
|
54
|
+
this.basis = new RepoRoot(repoRoot);
|
|
55
|
+
this.path = path.join(repoRoot, workspaceRoot);
|
|
56
|
+
}
|
|
57
|
+
/** Idempotently create the workspace root + self-publish the namespace root's
|
|
58
|
+
* `.gitignore` (a single `*` — everything under `.kairos/` is engine-owned, so
|
|
59
|
+
* the git face ignores the whole namespace wholesale, the `cdd/` workspace and
|
|
60
|
+
* any future sibling alike). The tree-clean gate then reads git's own judgment
|
|
61
|
+
* — `isClean` with zero engine-side exclusion — a consumer repo with no `.kairos`
|
|
62
|
+
* entry in its own `.gitignore` still stays clean across dispatches, because
|
|
63
|
+
* the workspace publishes its keep-out marker at ensure time, before the gate
|
|
64
|
+
* ever reads the tree (the F1 fix: the engine's run artifacts are engine-owned,
|
|
65
|
+
* never "uncommitted user work"). The ignore affects only untracked files — a
|
|
66
|
+
* user who git-tracks the workspace keeps seeing its changes on the gate. */
|
|
67
|
+
ensure() {
|
|
68
|
+
mkdirSync(this.path, { recursive: true });
|
|
69
|
+
// The namespace root — the workspace root's parent (`.kairos/cdd` → `.kairos`):
|
|
70
|
+
// the keep-out marker sits at the namespace's top, never per-workspace (the
|
|
71
|
+
// consumer-facing convention: ignore the whole `.kairos` namespace at once).
|
|
72
|
+
const namespaceRoot = path.dirname(this.path);
|
|
73
|
+
mkdirSync(namespaceRoot, { recursive: true });
|
|
74
|
+
const ignore = path.join(namespaceRoot, ".gitignore");
|
|
75
|
+
if (!existsSync(ignore))
|
|
76
|
+
writeFileSync(ignore, "*\n", "utf8");
|
|
77
|
+
return this;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
/** One dispatch workspace — `<base>/<slug>/`. */
|
|
81
|
+
export class Workspace {
|
|
82
|
+
root;
|
|
83
|
+
slug;
|
|
84
|
+
path;
|
|
85
|
+
constructor(root, slug) {
|
|
86
|
+
this.root = root;
|
|
87
|
+
this.slug = slug;
|
|
88
|
+
this.path = path.join(root.path, slug);
|
|
89
|
+
}
|
|
90
|
+
/** The doc-file → slug derivation: strip `.md`, then one trailing `-design` or
|
|
91
|
+
* `-plan` suffix (anchored, mutually exclusive — spec and plan converge). */
|
|
92
|
+
static slugFromDoc(doc) {
|
|
93
|
+
const base = path.basename(doc).replace(/\.md$/, "");
|
|
94
|
+
return base.replace(/-(?:design|plan)$/, "");
|
|
95
|
+
}
|
|
96
|
+
/** The slug's phase-suffix parse — the trailing `-p<major>(.<minor>)*` segment
|
|
97
|
+
* (null when the slug is a program slug, i.e. carries no phase suffix). The
|
|
98
|
+
* grammar is PHASE_SUFFIX_TAIL, composed from the shared PHASE_SUFFIX_CORE. */
|
|
99
|
+
static phaseSuffixOf(slug) {
|
|
100
|
+
const match = PHASE_SUFFIX_TAIL.exec(slug);
|
|
101
|
+
return match?.groups?.suffix ?? null;
|
|
102
|
+
}
|
|
103
|
+
/** The slug → doc-tree reverse derivation: from a program or phase slug, derive
|
|
104
|
+
* the artifact paths the doc tree should carry, judged by `existsSync` (the
|
|
105
|
+
* file system is the only truth — an absent file is null, never synthesized).
|
|
106
|
+
* A phase slug's overall anchors at the nearest existing `<ancestor>-overall.md`
|
|
107
|
+
* walking up the dotted phase path (`-p7.1` → `-p7` → program root) — no
|
|
108
|
+
* overall-declared table is parsed (the Phase inventory is stale-prone). */
|
|
109
|
+
static docsOfSlug(slug, repoRoot) {
|
|
110
|
+
const specs = path.join(repoRoot, ENGINE_RUNTIME.docRoots.specs);
|
|
111
|
+
const plans = path.join(repoRoot, ENGINE_RUNTIME.docRoots.plans);
|
|
112
|
+
const suffix = Workspace.phaseSuffixOf(slug);
|
|
113
|
+
if (suffix === null) {
|
|
114
|
+
const overall = path.join(specs, `${slug}-overall.md`);
|
|
115
|
+
return {
|
|
116
|
+
overall: existsSync(overall) ? overall : null,
|
|
117
|
+
spec: null,
|
|
118
|
+
plan: null,
|
|
119
|
+
phaseSuffix: null,
|
|
120
|
+
};
|
|
121
|
+
}
|
|
122
|
+
const overall = Workspace.#nearestOverall(specs, slug, suffix);
|
|
123
|
+
const spec = path.join(specs, `${slug}-design.md`);
|
|
124
|
+
const plan = path.join(plans, `${slug}.md`);
|
|
125
|
+
return {
|
|
126
|
+
overall,
|
|
127
|
+
spec: existsSync(spec) ? spec : null,
|
|
128
|
+
plan: existsSync(plan) ? plan : null,
|
|
129
|
+
phaseSuffix: suffix,
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
/** The nearest existing overall anchor walking up the dotted phase path: for a
|
|
133
|
+
* deep suffix (`-p7.1`) the candidates are `<program>-p7`, then the program
|
|
134
|
+
* root; for a single-segment suffix the program root only. Null when no
|
|
135
|
+
* candidate's overall file exists — nothing synthesized. */
|
|
136
|
+
static #nearestOverall(specs, slug, suffix) {
|
|
137
|
+
const stem = slug.slice(0, slug.length - suffix.length);
|
|
138
|
+
const segments = suffix.slice(2).split(".");
|
|
139
|
+
for (let keep = segments.length - 1; keep >= 0; keep--) {
|
|
140
|
+
const candidate = keep === 0
|
|
141
|
+
? path.join(specs, `${stem}-overall.md`)
|
|
142
|
+
: path.join(specs, `${stem}-p${segments.slice(0, keep).join(".")}-overall.md`);
|
|
143
|
+
if (existsSync(candidate))
|
|
144
|
+
return candidate;
|
|
145
|
+
}
|
|
146
|
+
return null;
|
|
147
|
+
}
|
|
148
|
+
/** Idempotently create the workspace directory. */
|
|
149
|
+
ensure() {
|
|
150
|
+
this.root.ensure();
|
|
151
|
+
mkdirSync(this.path, { recursive: true });
|
|
152
|
+
return this;
|
|
153
|
+
}
|
|
154
|
+
/** A child path inside this workspace. */
|
|
155
|
+
resolve(name) {
|
|
156
|
+
return path.join(this.path, name);
|
|
157
|
+
}
|
|
158
|
+
/** Read a JSON child — the tri-state face: `{kind:"ok",value}` on a present,
|
|
159
|
+
* parseable file; `{kind:"missing"}` when the path does not exist; `{kind:
|
|
160
|
+
* "malformed"}` when the file is present but its bytes are unparseable (a bad
|
|
161
|
+
* JSON draft) OR unreadable for any other I/O reason (a present-but-broken file is
|
|
162
|
+
* never silently "missing" — the reconstruct reports the true cause). The STRICT
|
|
163
|
+
* read — engine-authored files (`JSON.stringify` output) are always legal JSON, so
|
|
164
|
+
* they never need leniency; a lenient read of a strict file would only mask a real
|
|
165
|
+
* engine bug. */
|
|
166
|
+
readJson(name) {
|
|
167
|
+
const target = this.resolve(name);
|
|
168
|
+
const text = this.#readText(target);
|
|
169
|
+
if (text.kind !== "ok")
|
|
170
|
+
return text;
|
|
171
|
+
try {
|
|
172
|
+
// The read-time path backstop (P9 T4 §2.11): a path field persisted by an
|
|
173
|
+
// older build (an absolute form) is relativized on read, so an un-migrated
|
|
174
|
+
// file still yields the ONE canonical shape downstream. A no-op on
|
|
175
|
+
// already-relative values (relativize is idempotent).
|
|
176
|
+
return { kind: "ok", value: this.#normalizePaths(JSON.parse(text.value)) };
|
|
177
|
+
}
|
|
178
|
+
catch {
|
|
179
|
+
return { kind: "malformed" };
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
/** Read a JSON child LENIENTLY — the sub-agent-authored handoff-draft face (D39).
|
|
183
|
+
* A child LLM writes handoff carriers (`tasks-*-implement.json` …) from prose, and
|
|
184
|
+
* a trailing comma or a stray comment is a routine model slip, not a real defect —
|
|
185
|
+
* the strict `readJson` vetoes the WHOLE implement+review round on one such comma
|
|
186
|
+
* (the W3 {5,11} block: a `notes` array trailing comma, the draft otherwise whole).
|
|
187
|
+
* jsonc-parser with `allowTrailingComma` tolerates ONLY the lenient-dialect surface
|
|
188
|
+
* (trailing commas · comments) and still reports a real break (a missing brace, …)
|
|
189
|
+
* — so a corrupt draft stays fail-loud while a cosmetic slip no longer voids a round.
|
|
190
|
+
* The leniency is scoped to THIS face alone: engine-authored files (including the
|
|
191
|
+
* test-evidence sibling, which the engine/child writes as machine JSON) keep the
|
|
192
|
+
* strict `readJson` — the JSON contract is never widened for engine bytes. */
|
|
193
|
+
readJsonLenient(name) {
|
|
194
|
+
const target = this.resolve(name);
|
|
195
|
+
const text = this.#readText(target);
|
|
196
|
+
if (text.kind !== "ok")
|
|
197
|
+
return text;
|
|
198
|
+
const errors = [];
|
|
199
|
+
const value = parse(text.value, errors, {
|
|
200
|
+
allowTrailingComma: true,
|
|
201
|
+
disallowComments: false,
|
|
202
|
+
});
|
|
203
|
+
// A real break carries the parser's precise error codes (offset/length/error)
|
|
204
|
+
// for diagnosis; a tolerated slip parses clean (errors empty).
|
|
205
|
+
return errors.length === 0 ? { kind: "ok", value } : { kind: "malformed", errors };
|
|
206
|
+
}
|
|
207
|
+
/** Read a child's text — the shared tri-state file leg of both JSON reads: a
|
|
208
|
+
* genuinely absent path is `missing`; a present-but-unreadable one (EACCES, EISDIR …)
|
|
209
|
+
* is `malformed` — never silently "missing" (D27 · single-fact honesty). */
|
|
210
|
+
#readText(target) {
|
|
211
|
+
let text;
|
|
212
|
+
try {
|
|
213
|
+
text = readFileSync(target, "utf8");
|
|
214
|
+
}
|
|
215
|
+
catch (raw) {
|
|
216
|
+
const code = raw.code;
|
|
217
|
+
return code === "ENOENT" ? { kind: "missing" } : { kind: "malformed" };
|
|
218
|
+
}
|
|
219
|
+
return { kind: "ok", value: text };
|
|
220
|
+
}
|
|
221
|
+
/** Write a JSON child — mkdir before write. The declared path fields (`doc` /
|
|
222
|
+
* `plan`) are normalized to the canonical repoRoot-relative shape on write (P9
|
|
223
|
+
* T4 §2.7), so every engine-persisted path field lands relative — the read-time
|
|
224
|
+
* backstop then only covers legacy bytes (migration handles history, the read
|
|
225
|
+
* normalizes any straggler). The written bytes carry exactly one trailing `\n`
|
|
226
|
+
* (the repo's EOF rule), so an engine-written file is byte-canonical and the
|
|
227
|
+
* one-time migration leaves it byte-identical (zero churn). */
|
|
228
|
+
writeJson(name, value) {
|
|
229
|
+
this.ensure();
|
|
230
|
+
const normalized = this.#normalizePaths(value);
|
|
231
|
+
writeFileSync(this.resolve(name), `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
|
|
232
|
+
}
|
|
233
|
+
/** Write a text child — mkdir before write (the text twin of `writeJson`; the
|
|
234
|
+
* engine-rendered brief is the one text artifact the engine authors itself).
|
|
235
|
+
* Returns the resolved path. */
|
|
236
|
+
writeText(name, text) {
|
|
237
|
+
this.ensure();
|
|
238
|
+
const target = this.resolve(name);
|
|
239
|
+
writeFileSync(target, text, "utf8");
|
|
240
|
+
return target;
|
|
241
|
+
}
|
|
242
|
+
/** The workspace's repo-basis value object — the ONE conversion exit the
|
|
243
|
+
* read-time path backstop normalizes through. The basis is the root's OWN
|
|
244
|
+
* value object (`WorkspaceRoot.basis`, built once at the root's boundary) —
|
|
245
|
+
* never re-wrapped here (branch-review-1 F2: one basis, one form). */
|
|
246
|
+
#repoBasis() {
|
|
247
|
+
return this.root.basis;
|
|
248
|
+
}
|
|
249
|
+
/** The read-time path backstop (P9 T4 §2.11) — deep-normalize every DECLARED
|
|
250
|
+
* path field (`doc` / `plan` — the `reviewedRevision` two-layer layers + the
|
|
251
|
+
* base artifact's `plan`) to the canonical repoRoot-relative shape, so an
|
|
252
|
+
* un-migrated file (a legacy absolute value) still reads as the ONE shape.
|
|
253
|
+
* Only the declared path keys are touched (never arbitrary prose); the walk is
|
|
254
|
+
* a pure clone (arrays + plain objects), recursing into `waves[]` rows and the
|
|
255
|
+
* reviewed-revision records alike. Relativizing an already-relative value is a
|
|
256
|
+
* no-op (idempotent). */
|
|
257
|
+
#normalizePaths(value) {
|
|
258
|
+
const root = this.#repoBasis();
|
|
259
|
+
const walk = (node) => {
|
|
260
|
+
if (Array.isArray(node))
|
|
261
|
+
return node.map(walk);
|
|
262
|
+
if (node !== null && typeof node === "object") {
|
|
263
|
+
const out = {};
|
|
264
|
+
for (const [key, child] of Object.entries(node)) {
|
|
265
|
+
out[key] =
|
|
266
|
+
PERSISTED_PATH_KEYS.has(key) && typeof child === "string"
|
|
267
|
+
? root.relativize(child)
|
|
268
|
+
: walk(child);
|
|
269
|
+
}
|
|
270
|
+
return out;
|
|
271
|
+
}
|
|
272
|
+
return node;
|
|
273
|
+
};
|
|
274
|
+
return walk(value);
|
|
275
|
+
}
|
|
276
|
+
}
|
|
@@ -0,0 +1,82 @@
|
|
|
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
|
+
import { PlanDocType } from "../contract/doc.js";
|
|
12
|
+
/**
|
|
13
|
+
* The brief single renderer — pure data + content (no direct file system writes;
|
|
14
|
+
* the caller/CLI writes the rendered content into the workspace).
|
|
15
|
+
*/
|
|
16
|
+
export class BriefRenderer {
|
|
17
|
+
#parser;
|
|
18
|
+
constructor(parser = new PlanDocType("plan")) {
|
|
19
|
+
this.#parser = parser;
|
|
20
|
+
}
|
|
21
|
+
/** The task-heading slices of the plan parse face (the render's parse-face consumption). */
|
|
22
|
+
taskHeadingPattern() {
|
|
23
|
+
return this.#parser.slices.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
|
|
24
|
+
}
|
|
25
|
+
/** Extract the requested task blocks from a plan's content — the brief data. */
|
|
26
|
+
extract(planContent, tasks) {
|
|
27
|
+
const parsed = this.#parser.parse(planContent.split("\n"));
|
|
28
|
+
const byId = new Map(parsed.taskBlocks.map((block) => [block.id, block]));
|
|
29
|
+
const missing = [];
|
|
30
|
+
const data = [];
|
|
31
|
+
for (const id of new Set(tasks)) {
|
|
32
|
+
const block = byId.get(id);
|
|
33
|
+
if (block === undefined) {
|
|
34
|
+
missing.push(id);
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
const steps = block.steps;
|
|
38
|
+
const missingCheckables = steps
|
|
39
|
+
.filter((step) => step.checkable === null)
|
|
40
|
+
.map((step) => step.action);
|
|
41
|
+
data.push({
|
|
42
|
+
id: block.id,
|
|
43
|
+
heading: block.heading,
|
|
44
|
+
fields: block.fields,
|
|
45
|
+
steps,
|
|
46
|
+
checkableComplete: missingCheckables.length === 0,
|
|
47
|
+
missingCheckables,
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
return { data, missing };
|
|
51
|
+
}
|
|
52
|
+
/** Render the brief content — the requested task sections + the plan's
|
|
53
|
+
* `## Constraints` section (the complete plan mirror). Any requested task without
|
|
54
|
+
* a heading blocks the whole render (out-of-bounds). */
|
|
55
|
+
render(planContent, tasks) {
|
|
56
|
+
const { data, missing } = this.extract(planContent, tasks);
|
|
57
|
+
if (missing.length > 0) {
|
|
58
|
+
throw new Error(`task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`);
|
|
59
|
+
}
|
|
60
|
+
const lines = planContent.split("\n");
|
|
61
|
+
const sections = data.map((task) => this.#rawSection(lines, (line) => line.startsWith(`### Task ${task.id}:`)));
|
|
62
|
+
const constraints = this.#rawSection(lines, (line) => line.trimEnd() === "## Constraints");
|
|
63
|
+
const body = constraints === "" ? sections.join("\n\n") : `${sections.join("\n\n")}\n\n${constraints}`;
|
|
64
|
+
return `${body}\n`;
|
|
65
|
+
}
|
|
66
|
+
/** The shared heading slice — from the first line a matcher accepts to the next
|
|
67
|
+
* heading line ("" when nothing matches). Both the `### Task N:` sections and the
|
|
68
|
+
* `## Constraints` mirror render through this one shape. */
|
|
69
|
+
#rawSection(lines, match) {
|
|
70
|
+
const start = lines.findIndex(match);
|
|
71
|
+
if (start === -1)
|
|
72
|
+
return "";
|
|
73
|
+
const out = [];
|
|
74
|
+
for (let i = start; i < lines.length; i++) {
|
|
75
|
+
const line = lines[i];
|
|
76
|
+
if (i > start && /^#/.test(line))
|
|
77
|
+
break;
|
|
78
|
+
out.push(line);
|
|
79
|
+
}
|
|
80
|
+
return out.join("\n").replace(/\s+$/, "");
|
|
81
|
+
}
|
|
82
|
+
}
|
|
@@ -0,0 +1,129 @@
|
|
|
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
|
+
import { ISSUE_TYPES } from "../face/words.js";
|
|
19
|
+
/**
|
|
20
|
+
* The issue-body renderer — the aggregate issue body's steady renderer (the finding
|
|
21
|
+
* type/lang vocabularies and the segment labels live on the declared data — the type
|
|
22
|
+
* set on the renderer, the locale keys + label rows on the word table, never a second
|
|
23
|
+
* source): Session block → per-finding four-segment blocks with attribution → Dedup
|
|
24
|
+
* (open hits) → Related (closed hits + program). Pure deterministic text.
|
|
25
|
+
*/
|
|
26
|
+
export class IssueBodyRenderer {
|
|
27
|
+
/** The finding-type vocabulary (the canonical type set) — the word table's
|
|
28
|
+
* `ISSUE_TYPES` (derived from the issue-label rows, the ONE type source), never a
|
|
29
|
+
* second hand-written list. */
|
|
30
|
+
types = ISSUE_TYPES;
|
|
31
|
+
/** The four text-segment keys, in the render order. */
|
|
32
|
+
#segments = ["context", "problem", "impact", "suggestedFix"];
|
|
33
|
+
/** The word table's locale face — the langs projection + the label rows. */
|
|
34
|
+
#words;
|
|
35
|
+
/** The translation layer — the label rows localize through it (locale-normalized render). */
|
|
36
|
+
#translator;
|
|
37
|
+
constructor(words, translator) {
|
|
38
|
+
this.#words = words;
|
|
39
|
+
this.#translator = translator;
|
|
40
|
+
}
|
|
41
|
+
/** The rendered language vocabulary — the word table's locale key projection (the
|
|
42
|
+
* langs derivation: a locale-key change in the word table re-projects this face). */
|
|
43
|
+
langs() {
|
|
44
|
+
return this.#words.localeKeys();
|
|
45
|
+
}
|
|
46
|
+
/** The canonical `meta` bullet lines of one finding (the two attribution rows). */
|
|
47
|
+
#metaOf(meta) {
|
|
48
|
+
return `- Skill: ${meta.skill}\n- Step: ${meta.step}`;
|
|
49
|
+
}
|
|
50
|
+
/** One finding's segment label — the word table's label row localized to the
|
|
51
|
+
* finding's lang (localize(canonical, locale); an unknown row — impossible under
|
|
52
|
+
* the completeness pin — falls back to the canonical English face). */
|
|
53
|
+
#labelOf(finding, segment) {
|
|
54
|
+
const row = this.#words.localeRow(`${finding.type}.${segment}`);
|
|
55
|
+
if (row === null)
|
|
56
|
+
return segment;
|
|
57
|
+
return this.#translator.localize(row.en, finding.lang) ?? row.en;
|
|
58
|
+
}
|
|
59
|
+
/** One finding's block — the four labeled segments plus the attribution. */
|
|
60
|
+
#findingOf(finding) {
|
|
61
|
+
const parts = this.#segments.map((segment) => `${this.#labelOf(finding, segment)}\n\n${String(finding[segment])}`);
|
|
62
|
+
return [...parts, this.#metaOf(finding.meta)].join("\n\n");
|
|
63
|
+
}
|
|
64
|
+
/** Render the aggregate issue body — deterministic: the Session block (harness
|
|
65
|
+
* line), the findings in input order, then the Dedup / Related tails. */
|
|
66
|
+
renderBody(input) {
|
|
67
|
+
const parts = [`# CDD aggregate issue\n\n- Harness: ${input.harness}`];
|
|
68
|
+
for (const finding of input.findings)
|
|
69
|
+
parts.push(this.#findingOf(finding));
|
|
70
|
+
const open = input.related?.open ?? [];
|
|
71
|
+
if (open.length > 0) {
|
|
72
|
+
parts.push(`## Dedup\n${open.map((hit) => `- Dedup → #${hit.issue} (open):${hit.component} · ${hit.reason}`).join("\n")}`);
|
|
73
|
+
}
|
|
74
|
+
const closed = input.related?.closed ?? [];
|
|
75
|
+
const program = input.related?.program;
|
|
76
|
+
if (closed.length > 0 || program !== undefined) {
|
|
77
|
+
const lines = [];
|
|
78
|
+
for (const hit of closed)
|
|
79
|
+
lines.push(`- Regression / follow-up of #${hit.issue} (closed)`);
|
|
80
|
+
if (program !== undefined)
|
|
81
|
+
lines.push(`- Program: #${program.issue}`);
|
|
82
|
+
parts.push(`## Related\n${lines.join("\n")}`);
|
|
83
|
+
}
|
|
84
|
+
return parts.join("\n\n");
|
|
85
|
+
}
|
|
86
|
+
/** Input-shape validation — the E-3 early-report contract (field paths, empty =
|
|
87
|
+
* pass). The canonical type set and the word-table locale projection are the single
|
|
88
|
+
* declared vocabularies. */
|
|
89
|
+
validateInput(raw) {
|
|
90
|
+
const errors = [];
|
|
91
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw))
|
|
92
|
+
return ["input: expected an object with harness / findings / related?"];
|
|
93
|
+
const input = raw;
|
|
94
|
+
if (typeof input.harness !== "string" || input.harness.length === 0)
|
|
95
|
+
errors.push("harness: non-empty string required");
|
|
96
|
+
if (!Array.isArray(input.findings) || input.findings.length === 0) {
|
|
97
|
+
errors.push("findings: non-empty array of findings required");
|
|
98
|
+
}
|
|
99
|
+
else {
|
|
100
|
+
input.findings.forEach((rawFinding, i) => {
|
|
101
|
+
const finding = rawFinding;
|
|
102
|
+
const base = `findings[${i}]`;
|
|
103
|
+
if (typeof finding !== "object" || finding === null) {
|
|
104
|
+
errors.push(`${base}: object with type/lang/context/problem/impact/suggestedFix/meta expected`);
|
|
105
|
+
return;
|
|
106
|
+
}
|
|
107
|
+
if (!this.types.includes(String(finding.type)))
|
|
108
|
+
errors.push(`${base}.type: must be one of ${this.types.join(" | ")}`);
|
|
109
|
+
if (!this.langs().includes(String(finding.lang)))
|
|
110
|
+
errors.push(`${base}.lang: must be one of ${this.langs().join(" | ")}`);
|
|
111
|
+
for (const field of this.#segments) {
|
|
112
|
+
if (typeof finding[field] !== "string" || finding[field].length === 0)
|
|
113
|
+
errors.push(`${base}.${field}: non-empty string required`);
|
|
114
|
+
}
|
|
115
|
+
const meta = finding.meta;
|
|
116
|
+
if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
|
|
117
|
+
errors.push(`${base}.meta: object with skill / step required`);
|
|
118
|
+
}
|
|
119
|
+
else {
|
|
120
|
+
if (typeof meta.skill !== "string" || meta.skill.length === 0)
|
|
121
|
+
errors.push(`${base}.meta.skill: non-empty string required`);
|
|
122
|
+
if (typeof meta.step !== "string" || meta.step.length === 0)
|
|
123
|
+
errors.push(`${base}.meta.step: non-empty string required`);
|
|
124
|
+
}
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
return errors;
|
|
128
|
+
}
|
|
129
|
+
}
|