From 109753144c5bdd001caa18d07a2d280ac2cc8a51 Mon Sep 17 00:00:00 2001 From: Manuel de Brito Fontes Date: Thu, 19 Nov 2026 14:52:03 -0300 Subject: [PATCH 1/2] Output: mark, ins and del point at text of a golden, and refgen fails on one it lost Expressive Code marks nothing and says nothing when a marker's text is not there, so a golden that changed would take the mark away unseen. Co-Authored-By: Claude Opus 5.5 --- README.md | 6 +++++ src/components/Output.astro | 12 +++++++-- src/lib/pages.ts | 4 +-- tools/refgen/main.go | 1 + tools/refgen/outputs.go | 51 ++++++++++++++++++++++++++++++++++++ tools/refgen/outputs_test.go | 28 ++++++++++++++++++++ 6 files changed, 98 insertions(+), 4 deletions(-) create mode 100644 tools/refgen/outputs_test.go diff --git a/README.md b/README.md index 9dad9e0..a3b32ee 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,12 @@ that is not one task (`taskgate`). - **Figures the code decides** - a volume's commit size, how much older a runner may be, how long CloudWatch keeps the logs - are `src/data/constants.json`, read from spin's constants and the module's defaults by `task reference`, and a page shows one with ``. +- **What a command prints** is the golden a test in spin holds it to, copied by `task reference` + into `src/data/output` (`outputs` in `tools/refgen`) and shown with ``, + never retyped. A page points at what matters in it without editing it: `mark="…"`, `ins="…"` + and `del="…"` are text of the output, which the block marks wherever it occurs, and refgen + fails on one the golden no longer has, so a change to what the command prints cannot take a + mark away unseen. The Markdown twin is the plain block. - **A figure said in prose has a line** in `tools/refgen/figures.txt`: every duration, size and count a hand-written page says outside ``, with the constant of spin's that decides it (`spin:# = 15m`), which `task reference:check` reads and holds the line to; with the text of a file diff --git a/src/components/Output.astro b/src/components/Output.astro index a8c11ac..f55c2d5 100644 --- a/src/components/Output.astro +++ b/src/components/Output.astro @@ -2,6 +2,11 @@ // What a spin command prints, as a golden in spin holds it (tools/refgen copies them into // src/data/output): shown as a block of output, never retyped. Its Markdown twin is the same // block (src/lib/pages.ts). +// +// mark, ins and del point at what matters without editing the golden: each is text of the +// output, every occurrence of which Expressive Code marks. Text, not a line number - a line +// number keeps pointing after the golden moves, at whatever line is there now; text that is gone +// fails refgen's check (checkOutputMarks). import { Code } from '@astrojs/starlight/components'; import { output } from '../lib/output'; @@ -9,8 +14,11 @@ interface Props { name: string; caption: string; lang?: string; + mark?: string; + ins?: string; + del?: string; } -const { name, caption, lang = 'text' } = Astro.props; +const { name, caption, lang = 'text', mark, ins, del } = Astro.props; --- - + diff --git a/src/lib/pages.ts b/src/lib/pages.ts index 06bc03e..06645d2 100644 --- a/src/lib/pages.ts +++ b/src/lib/pages.ts @@ -112,9 +112,9 @@ export function toMarkdown(d: Doc, base: string): string { body = body.replace(/\{published\}/g, published).replace(/\{generated\}/g, generated); // A screenshot is its alt text: a twin has no picture to show. body = body.replace(/!\[([^\]]*)\]\([^)]*\.png\)/g, '*Screenshot: $1.*'); - // What a command prints is the same block of output. + // What a command prints is the same block of output; what the page marks in it is the page's. body = body.replace( - //g, + //g, (_, name: string, caption: string, lang = 'text') => `${caption}:\n\n\`\`\`${lang}\n${output(name)}\n\`\`\``, ); // A diagram is its caption, its words in the order the picture has them, and where it is drawn. diff --git a/tools/refgen/main.go b/tools/refgen/main.go index ad67cc0..1140934 100644 --- a/tools/refgen/main.go +++ b/tools/refgen/main.go @@ -169,6 +169,7 @@ func run() error { bad = append(bad, shotBad...) for _, c := range []func() ([]string, error){ func() ([]string, error) { return checkDescriptions(*docs) }, + func() ([]string, error) { return checkOutputMarks(*docs, *outputsDir) }, func() ([]string, error) { return checkRepos(*docs) }, func() ([]string, error) { return checkPins(*pinned, r) }, func() ([]string, error) { return checkDomains(*docs, *tf) }, diff --git a/tools/refgen/outputs.go b/tools/refgen/outputs.go index 58c8c13..976038e 100644 --- a/tools/refgen/outputs.go +++ b/tools/refgen/outputs.go @@ -1,8 +1,13 @@ package main import ( + "bytes" + "errors" + "fmt" + "io/fs" "os" "path/filepath" + "regexp" ) // outputs are what spin's CLI prints that the site shows as its output: goldens a test in spin @@ -32,3 +37,49 @@ func outputFiles(spin, dir string, check bool) ([]string, error) { } return stale, nil } + +var ( + // outputTag is a page's ; a caption may hold a >. + outputTag = regexp.MustCompile(``) + outputAttr = regexp.MustCompile(`(\w+)="([^"]*)"`) +) + +// checkOutputMarks holds what a page marks in a command's output (mark=, ins=, del= of +// ) to the golden it shows: each must be text the output has. Expressive Code marks +// nothing, and says nothing, when the text is not there, so a golden that changes would take the +// mark away and leave the page pointing at nothing. +func checkOutputMarks(docs, dir string) ([]string, error) { + var bad []string + err := handPages(docs, func(path string, raw []byte) error { + for i, line := range bytes.Split(raw, []byte("\n")) { + for _, tag := range outputTag.FindAllSubmatch(line, -1) { + attrs := map[string]string{} + var marks [][2]string + for _, a := range outputAttr.FindAllSubmatch(tag[1], -1) { + k, v := string(a[1]), string(a[2]) + attrs[k] = v + if k == "mark" || k == "ins" || k == "del" { + marks = append(marks, [2]string{k, v}) + } + } + if len(marks) == 0 { + continue + } + out, err := os.ReadFile(filepath.Join(dir, attrs["name"])) + if errors.Is(err, fs.ErrNotExist) { + bad = append(bad, fmt.Sprintf("%s:%d: no output %q in %s", path, i+1, attrs["name"], dir)) + continue + } else if err != nil { + return err + } + for _, m := range marks { + if m[1] == "" || !bytes.Contains(out, []byte(m[1])) { + bad = append(bad, fmt.Sprintf("%s:%d: %s=%q is not in %s", path, i+1, m[0], m[1], attrs["name"])) + } + } + } + } + return nil + }) + return bad, err +} diff --git a/tools/refgen/outputs_test.go b/tools/refgen/outputs_test.go new file mode 100644 index 0000000..f937c62 --- /dev/null +++ b/tools/refgen/outputs_test.go @@ -0,0 +1,28 @@ +package main + +import ( + "path/filepath" + "testing" +) + +// A mark on a command's output is text the golden has: one the golden lost fails, wherever on +// the tag it is and whatever the caption holds, and an Output with no mark is not read. +func TestWhatAPageMarksInAnOutputIsInTheGolden(t *testing.T) { + dir := writePage(t, map[string]string{"diff.txt": "A /etc/greeting\nM /etc/hosts\n"}) + docs := writePage(t, map[string]string{ + "use/agents.mdx": `` + "\n" + + `` + "\n" + + `` + "\n" + + `` + "\n" + + `` + "\n", + "reference/cli.md": `` + "\n", + }) + bad, err := checkOutputMarks(docs, dir) + if err != nil { + t.Fatal(err) + } + wantBad(t, bad, + filepath.Join("use", "agents.mdx")+`:2: del="D /etc/issue" is not in diff.txt`, + `agents.mdx:3: no output "gone.txt"`, + `agents.mdx:5: mark="" is not in diff.txt`) +} From 56ff37f280b399b72d15bb968f3f1ada73c911fc Mon Sep 17 00:00:00 2001 From: Manuel de Brito Fontes Date: Thu, 19 Nov 2026 14:52:03 -0300 Subject: [PATCH 2/2] use/agents: the diff's output marks what was added, changed and removed Co-Authored-By: Claude Opus 5.5 --- src/content/docs/use/agents.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/use/agents.mdx b/src/content/docs/use/agents.mdx index f5c94a0..1f2ac3b 100644 --- a/src/content/docs/use/agents.mdx +++ b/src/content/docs/use/agents.mdx @@ -25,7 +25,7 @@ spin snapshot diff task-1 --from -o json spin workspace delete task-1 ``` - + Every command prints JSON with `-o json`: the whole answer, each file's type, mode, size and hash on both sides. A model reading this site starts at