Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<Value name="…" />`.
- **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 `<Output name="…" />`,
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 `<Value>`, with the constant of spin's that decides it
(`spin:<file>#<Constant> = 15m`), which `task reference:check` reads and holds the line to; with the text of a file
Expand Down
12 changes: 10 additions & 2 deletions src/components/Output.astro
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,23 @@
// 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';

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;
---

<Code code={output(name)} lang={lang} title={caption} />
<Code code={output(name)} lang={lang} title={caption} mark={mark} ins={ins} del={del} />
2 changes: 1 addition & 1 deletion src/content/docs/use/agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ spin snapshot diff task-1 <after-id> --from <before-id> -o json
spin workspace delete task-1
```

<Output name="diff.json" caption="spin snapshot diff task-1 <after-id> --from <before-id> -o json" lang="json" />
<Output name="diff.json" caption="spin snapshot diff task-1 <after-id> --from <before-id> -o json" lang="json" ins="FILE_CHANGE_KIND_ADDED" mark="FILE_CHANGE_KIND_MODIFIED" del="FILE_CHANGE_KIND_REMOVED" />

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
Expand Down
4 changes: 2 additions & 2 deletions src/lib/pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(
/<Output\s+name="([\w.-]+)"\s+caption="([^"]*)"(?:\s+lang="(\w+)")?\s*\/>/g,
/<Output\s+name="([\w.-]+)"\s+caption="([^"]*)"(?:\s+lang="(\w+)")?(?:\s+(?:mark|ins|del)="[^"]*")*\s*\/>/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.
Expand Down
1 change: 1 addition & 0 deletions tools/refgen/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) },
Expand Down
51 changes: 51 additions & 0 deletions tools/refgen/outputs.go
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -32,3 +37,49 @@ func outputFiles(spin, dir string, check bool) ([]string, error) {
}
return stale, nil
}

var (
// outputTag is a page's <Output name="..." caption="..." .../>; a caption may hold a >.
outputTag = regexp.MustCompile(`<Output((?:\s+\w+="[^"]*")*)\s*/>`)
outputAttr = regexp.MustCompile(`(\w+)="([^"]*)"`)
)

// checkOutputMarks holds what a page marks in a command's output (mark=, ins=, del= of
// <Output>) 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
}
28 changes: 28 additions & 0 deletions tools/refgen/outputs_test.go
Original file line number Diff line number Diff line change
@@ -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": `<Output name="diff.txt" caption="spin snapshot diff <id>" mark="/etc/hosts" ins="A /etc/greeting" />` + "\n" +
`<Output name="diff.txt" caption="x" del="D /etc/issue" />` + "\n" +
`<Output name="gone.txt" caption="x" mark="y" />` + "\n" +
`<Output name="gone.txt" caption="x" />` + "\n" +
`<Output name="diff.txt" caption="x" mark="" />` + "\n",
"reference/cli.md": `<Output name="diff.txt" caption="x" mark="nowhere" />` + "\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`)
}