Skip to content

Commit 0eecf13

Browse files
committed
📝 Let the README's commands be watched rather than swallowed
The runnable Development section was written against contracts that had not landed. It declared a root `<Output />` because that was the only way a text root could fail, ran every task `silent` because a rendered transcript was the alternative to nothing, and redirected the changed-test report to /dev/null because a journaled report of this repository's own scanner fixtures is refused. All three are merged now. #453 settles an uncaught failure at any text root, so fail-fast needs no region. #441 forwards a command's output as it is produced and displays each byte once, so an ordinary `exec` block shows a build or a test run the way typing the command does. #442 keeps nothing without `--journal`, so there is no retained report for the gate to scan and no reason to discard one. So the section says what it now does: the commands stream, the exit status still decides, and `timeout=30m` still bounds the complete battery. The regression that pinned "a successful target renders nothing" is replaced by the one worth having — each command's output reaches the reader exactly once, in order — and RM12 now proves a credential-shaped report reaches the reader unscanned rather than proving a redirection hid it.
1 parent 308a95f commit 0eecf13

2 files changed

Lines changed: 63 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# executable.md
22

3-
<Output />
4-
53
**executable.md** treats markdown documents as executable workflows. A document can expand markdown components, execute annotated code blocks, and evaluate in-process [Effection](https://frontside.com/effection) operations while staying a valid, readable markdown file in any viewer.
64

75
The command-line tool is called **`xmd`** (eXecutable MarkDown).
@@ -347,7 +345,7 @@ deno task xmd run README.md#Development/Verification/Complete # setup, then the
347345
Preparing a checkout is common to all of them, so it lives here rather than in
348346
each one, and runs before whichever heading you selected:
349347

350-
```bash silent exec
348+
```bash exec
351349
deno task setup
352350
```
353351

@@ -377,9 +375,11 @@ restarted by invoking the target again, subject to each low-level command's own
377375
idempotence.
378376

379377
A command that exits nonzero ends the document there: the blocks after it and
380-
the sections beside it do not run, and `xmd run` exits nonzero. A run that
381-
succeeds prints nothing, because these blocks are `silent` — the exit status is
382-
the result.
378+
the sections beside it do not run, and `xmd run` exits nonzero. Until then each
379+
command's output reaches you as it is produced, exactly as it would if you had
380+
typed the command yourself — you watch a build or a test run, you do not wait
381+
for a transcript of one. Nothing is kept: without `--journal` the run records a
382+
command's exit status and never accumulates its output.
383383

384384
`xmd run` is how these sections are meant to be entered. `xmd test README.md`
385385
also executes this document — that command runs a document while looking for
@@ -411,7 +411,7 @@ changing a dependency.
411411
Compiles the standalone `xmd` binary into `dist/`, after building the browser
412412
bundle it embeds:
413413

414-
```bash silent exec
414+
```bash exec
415415
deno task build
416416
```
417417

@@ -425,28 +425,22 @@ The short loop: lint and format, typecheck, the JSR publishability dry run, and
425425
the tests this branch and worktree affect. Each command is its own block, so the
426426
first one to fail is where the document stops.
427427

428-
```bash silent exec
428+
```bash exec
429429
deno task lint
430430
```
431431

432-
```bash silent exec
432+
```bash exec
433433
deno task check
434434
```
435435

436-
```bash silent exec
436+
```bash exec
437437
deno task check:jsr
438438
```
439439

440-
```bash silent exec
441-
deno task test --changed=origin/main >/dev/null
440+
```bash exec
441+
deno task test --changed=origin/main
442442
```
443443

444-
The redirection is the block's, not the task's: a test report is long and this
445-
repository's fixtures deliberately resemble credentials, so the report is
446-
discarded rather than journaled and scanned. The exit status, stderr and failure
447-
diagnostics are untouched, and `deno task test --changed=origin/main` on its own
448-
still prints the complete report.
449-
450444
`deno task verify:focused` is the shorthand that enters this target:
451445

452446
```bash
@@ -458,7 +452,7 @@ deno task verify:focused
458452
The whole applicable battery at once, which also fails if any of it leaves a
459453
tracked file changed:
460454

461-
```bash silent timeout=30m exec
455+
```bash timeout=30m exec
462456
deno task verify
463457
```
464458

‎scripts/tests/readme-targets.test.ts‎

Lines changed: 50 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,20 +34,27 @@ const REPO = fileURLToPath(new URL("../../", import.meta.url));
3434
/** The leaf tasks the README composes. The shim answers for exactly these. */
3535
const LEAF_TASKS = ["setup", "build", "lint", "check", "check:jsr", "test", "verify"];
3636

37+
/** The changed-test leaf, as the shim sees it on the command line. */
38+
const CHANGED_TESTS = "test --changed=origin/main";
39+
3740
/**
38-
* The changed-test leaf as the shim sees it. The README redirects the report
39-
* away, and the shell consumes that redirection, so what reaches `deno` — and
40-
* the log — is the task and its flag alone.
41+
* What the shim prints on stdout for each leaf it answers.
42+
*
43+
* A real task writes to the terminal while it runs, and that is the thing these
44+
* blocks exist to let a contributor watch. The marker stands in for it, so a
45+
* case can ask where that output went and how often.
4146
*/
42-
const CHANGED_TESTS = "test --changed=origin/main";
47+
function marker(task: string): string {
48+
return `xmd-ran:${task}`;
49+
}
4350

4451
/**
4552
* A credential-shaped canary the shim prints when it answers the changed-test
4653
* leaf, assembled from fragments so no complete token-shaped literal is
4754
* committed. The real suite prints strings like it — fixtures for the secret
48-
* scanner — and journaling one fails a run, which is why the README discards
49-
* that report. If the redirection goes, this reaches the exec result and the
50-
* run is refused.
55+
* scanner — and a *journaled* one fails a run. Without `--journal` a run keeps a
56+
* command's exit status alone and never accumulates its output, so there is
57+
* nothing for the gate to scan and the report needs no redirection (#441/#442).
5158
*/
5259
const CANARY_PREFIX = ["gh", "p", "_"].join("");
5360
const CANARY_BODY = `${"abcdefghijklmnopqrstuvwxyz"}${"0123456789"}`;
@@ -62,6 +69,8 @@ const SHIM = [
6269
` ${LEAF_TASKS.join("|")})`,
6370
" shift",
6471
' printf "%s\\n" "$*" >> "$XMD_TASK_LOG"',
72+
" # What a real task writes while it runs.",
73+
' printf "%s%s\\n" "$XMD_MARKER_PREFIX" "$*"',
6574
' if [ "$*" = "$XMD_FAIL_TASK" ]; then',
6675
" exit 1",
6776
" fi",
@@ -120,6 +129,7 @@ function* invoke(args: string[], options: { fail?: string } = {}): Operation<Inv
120129
XMD_TASK_LOG: log,
121130
XMD_REAL_DENO: Deno.execPath(),
122131
XMD_FAIL_TASK: options.fail ?? "",
132+
XMD_MARKER_PREFIX: marker(""),
123133
XMD_CANARY_TASK: CHANGED_TESTS,
124134
XMD_CANARY_PREFIX: CANARY_PREFIX,
125135
XMD_CANARY_BODY: CANARY_BODY,
@@ -172,8 +182,8 @@ describe("Tier RM — README dogfood", () => {
172182
expect(lines).toContain("README.md#Implementation%20feedback");
173183
expect(lines).toContain("README.md#Dependency%20layout");
174184

175-
// The root `<Output />` declares a policy, not a region: every other
176-
// heading in the document is still addressable beside it.
185+
// Making one section executable addresses nothing else differently: every
186+
// other heading in the document is still an ordinary prose target.
177187
expect(lines).toContain("README.md#Install");
178188
expect(lines).toContain("README.md#Status");
179189
// Discovery runs nothing.
@@ -281,27 +291,48 @@ describe("Tier RM — README dogfood", () => {
281291
});
282292

283293
/**
284-
* The changed-test report is discarded by the README's own redirection, not
285-
* by turning the scanner off. The canary the shim prints for that leaf is
286-
* what a real report carries — a fixture shaped like a credential — and a
287-
* journaled one is refused, so a run that succeeds proves the report never
288-
* reached the exec result.
294+
* The report is not redirected, and the scanner is not turned off. The canary
295+
* the shim prints for that leaf is what a real report carries — a fixture
296+
* shaped like a credential — and it reaches the reader unaltered while the
297+
* run keeps none of it. A gate scans what a run retains, and this one retains
298+
* nothing, so there is nothing to refuse (#441/#442).
289299
*/
290-
it("RM12: the entry point succeeds with secret detection still enabled", function* () {
300+
it("RM12: the entry point streams a credential-shaped report and keeps none of it", function* () {
291301
const run = yield* invoke(["verify:focused"]);
292302

293303
expect(run.code).toBe(0);
294304
expect(run.tasks).toEqual([SETUP, ...FOCUSED]);
305+
// The contributor saw the report.
306+
expect(run.stdout).toContain(`${CANARY_PREFIX}${CANARY_BODY}`);
307+
// And nothing scanned or refused it.
295308
expect(run.stderr).not.toContain("secret detection rejected");
296309
// No substitution of --no-secret-detection: the CLI announces that opt-out.
297310
expect(run.stderr).not.toContain("secret detection is disabled");
298311
});
299312

300-
it("RM10: a target that succeeds renders nothing and says so with its status", function* () {
313+
/**
314+
* The point of running a build or a test suite is watching it, so what a
315+
* command writes has to reach the reader — once. A block that forwarded a
316+
* chunk live and then rendered the same text into the document at completion
317+
* would show every line twice, which is the defect this counts.
318+
*/
319+
it("RM10: each command's output reaches the reader live, exactly once", function* () {
301320
const run = yield* invoke(["xmd", "run", "README.md#Development/Build", "--raw"]);
302321
expect(run.code).toBe(0);
303-
// `silent` blocks under a root that declares `<Output />`: the exit status
304-
// is the result, and no section text is emitted around them.
305-
expect(run.stdout).toBe("");
322+
323+
expect(occurrences(run.stdout, marker(SETUP))).toBe(1);
324+
expect(occurrences(run.stdout, marker(BUILD))).toBe(1);
325+
// In the order the document runs them: the ancestor's preparation, then the
326+
// leaf's own command.
327+
expect(run.stdout.indexOf(marker(SETUP))).toBeLessThan(run.stdout.indexOf(marker(BUILD)));
328+
// Beside the section's own prose, which is what `--raw` renders.
329+
expect(run.stdout).toContain("Compiles the standalone");
330+
// And nothing from a sibling the target did not select.
331+
expect(run.stdout).not.toContain(marker(VERIFY));
306332
});
307333
});
334+
335+
/** How many times `needle` occurs in `text`. */
336+
function occurrences(text: string, needle: string): number {
337+
return text.split(needle).length - 1;
338+
}

0 commit comments

Comments
 (0)