@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
@@ -1,128 +0,0 @@
1
- // packages/cdd-engine/src-next/__tests__/bin.test.ts
2
- // T13 — the bin-bootstrap face, black-box: the thin entry's cli-load + exit-code
3
- // plumbing exercised exactly the way the checkable runs it (`node src-next/bin.ts …`).
4
- // Spawns the source entry straight (Node >=22.18 native type stripping — the dev
5
- // face; the test asserts through the steady exit-code table — 0 = OK · 2 = usage —
6
- // not through anything imported in-process: the bin is only ever executed, never
7
- // imported).
8
-
9
- import { spawnSync } from "node:child_process";
10
- import { readFileSync } from "node:fs";
11
- import process from "node:process";
12
- import { fileURLToPath } from "node:url";
13
- import { describe, expect, it } from "vitest";
14
-
15
- const BIN = fileURLToPath(new URL("../bin.ts", import.meta.url));
16
-
17
- /** One spawned bin run — fail-open (a non-zero child rides the code, never a throw;
18
- * the child's streams are piped, never inherited into the reporter). */
19
- const run = (
20
- args: readonly string[],
21
- opts: { cwd?: string; input?: string } = {},
22
- ): { code: number; stdout: string; stderr: string } => {
23
- const result = spawnSync(process.execPath, [BIN, ...args], {
24
- encoding: "utf8",
25
- cwd: opts.cwd ?? process.cwd(),
26
- input: opts.input,
27
- stdio: ["pipe", "pipe", "pipe"],
28
- });
29
- return {
30
- code: result.status ?? (result.error !== undefined ? 1 : 0),
31
- stdout: result.stdout ?? "",
32
- stderr: result.stderr ?? "",
33
- };
34
- };
35
-
36
- describe("the T9 deliberate pin — the NodeEnvGuard + Cli.create entry (the class-face boot)", () => {
37
- it("the entry is the NodeEnvGuard class member + the Cli.create factory — zero module-level functions in bin.ts", () => {
38
- // bin.ts is only ever executed, never imported, so the entry form is pinned
39
- // from its source: the environment pre-flight is a class static judgement and
40
- // the CLI face boots through the Cli.create static factory — a regression to a
41
- // module-level `bootEnvironmentProblem`/`cli` function trips this pin.
42
- const src = readFileSync(BIN, "utf8");
43
- expect(src).not.toMatch(/^(export )?(async )?function /m);
44
- expect(src).toMatch(/class NodeEnvGuard/);
45
- expect(src).toMatch(/NodeEnvGuard\.problem\(\)/);
46
- expect(src).toMatch(/const \{ Cli \} = await import\("\.\/face\/cli\.ts"\)/);
47
- expect(src).toMatch(/Cli\.create\(\)\.runArgv/);
48
- });
49
-
50
- it("the environment guard's message + exit bytes are pinned (the below-floor word face)", () => {
51
- const src = readFileSync(BIN, "utf8");
52
- // The byte message is produced from the NODE_FLOOR row — both the floor and the
53
- // template production are pinned so the below-floor word face cannot drift.
54
- expect(src).toContain("const NODE_FLOOR = { major: 22, minor: 18 } as const;");
55
- expect(src).toMatch(
56
- /cdd requires Node >= \$\{NODE_FLOOR\.major\}\.\$\{NODE_FLOOR\.minor\} \(native type stripping\) — installed: \$\{process\.versions\.node\}/,
57
- );
58
- expect(src).toContain("process.exit(1)");
59
- });
60
- });
61
-
62
- describe("the bin bootstrap — cli load + exit-code plumbing (black-box)", () => {
63
- it("`node src-next/bin.ts schema get plan` prints the derived plan schema + exits 0 (the T13 checkable)", () => {
64
- const result = run(["schema", "get", "plan"]);
65
- expect(result.code).toBe(0);
66
- const parsed = JSON.parse(result.stdout) as {
67
- docType: string;
68
- $schema: string;
69
- properties: Record<string, unknown>;
70
- };
71
- // The derived doc-structure schema — the registration-derived face, never a
72
- // hand-written second schema.
73
- expect(parsed.docType).toBe("plan");
74
- expect(parsed.$schema).toContain("json-schema.org");
75
- expect(parsed.properties).toBeTypeOf("object");
76
- expect(Object.keys(parsed.properties).length).toBeGreaterThan(0);
77
- });
78
-
79
- it("an unknown flag exits 2 with commander's unknown-option byte + the native did-you-mean (the guardArgs semantics ride the bin)", () => {
80
- // the required flags must be satisfied first — commander's missing-required
81
- // check fires before the unknown-option scan, so the typo surfaces only with
82
- // --tasks/--plan present
83
- const result = run(["implement", "--tasks", "2", "--plan", "p.md", "--taks"]);
84
- expect(result.code).toBe(2);
85
- expect(result.stderr).toContain("error: unknown option '--taks'");
86
- expect(result.stderr).toContain("(Did you mean --tasks?)");
87
- });
88
-
89
- it("an unknown command exits 2 with commander's unknown-command byte", () => {
90
- const result = run(["bogus"]);
91
- expect(result.code).toBe(2);
92
- expect(result.stderr).toContain("error: unknown command 'bogus'");
93
- });
94
-
95
- it("a missing required flag exits 2 with the .requiredOption() byte (base get's required --plan)", () => {
96
- const result = run(["base", "get"]);
97
- expect(result.code).toBe(2);
98
- expect(result.stderr).toContain("error: required option '--plan <path>' not specified");
99
- });
100
-
101
- it("`node src-next/bin.ts issue render` renders the aggregate body from stdin + exits 0", () => {
102
- const input = JSON.stringify({
103
- harness: "claude",
104
- findings: [
105
- {
106
- type: "bug",
107
- lang: "en",
108
- context: "c",
109
- problem: "p",
110
- impact: "i",
111
- suggestedFix: "f",
112
- meta: { skill: "tdd", step: "loop" },
113
- },
114
- ],
115
- });
116
- const result = run(["issue", "render"], { input });
117
- expect(result.code).toBe(0);
118
- expect(result.stdout).toContain("# CDD aggregate issue");
119
- expect(result.stdout).toContain("## Context");
120
- expect(result.stdout).toContain("- Skill: tdd");
121
- });
122
-
123
- it("issue render rejects malformed input JSON with exit 1 (the input-value failure surface)", () => {
124
- const result = run(["issue", "render"], { input: "not json" });
125
- expect(result.code).toBe(1);
126
- expect(result.stderr).toContain("invalid input JSON");
127
- });
128
- });
@@ -1,202 +0,0 @@
1
- // packages/cdd-engine/src-next/__tests__/smoke.integration.test.ts
2
- // The engine smoke integration test — the consumer release gate migrated from
3
- // scripts/smoke-cdd.ts (P5 T7): boots the source bin (`node src-next/bin.ts`) over a
4
- // fresh fixture git repo and asserts the status-capsule contract on the dry-run
5
- // chain (`--dry-run implement` + `--dry-run review`) plus the `--help` commander
6
- // face. The engine carries no version assertion — `--expect-version` was withdrawn as
7
- // a no-op (user adjudication 2026-10-12); the `smoke` script (`pnpm -C
8
- // packages/cdd-engine run smoke`) is the release.yml gate's shared anchor.
9
- //
10
- // Zero module-level bare functions — the helpers are `const` (the P5
11
- // zero-`function`-declaration discipline).
12
-
13
- import { execFileSync, spawnSync } from "node:child_process";
14
- import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
15
- import { tmpdir } from "node:os";
16
- import path from "node:path";
17
- import { fileURLToPath } from "node:url";
18
- import { describe, expect, it } from "vitest";
19
-
20
- /** The source bin under test — the engine's own entry (spawned, never imported). */
21
- const BIN = fileURLToPath(new URL("../bin.ts", import.meta.url));
22
-
23
- /** The fixture plan text — the canonical data-shaped task record (the markers the
24
- * plan parser reads; the workspace slug derives `fixture` from the basename). */
25
- const fixturePlan = (): string =>
26
- [
27
- "# Fixture Plan",
28
- "",
29
- "**Spec:** [fixture-design.md](fixture-design.md)",
30
- "",
31
- "- **Parent program**: [fixture-overall.md v1.0](fixture-overall.md)",
32
- "",
33
- "## Constraints",
34
- "",
35
- "- Smoke fixture constraints materialized into the temp repo.",
36
- "",
37
- "### Task 1: fixture task",
38
- "",
39
- "- **Objective**: exercise the installed cdd engine under dry-run",
40
- "- **Files**: fixture-plan.md",
41
- "- **Steps**:",
42
- " 1. run the new-tree engine under dry-run — checkable: the dry-run chain completes",
43
- "- **Acceptance**:",
44
- " - the dry-run chain prints the status capsule",
45
- "- **DependsOn**: none",
46
- "",
47
- ].join("\n");
48
-
49
- /** The fixture design spec — the plan's **Spec:** link target (existence only). */
50
- const fixtureSpec = (): string =>
51
- [
52
- "# Fixture Design",
53
- "",
54
- "- **Version**: v1.0",
55
- "",
56
- "## Design",
57
- "",
58
- "### Acceptance criteria",
59
- "",
60
- "- the smoke chain audits clean",
61
- "",
62
- ].join("\n");
63
-
64
- /** The fixture overall — the plan's **Parent program** link target (existence only). */
65
- const fixtureOverall = (): string =>
66
- [
67
- "# Fixture Overall",
68
- "",
69
- "- **Version**: v1.0",
70
- "",
71
- "## Phase inventory",
72
- "",
73
- "| # | Phase | Status | []",
74
- "|---|-------|--------|-----|",
75
- "",
76
- "",
77
- ]
78
- .join("\n")
79
- .trimEnd();
80
-
81
- /** The smoke assertion surface — one failed assert = the smoke fails loud. */
82
- const assertOk = (cond: boolean, msg: string): void => {
83
- if (!cond) throw new Error(`smoke: ${msg}`);
84
- };
85
-
86
- /** Run the source bin in a cwd (host env injected — the harness detection sees claude). */
87
- const runNode = (args: string[], cwd: string): { code: number; stdout: string; stderr: string } => {
88
- const res = spawnSync(process.execPath, args, {
89
- cwd,
90
- encoding: "utf8",
91
- env: { ...process.env, CLAUDE_CODE_SESSION_ID: "1" },
92
- timeout: 120_000,
93
- });
94
- return {
95
- code: res.status ?? 1,
96
- stdout: (res.stdout ?? "") as string,
97
- stderr: (res.stderr ?? "") as string,
98
- };
99
- };
100
-
101
- /** The capsule contract — the last stdout block carries the status capsule + the
102
- * `next:` suggestion line (the engine's single result surface). The route-face
103
- * words (v1.25 dispatch-ready literals: `done` terminal · `implement wave {tasks}`
104
- * · `review <type> <id> (base …)` · `fix <type> <id> --findings …` + the readback
105
- * suffix · the soft-cap message) — `none` is retired. */
106
- const assertCapsule = (stdout: string, command: string): void => {
107
- const lines = stdout.trim().split("\n");
108
- const capsule = lines.find((l) => l.startsWith("status:") && l.includes("blocker:"));
109
- assertOk(
110
- capsule !== undefined,
111
- `status capsule missing from ${command} stdout: ${JSON.stringify(stdout)}`,
112
- );
113
- assertOk(
114
- /^status: (APPROVED|BLOCKED|REVIEW_FIX|CHANGES_REQUESTED) · blocker: \d+ · handoff: /.test(
115
- capsule!,
116
- ),
117
- `status capsule malformed for ${command}: ${JSON.stringify(capsule)}`,
118
- );
119
- const next = lines.find((l) => l.startsWith("next:"));
120
- assertOk(
121
- next !== undefined && /^next: (done$|implement wave|review |fix($| )|BLOCKED:)/.test(next!),
122
- `next: line missing or malformed for ${command}: ${JSON.stringify(next)}`,
123
- );
124
- // Zero old-shape stdout key lines (the 4-line block is retired).
125
- assertOk(
126
- lines.every((l) => !/^(commits|artifacts|counters):/.test(l)),
127
- `old-shape stdout key line present for ${command}`,
128
- );
129
- };
130
-
131
- /** Run git in the fixture repo (the temp repo's commit identity is injected inline). */
132
- const git = (repo: string, ...args: string[]): void => {
133
- execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: "ignore" });
134
- };
135
-
136
- describe("the engine smoke — the source bin dry-run chain over a fixture repo", () => {
137
- it("boots the bin, asserts the `--help` face + the capsule contract on the dry-run chain", () => {
138
- const repoRoot = mkdtempSync(path.join(tmpdir(), "cdd-smoke-"));
139
- try {
140
- writeFileSync(path.join(repoRoot, ".gitignore"), ".kairos\n");
141
- writeFileSync(path.join(repoRoot, "fixture-plan.md"), fixturePlan(), "utf8");
142
- writeFileSync(path.join(repoRoot, "fixture-design.md"), fixtureSpec(), "utf8");
143
- writeFileSync(path.join(repoRoot, "fixture-overall.md"), fixtureOverall(), "utf8");
144
- git(repoRoot, "init", "-q");
145
- git(
146
- repoRoot,
147
- "-c",
148
- "user.name=cdd-smoke",
149
- "-c",
150
- "user.email=cdd-smoke@oscaner.dev",
151
- "add",
152
- "-A",
153
- );
154
- git(
155
- repoRoot,
156
- "-c",
157
- "user.name=cdd-smoke",
158
- "-c",
159
- "user.email=cdd-smoke@oscaner.dev",
160
- "commit",
161
- "-qm",
162
- "fixture",
163
- );
164
-
165
- // The help face — the commander-native program face (the T4 stable anchor): the
166
- // native Usage first line + the command-table rows (the new-tree CLI's --help is
167
- // the commander program face — `Usage: cdd [options] [command]` + the
168
- // `implement [options]` / `review [options]` / `fix [options]` rows).
169
- const helpOut = runNode([BIN, "--help"], repoRoot);
170
- assertOk(
171
- helpOut.stdout.includes("Usage: cdd [options] [command]") &&
172
- ["implement", "review", "fix"].every((name) =>
173
- helpOut.stdout.includes(`${name} [options]`),
174
- ),
175
- `--help missing the commander-native face (code ${helpOut.code}) stdout=${JSON.stringify(helpOut.stdout.slice(0, 120))} stderr=${JSON.stringify(helpOut.stderr.slice(0, 120))}`,
176
- );
177
-
178
- // The dry-run work chain — implement then review, each asserting the capsule.
179
- let stdout = "";
180
- const chain = [
181
- ["--dry-run", "implement", "--tasks", "1", "--plan", "fixture-plan.md"],
182
- ["--dry-run", "review", "--type", "wave", "--tasks", "1", "--plan", "fixture-plan.md"],
183
- ];
184
- for (const args of chain) {
185
- const res = runNode([BIN, ...args], repoRoot);
186
- assertOk(
187
- res.code === 0,
188
- `dry-run ${args.slice(1, 3).join(" ")} exited ${res.code}: ${res.stderr}`,
189
- );
190
- assertCapsule(res.stdout, args.join(" "));
191
- stdout += res.stdout;
192
- }
193
-
194
- // The fixture repo's workspace slug + the status capsule (the smoke.test.ts
195
- // assertions, migrated in place).
196
- expect(stdout).toContain("status:");
197
- expect(stdout).toContain(".kairos/cdd/fixture/");
198
- } finally {
199
- rmSync(repoRoot, { recursive: true, force: true });
200
- }
201
- });
202
- });
@@ -1,134 +0,0 @@
1
- // packages/cdd-engine/src-next/__tests__/zero-dep.test.ts
2
- // P3.2 zero-dependency guard (T1 → cutover): during the two-tree coexistence window the
3
- // old tree (src) and the new tree (src-next) had to stay mutually import-free. The
4
- // cutover (T15) deleted the old tree — the guard now pins the post-cutover terminal
5
- // state: the retired planes of this package (the src and config planes) are absent from
6
- // disk, and no src-next module specifier may address them (a dangling reference into a
7
- // deleted plane is a hard violation of the plan's zero-residue constraint). The two-way
8
- // scan becomes one-way: src-next is the only live plane left.
9
-
10
- import { readdirSync, readFileSync } from "node:fs";
11
- import { dirname, join, relative, resolve, sep } from "node:path";
12
- import { fileURLToPath } from "node:url";
13
- import { expect, it } from "vitest";
14
-
15
- const SRC_NEXT = fileURLToPath(new URL("../", import.meta.url));
16
- const PKG_ROOT = fileURLToPath(new URL("../../", import.meta.url)); // packages/cdd-engine/
17
-
18
- // The retired-plane discriminant: which deleted plane a module specifier addresses.
19
- // The bare dirnames (no trailing slash — a slash-prefixed form would itself trip the
20
- // cutover's zero-residue grep) are the only retired-plane tokens the guard names.
21
- type RetiredPlane = "src" | "config";
22
- const RETIRED_PLANES: readonly RetiredPlane[] = ["src", "config"];
23
-
24
- /** Which retired plane a first path segment names, or null. */
25
- const retiredBySegment = (head: string | undefined): RetiredPlane | null =>
26
- head === "src" || head === "config" ? head : null;
27
-
28
- /** The retired plane a resolved path falls into (by the package-root-relative first
29
- * segment), or null when the path lives in a live plane or outside the package. */
30
- const retiredByResolved = (resolved: string): RetiredPlane | null => {
31
- return retiredBySegment(relative(PKG_ROOT, resolved).split(sep)[0]);
32
- };
33
-
34
- // Module specifier patterns: `from "..."` (static import + re-export), dynamic
35
- // `import("...")`, and side-effect `import "..."`.
36
- const SPECIFIER_PATTERN = /(?:from\s+|import\s*\(\s*)(['"])([^'"]+)\1/g;
37
- const SIDE_EFFECT_PATTERN = /^\s*import\s+(['"])([^'"]+)\1/gm;
38
-
39
- // Strip comments conservatively (line + block) while keeping string literals, so
40
- // prose that quotes a `from "../src/x"` idiom never trips the guard.
41
- // Heuristic boundary: comment elision applies only in code scope — string-literal
42
- // contents are kept verbatim, and nested template literals are not tracked (a
43
- // backtick inside `${ }` prematurely closes the outer template).
44
- const stripComments = (code: string): string => {
45
- let out = "";
46
- let i = 0;
47
- let inLineComment = false;
48
- let inBlockComment = false;
49
- let inString: "'" | '"' | "`" | null = null;
50
- while (i < code.length) {
51
- const c = code[i];
52
- const next = code[i + 1];
53
- if (inLineComment) {
54
- if (c === "\n") {
55
- inLineComment = false;
56
- out += c;
57
- }
58
- i++;
59
- } else if (inBlockComment) {
60
- if (c === "*" && next === "/") inBlockComment = false;
61
- i++;
62
- } else if (inString) {
63
- if (c === "\\") {
64
- out += c + (next ?? "");
65
- i += 2;
66
- } else {
67
- out += c;
68
- if (c === inString) inString = null;
69
- i++;
70
- }
71
- } else if (c === "/" && next === "/") {
72
- inLineComment = true;
73
- i += 2;
74
- } else if (c === "/" && next === "*") {
75
- inBlockComment = true;
76
- i += 2;
77
- } else {
78
- if (c === "'" || c === '"' || c === "`") inString = c;
79
- out += c;
80
- i++;
81
- }
82
- }
83
- return out;
84
- };
85
-
86
- const listTsFiles = (dir: string, files: string[]): string[] => {
87
- for (const entry of readdirSync(dir, { withFileTypes: true })) {
88
- const full = join(dir, entry.name);
89
- if (entry.isDirectory()) listTsFiles(full, files);
90
- else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) files.push(full);
91
- }
92
- return files;
93
- };
94
-
95
- const extractSpecifiers = (text: string): string[] => {
96
- const specifiers = new Set<string>();
97
- const cleaned = stripComments(text);
98
- for (const match of cleaned.matchAll(SPECIFIER_PATTERN)) specifiers.add(match[2]);
99
- for (const match of cleaned.matchAll(SIDE_EFFECT_PATTERN)) specifiers.add(match[2]);
100
- return [...specifiers];
101
- };
102
-
103
- // Result: the retired plane a module specifier addresses, or null when it addresses
104
- // neither (a live plane, a bare package, a node: builtin, or an external module).
105
- const addressedRetiredPlane = (specifier: string, importer: string): RetiredPlane | null => {
106
- if (!specifier.startsWith("./") && !specifier.startsWith("../") && !specifier.startsWith("/")) {
107
- return retiredBySegment(specifier.split("/")[0]);
108
- }
109
- const resolved = specifier.startsWith("/") ? specifier : resolve(dirname(importer), specifier);
110
- return retiredByResolved(resolved);
111
- };
112
-
113
- it("the retired src and config planes are deleted from the package (the cutover terminal pin)", () => {
114
- const entries = readdirSync(PKG_ROOT);
115
- for (const name of RETIRED_PLANES) {
116
- expect(entries, `deleted plane ${name} must be absent from the package root`).not.toContain(
117
- name,
118
- );
119
- }
120
- });
121
-
122
- it("src-next carries zero module specifiers addressing the retired src or config planes", () => {
123
- const files = listTsFiles(SRC_NEXT, []);
124
- const violations: string[] = [];
125
- for (const file of files) {
126
- for (const specifier of extractSpecifiers(readFileSync(file, "utf8"))) {
127
- const target = addressedRetiredPlane(specifier, file);
128
- if (target !== null) violations.push(`${file} imports "${specifier}"`);
129
- }
130
- }
131
- const message =
132
- violations.length > 0 ? violations.join("\n") : "src-next has no retired-plane references";
133
- expect(violations, message).toEqual([]);
134
- });