Skip to content

Commit de3068e

Browse files
authored
🎯 Describe a document's targets in its own run help (#478)
* 🎯 Describe a document's targets in its own run help (#463) Discovery moves from the standalone `xmd targets` command into `xmd run <document> --help`, which already inspects the document once to describe its properties. The same inspection now also supplies a catalog of targets, each named by the reference that selects it and described by the first static paragraph its section states. `DocumentInfo` gains an additive `targetCatalog`; `targets` stays the canonical identity surface, byte-for-byte and order-for-order unchanged, and mapping the catalog back to its `target` members reproduces it. Descriptions come from the same masked Remark parse that discovers the headings, so no document is parsed twice, and a paragraph that is not wholly static is omitted whole rather than as a static prefix. * 🏷️ Name the additive inspection field targetInfo (#463) The field is one name, and it runs from the outline through the parsed root document to the public inspection result. * 🧪 Ask CT19 for the journal it proves help never creates (#463) The case asserted `trace.jsonl` was absent without ever requesting a journal, so it could not tell help apart from any run. It now passes `--journal` and asserts that exact path stays absent. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent e506292 commit de3068e

18 files changed

Lines changed: 937 additions & 378 deletions

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,8 +231,10 @@ jobs:
231231
printf '%s\n%s\n' \
232232
'smoke-test/document-targets.md#Alpha' \
233233
'smoke-test/document-targets.md#Beta' > /tmp/targets.expected
234-
./dist/xmd targets smoke-test/document-targets.md > /tmp/targets.out
234+
./dist/xmd run smoke-test/document-targets.md --help > /tmp/help.out
235+
grep -o 'smoke-test/document-targets\.md#[A-Za-z]*' /tmp/help.out > /tmp/targets.out
235236
diff /tmp/targets.expected /tmp/targets.out
237+
grep -q 'ALPHA_DESCRIBED' /tmp/help.out
236238
237239
./dist/xmd run 'smoke-test/document-targets.md#Alpha' --raw > /tmp/targeted.out
238240
grep -q 'ALPHA_RAN' /tmp/targeted.out

‎README.md‎

Lines changed: 49 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -51,20 +51,16 @@ Success provides the prepared checkout every command in this guide reads from,
5151
including the source CLI the targets below run through.
5252

5353
With that in place, this guide is itself an executable document: each section is
54-
a target you can select, and selecting one runs the commands it describes.
54+
a target you can select, and selecting one runs the commands it describes. Ask
55+
the document what it offers:
5556

5657
```bash
57-
deno task xmd targets README.md
58+
deno task xmd run README.md --help
5859
```
5960

60-
```text
61-
README.md#Setup
62-
README.md#Build
63-
README.md#Test
64-
README.md#Test/Focused
65-
README.md#Test/Complete
66-
README.md#Bootstrap
67-
```
61+
It answers with the properties this document declares and every target you can
62+
invoke, each named by the reference that selects it and described by what
63+
selecting it does.
6864

6965
Preparation is common to all of them, so the block above is the document's own
7066
preamble: whichever target you select runs it first, and the checkout is
@@ -88,62 +84,64 @@ deno task verify # the whole applicable battery, concurrently
8884

8985
## Setup
9086

91-
Run this after changing a dependency, or whenever you want the checkout restored
92-
on its own without building or testing.
87+
Prepare both dependency layouts and the browser bundle, yielding a checkout
88+
ready for every build and verification command in this guide.
9389

9490
```bash
9591
deno task xmd run README.md#Setup
9692
```
9793

98-
It executes `deno task setup`, the preamble block above and the only thing in
99-
this repository that installs. Setup owns both dependency layouts —
100-
`node_modules/` and Deno's global cache — and prepares them in the order their
101-
union resolves in: Deno's frozen install and cached module graphs first, then
102-
pnpm's store beside it, then the browser bundle.
94+
Select it after changing a dependency, or whenever you want the checkout
95+
restored on its own without building or testing. It executes `deno task setup`,
96+
the preamble block above and the only thing in this repository that installs.
97+
Setup owns both dependency layouts — `node_modules/` and Deno's global cache —
98+
and prepares them in the order their union resolves in: Deno's frozen install
99+
and cached module graphs first, then pnpm's store beside it, then the browser
100+
bundle.
103101

104-
Success provides a prepared checkout: both dependency layouts resolved for Deno,
105-
`tsc`, Bun, oxlint and the site, and the generated browser bundle the binary
106-
embeds. Builds and checks read what setup prepared and leave tracked files,
107-
`node_modules` and `deno.lock` as they found them, so they compose with one
108-
another.
102+
The prepared layouts resolve for Deno, `tsc`, Bun, oxlint and the site. Builds
103+
and checks read what setup prepared and leave tracked files, `node_modules` and
104+
`deno.lock` as they found them, so they compose with one another.
109105

110106
## Build
111107

112-
Compile the standalone `xmd` binary.
108+
Compile the standalone `xmd` binary: prepare the checkout and then build,
109+
yielding `dist/xmd`, a self-contained executable for this host.
113110

114111
```bash
115112
deno task xmd run README.md#Build
116113
```
117114

118-
It prepares the checkout, then runs the build, which produces the browser bundle
119-
the binary embeds and compiles the CLI for this host.
115+
The build produces the browser bundle the binary embeds and compiles the CLI.
120116

121117
```bash exec
122118
deno task build
123119
```
124120

125-
Success provides `dist/xmd`: a self-contained executable you can run directly.
121+
Run `dist/xmd` directly once it reports success.
126122

127123
## Test
128124

129-
Testing comes in two levels, and this heading is the parent of both. Focused is
130-
the evidence a change offers for review; Complete is the battery that decides
131-
whether it merges.
125+
Run Focused and then Complete, yielding implementation-feedback evidence and
126+
delivery verification from one invocation.
132127

133128
```bash
134129
deno task xmd run README.md#Test
135130
```
136131

137-
Selecting it runs Focused, then Complete, so one invocation produces both:
138-
implementation-feedback evidence, followed by delivery verification.
132+
Testing comes in two levels, and this heading is the parent of both: Focused is
133+
the evidence a change offers for review, and Complete is the battery that
134+
decides whether it merges.
139135

140136
### Focused
141137

142-
The evidence an implementation offers with a feedback commit: enough to show the
143-
change is sound, in the time a feedback loop can afford. It runs the lint and
144-
format check, the typecheck, the JSR publishability dry run, and the tests this
145-
branch and worktree affect — each as its own block, so the first command to fail
146-
is where the run stops and what it stopped on is unambiguous.
138+
Run the lint and format check, the typecheck, the JSR publishability dry run,
139+
and the tests this branch and worktree affect, yielding the evidence a feedback
140+
commit is offered with.
141+
142+
That is enough to show the change is sound, in the time a feedback loop can
143+
afford. Each check is its own block, so the first command to fail is where the
144+
run stops and what it stopped on is unambiguous.
147145

148146
```bash
149147
deno task verify:focused
@@ -174,30 +172,34 @@ describes what happens next.
174172

175173
### Complete
176174

177-
The delivery battery — the same checks CI requires, started together.
175+
Run the complete applicable battery concurrently, yielding delivery
176+
verification and proof that the worktree it ran in is unchanged.
178177

179178
```bash
180179
deno task xmd run README.md#Test/Complete
181180
```
182181

183-
It runs `deno task verify`, which starts every applicable command at once,
184-
reports them in a fixed order however they finish, and prints the first
185-
failure's output in full.
182+
It runs `deno task verify`, the same checks CI requires: every applicable
183+
command starts at once, they are reported in a fixed order however they finish,
184+
and the first failure's output is printed in full.
186185

187186
```bash timeout=30m exec
188187
deno task verify
189188
```
190189

191-
Success provides delivery verification: the whole battery passed, and the
192-
worktree it ran in is unchanged — `verify` compares tracked files afterwards and
193-
fails if any command moved one, so a green result is also evidence that the
194-
battery left the repository exactly as it found it.
190+
`verify` compares tracked files afterwards and fails if any command moved one,
191+
so a green result is also evidence that the battery left the repository exactly
192+
as it found it.
195193

196194
## Bootstrap
197195

198-
Adding a package to `packages/*` needs one manual step before CI can release it.
199-
A tagged release publishes to npm with OIDC, and OIDC can only publish a package
200-
that already exists — so the name is reserved by hand, once, per package.
196+
Validate and reserve a new workspace package name on npm, yielding the empty
197+
package a later tagged release publishes to.
198+
199+
Adding a package to `packages/*` needs this one manual step before CI can
200+
release it: a tagged release publishes with OIDC, and OIDC can only publish a
201+
package that already exists, so the name is reserved by hand, once, per
202+
package.
201203

202204
```bash
203205
npm login

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2084,7 +2084,7 @@ Status is measured against main.
20842084
| `<Output>` rendering selection | chooses which regions of a body render, and buffers a root that declares one; it decides nothing about failure | built on main |
20852085
| `Expansion` / `getExpansion()` | describes the current logical element expansion | built on main |
20862086
| document targets | catalogs a root document's addressable static headings, resolves one selector to one exact target, and projects the document to it before expansion | built on the #412 stack |
2087-
| `xmd targets` | prints one document's catalog as full document references, by inspection alone | built on the #412 stack |
2087+
| document-aware `xmd run … --help` | describes what one document declares and every target it addresses, each as a full document reference with the description its section states, by inspection alone | built on the #463 stack |
20882088
| targeted `xmd run` | reads a file argument as a document reference and executes the one exact target its selector resolved to, replacing the selector before execution rereads the file | built on the #412 stack |
20892089
| targeted workflow definition | the V1 workflow definition optionally carries the exact canonical document target, which takes part in definition identity and in compatible reuse | built on the #412 stack; the workflow CLI does not supply one yet |
20902090
| `workflowInstallation()` / `getWorkflowRun()` | associates one document execution with a workflow run, through an `ExecutionInstallation` the trusted host passes to `executeInstalled()` | built on the #366 stack |

0 commit comments

Comments
 (0)