Skip to content

Commit 8e25614

Browse files
committed
docs(build): reattach the library-graph guard's explanation to the guard
Restructuring `assertPromptsGraph` into `assertLibraryGraphs` left its doc block sitting immediately above `checkLibraryEntry`'s own doc block, so the rich one attached to nothing and `assertLibraryGraphs` — the function a reader actually looks up — had no documentation at all. The orphaned block is the one carrying the reasoning worth keeping: the two rules the guard enforces, and why this is enforced in the build rather than asserted by a test over the artifact, including the prompts.test.ts regex-scan story that produced that decision. Prose no tool associates with a symbol is prose nobody finds. Also generalizes one phrase it inherited: the guard covers every library entry now, not only the render path. Found by the review on #215.
1 parent f9b6170 commit 8e25614

1 file changed

Lines changed: 27 additions & 27 deletions

File tree

‎packages/cli/vite.config.ts‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -166,33 +166,6 @@ function findEntryChunk(
166166
);
167167
}
168168

169-
/**
170-
* Refuse to emit a library entry that drags the CLI runtime along with it.
171-
*
172-
* `@taskless/cli/prompts` renders recipe text; `@taskless/cli/layout` is the
173-
* rule layout table a service builds payloads against. Both are imported by
174-
* consumers that are not this CLI — a Worker among them — so neither may pull
175-
* in the command layer or reach a host capability. The graph is allowed to
176-
* touch embedded text and the pure values it exports, and nothing else.
177-
*
178-
* Two rules, both checked over the entry's transitive chunk graph:
179-
*
180-
* - **No external imports at all.** Everything but node builtins is bundled
181-
* (see `rollupOptions.external`), so a bare specifier surviving here is a
182-
* builtin — `node:fs`, `node:child_process` — and the render path has no
183-
* business with any of them.
184-
* - **Never reach the bin entry.** That chunk is the CLI itself.
185-
*
186-
* ENFORCED IN THE BUILD, DELIBERATELY, rather than asserted by a test over the
187-
* artifact. A build that refuses to emit a leaking bundle makes the bad artifact
188-
* unproducible; a test that inspects one afterwards only notices. It is also
189-
* the difference between reading rollup's own resolved graph and reconstructing
190-
* it: the test this replaces regex-scanned built JavaScript for `from "…"`, and
191-
* a chunk embeds every recipe as a string literal, so the engine-selection
192-
* recipe's `a different axis from "which engine"` was reported as an import.
193-
* `imports`/`dynamicImports` below are the real thing and cannot be spoofed by
194-
* prose.
195-
*/
196169
/**
197170
* Walk one library entry's transitive chunk graph, failing the build on a leak.
198171
*
@@ -239,6 +212,33 @@ function checkLibraryEntry(
239212
}
240213
}
241214

215+
/**
216+
* Refuse to emit a library entry that drags the CLI runtime along with it.
217+
*
218+
* `@taskless/cli/prompts` renders recipe text; `@taskless/cli/layout` is the
219+
* rule layout table a service builds payloads against. Both are imported by
220+
* consumers that are not this CLI — a Worker among them — so neither may pull
221+
* in the command layer or reach a host capability. The graph is allowed to
222+
* touch embedded text and the pure values it exports, and nothing else.
223+
*
224+
* Two rules, both checked over the entry's transitive chunk graph:
225+
*
226+
* - **No external imports at all.** Everything but node builtins is bundled
227+
* (see `rollupOptions.external`), so a bare specifier surviving here is a
228+
* builtin — `node:fs`, `node:child_process` — and a library entry has no
229+
* business with any of them.
230+
* - **Never reach the bin entry.** That chunk is the CLI itself.
231+
*
232+
* ENFORCED IN THE BUILD, DELIBERATELY, rather than asserted by a test over the
233+
* artifact. A build that refuses to emit a leaking bundle makes the bad artifact
234+
* unproducible; a test that inspects one afterwards only notices. It is also
235+
* the difference between reading rollup's own resolved graph and reconstructing
236+
* it: the test this replaces regex-scanned built JavaScript for `from "…"`, and
237+
* a chunk embeds every recipe as a string literal, so the engine-selection
238+
* recipe's `a different axis from "which engine"` was reported as an import.
239+
* `imports`/`dynamicImports` below are the real thing and cannot be spoofed by
240+
* prose.
241+
*/
242242
function assertLibraryGraphs(): Plugin {
243243
return {
244244
name: "assert-library-graphs",

0 commit comments

Comments
 (0)