feat(docsite): check, caption and sync src= blocks in module READMEs (quick-261118-qsd)

- checkSnippets compares top-level src= fences of module READMEs like
  docs/ pages; the README src= refusal is gone
- Sync also rewrites drifted src= fences in modules/<name>/README.md,
  still all-or-nothing across pages and READMEs
- fenceAnnotator captions top-level src= fences on every page
- the snippet-readme-src planted violation now plants a drifted README
  fence instead of the old refusal
- utilities.md, README.md and CLAUDE.md describe src= in module READMEs
This commit is contained in:
Jakub Zych
2026-11-18 19:29:36 +01:00
parent 830f305376
commit 721830c502
10 changed files with 180 additions and 46 deletions

View File

@@ -504,6 +504,9 @@ func TestNestedFenceChecks(t *testing.T) {
"> ```",
"",
}, "\n")
// A module README's src= fences are checked like a docs/ page's: a
// matching body passes, drift, nesting and refused targets are
// reported at the README's own lines.
readme := strings.Join([]string{
"# fixture",
"",
@@ -515,15 +518,42 @@ func TestNestedFenceChecks(t *testing.T) {
"x := 1",
"```",
"",
"```go src=modules/fixture/fixture.go",
"package fixture",
"```go src=modules/fixture/example_test.go#ExampleHello",
"fmt.Println(\"hello\")",
"// Output: hello",
"```",
"",
"```go src=modules/fixture/example_test.go#ExampleHello",
"stale",
"```",
"",
"- item",
"",
" ```go src=modules/fixture/example_test.go#ExampleHello",
" stale",
" ```",
"",
"> [!NOTE]",
"> ```go src=modules/fixture/example_test.go#ExampleHello",
"> ```",
"",
"```text src=modules/fixture/.env",
"```",
"",
"```go src=modules/fixture/example_test.go#ExampleSilent",
"```",
"",
}, "\n")
exampleTest := "package fixture\n\nimport \"fmt\"\n\n" +
"func ExampleHello() {\n\tfmt.Println(\"hello\")\n\t// Output: hello\n}\n\n" +
"func ExampleSilent() {\n\tfmt.Println(\"quiet\")\n}\n"
const hello = "modules/fixture/example_test.go#ExampleHello"
assertProblems(t, checkFixture(t, fixtureCommands, map[string]string{
"docs/index.md": page("Acme docs", "index", 0, "Text.\n"),
"docs/setup/start.md": page("Start", "setup", 10, body),
"modules/fixture/README.md": readme,
"go.mod": "module example.com/acme\n\ngo 1.27\n",
"docs/index.md": page("Acme docs", "index", 0, "Text.\n"),
"docs/setup/start.md": page("Start", "setup", 10, body),
"modules/fixture/README.md": readme,
"modules/fixture/example_test.go": exampleTest,
}), []string{
"docs/setup/start.md:10: snippet: go code block has no src= reference",
"docs/setup/start.md:16: snippet: go code block has no src= reference",
@@ -531,7 +561,11 @@ func TestNestedFenceChecks(t *testing.T) {
"docs/setup/start.md:24: snippet: main.go code block has no src= reference",
`docs/setup/start.md:34: command: "bogus:nested" is not a summer or application command`,
"docs/setup/start.md:37: snippet: config/app.yaml: " + nestedSrcMessage,
"modules/fixture/README.md:11: snippet: modules/fixture/fixture.go: " + readmeSrcMessage,
"modules/fixture/README.md:16: snippet: body differs from " + hello + " (run: summer docs:sync)",
"modules/fixture/README.md:22: snippet: " + hello + ": " + nestedSrcMessage,
"modules/fixture/README.md:27: snippet: " + hello + ": " + nestedSrcMessage,
"modules/fixture/README.md:30: snippet: modules/fixture/.env: path names a dotfile or .env file",
"modules/fixture/README.md:33: snippet: modules/fixture/example_test.go#ExampleSilent: ExampleSilent has no // Output: comment, so go test compiles it but never runs it",
})
}

View File

@@ -59,10 +59,11 @@ func (fenceAnnotator) Transform(doc *ast.Document, reader text.Reader, pc parser
if !entering || !ok || fc.Info == nil {
return ast.WalkContinue, nil
}
// Captions only on the fences checkSnippets compares: top-level
// src= fences of docs/ pages. A nested or module README fence is
// not verified, so it must not claim a source.
verified := pctx != nil && pctx.page != nil && pctx.page.Module == "" &&
// Captions only on the fences checkSnippets compares: the
// top-level src= fences of every page, docs/ pages and module
// READMEs alike. A nested fence is refused, not verified, so it
// must not claim a source.
verified := pctx != nil && pctx.page != nil &&
fc.Parent() != nil && fc.Parent().Kind() == ast.KindDocument
if !verified {
return ast.WalkContinue, nil

View File

@@ -71,7 +71,7 @@ func renderHTML(t *testing.T, s *site, p *Page) renderedPage {
return r
}
func TestFenceCaptionsOnlyVerified(t *testing.T) {
func TestFenceCaptionsTopLevelSrc(t *testing.T) {
guide := page("Start", "setup", 10, strings.Join([]string{
"```go src=pkg/lib.go#Greeting",
"func Greeting() {}",
@@ -83,7 +83,8 @@ func TestFenceCaptionsOnlyVerified(t *testing.T) {
"> ```",
"",
}, "\n"))
readme := "# alpha\n\nAlpha does one thing.\n\n```go src=modules/alpha/alpha.go\npackage alpha\n```\n"
readme := "# alpha\n\nAlpha does one thing.\n\n```go src=modules/alpha/alpha.go\npackage alpha\n```\n\n" +
"> [!TIP]\n> ```go src=modules/alpha/alpha.go#Nested\n> package alpha\n> ```\n"
s, pages := renderFixture(t, map[string]string{
"docs/setup/start.md": guide,
"modules/alpha/README.md": readme,
@@ -95,9 +96,14 @@ func TestFenceCaptionsOnlyVerified(t *testing.T) {
if !strings.Contains(guideHTML, "<figcaption>pkg/lib.go#Greeting</figcaption>") {
t.Fatalf("guide caption missing the top-level reference\n%s", guideHTML)
}
// A module README captions its top-level src= fence like a docs/
// page; the fence nested in the callout gets none.
readmeHTML := string(renderHTML(t, s, pages["api/alpha"]).html)
if strings.Contains(readmeHTML, "<figcaption>") {
t.Fatalf("module README has a caption\n%s", readmeHTML)
if got := strings.Count(readmeHTML, "<figcaption>"); got != 1 {
t.Fatalf("module README figcaptions = %d, want 1\n%s", got, readmeHTML)
}
if !strings.Contains(readmeHTML, "<figcaption>modules/alpha/alpha.go</figcaption>") {
t.Fatalf("module README caption missing the top-level reference\n%s", readmeHTML)
}
}

View File

@@ -530,14 +530,11 @@ type drift struct {
// its container marker, so the fence is refused instead of extracted.
const nestedSrcMessage = "src= code block must be a top-level block of the page, not inside a callout, blockquote or list item"
// readmeSrcMessage is the problem for a src= fence in a module README.
// Those fences are rendered as written and never compared, so a src=
// there would claim a check that does not run.
const readmeSrcMessage = "module README code blocks are rendered as written; src= is verified only in docs/ pages"
// checkFences verifies every src= fence in fences. lines are the body
// lines the fences index into. lineBase is the 1-based file line of
// lines[0]; file is the display path for problems.
// checkFences verifies every src= fence in fences, on a docs/ page or a
// module README alike: a top-level fence is extracted and compared with
// its source, a nested one is refused. lines are the body lines the
// fences index into. lineBase is the 1-based file line of lines[0]; file
// is the display path for problems.
func checkFences(root, file string, lines []string, lineBase int, fences []mdFence) ([]drift, []Problem, error) {
var drifts []drift
var problems []Problem
@@ -596,9 +593,10 @@ func unindent(l string, n int) string {
return l[i:]
}
// checkSnippets verifies the src= fences of every page. A docs/ page is
// compared with its source. A module README is rendered as written, so
// any src= fence there is refused instead of checked.
// checkSnippets verifies the src= fences of every page, docs/ pages and
// module READMEs alike: each top-level src= fence is compared with its
// source. A README page keeps its file's line indices (BodyLine 1), so
// problems cite the README's own lines.
func (s *site) checkSnippets(docs []parsedDoc) ([]Problem, error) {
var problems []Problem
for _, d := range docs {
@@ -609,17 +607,6 @@ func (s *site) checkSnippets(docs []parsedDoc) ([]Problem, error) {
if err != nil {
return nil, err
}
if d.page.Module != "" {
for _, f := range fences {
ref, ok := ParseSrc(f.info)
if !ok {
continue
}
problems = append(problems, Problem{File: d.file, Line: d.line + f.line, Rule: "snippet",
Message: ref.String() + ": " + readmeSrcMessage})
}
continue
}
_, ps, err := checkFences(s.opts.Root, d.file, strings.Split(string(d.body), "\n"), d.line, fences)
if err != nil {
return nil, err
@@ -629,9 +616,10 @@ func (s *site) checkSnippets(docs []parsedDoc) ([]Problem, error) {
return problems, nil
}
// Sync rewrites every drifted src= fence body under Src from its source,
// preserving everything else byte for byte. When a reference is missing or
// breaks a rule, it returns the problems and writes nothing.
// Sync rewrites every drifted src= fence body from its source, in the
// pages under Src and in every modules/<name>/README.md under Root,
// preserving everything else byte for byte. When a reference anywhere is
// missing or breaks a rule, it returns the problems and writes nothing.
func Sync(opts Options) (SyncResult, []Problem, error) {
opts, err := opts.normalize()
if err != nil {
@@ -642,6 +630,20 @@ func Sync(opts Options) (SyncResult, []Problem, error) {
if err != nil {
return SyncResult{}, nil, err
}
// Module READMEs come from Root, as load ingests them. A module
// without a README is skipped here; load reports it.
names, err := moduleNames(opts.Root)
if err != nil {
return SyncResult{}, nil, err
}
for _, name := range names {
readme := filepath.Join(opts.Root, "modules", name, "README.md")
if _, err := os.Stat(readme); err == nil {
files = append(files, readme)
} else if !errors.Is(err, fs.ErrNotExist) {
return SyncResult{}, nil, fmt.Errorf("docs:sync: %w", err)
}
}
type rewrite struct {
path string
mode fs.FileMode

View File

@@ -478,3 +478,94 @@ func TestSyncParsedFences(t *testing.T) {
t.Fatal(err)
}
}
// treeContents reads every file under root, keyed by path.
func treeContents(t *testing.T, root string) map[string]string {
t.Helper()
files := map[string]string{}
err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
if err != nil || d.IsDir() {
return err
}
b, err := os.ReadFile(p)
if err != nil {
return err
}
files[p] = string(b)
return nil
})
if err != nil {
t.Fatal(err)
}
return files
}
func TestSyncModuleReadme(t *testing.T) {
const alphaTest = "package alpha\n\nimport \"fmt\"\n\n" +
"func ExampleHello() {\n\tfmt.Println(\"hello\")\n\t// Output: hello\n}\n"
readme := strings.Join([]string{
"# alpha",
"",
"Alpha does one thing.",
"",
"`import \"example.com/acme/modules/alpha\"`",
"",
"## Usage",
"",
"Prose before.",
"",
"```go src=modules/alpha/alpha_test.go#ExampleHello",
"stale",
"```",
"",
"Prose `alpha` after.",
"",
"```sh",
"summer docs:build",
"```",
"",
}, "\n")
tree := map[string]string{
"modules/alpha/alpha.go": "package alpha\n",
"modules/alpha/alpha_test.go": alphaTest,
"modules/alpha/README.md": readme,
// A module directory without a README is skipped; load reports it.
"modules/beta/beta.go": "package beta\n",
}
root := snippetTree(t, tree)
path := filepath.Join(root, "modules/alpha/README.md")
res, problems, err := Sync(Options{Root: root})
if err != nil || len(problems) > 0 || res != (SyncResult{Snippets: 1, Files: 1}) {
t.Fatalf("Sync = %+v %q %v", res, problemLines(problems), err)
}
got, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
want := strings.Replace(readme, "stale\n", "fmt.Println(\"hello\")\n// Output: hello\n", 1)
if string(got) != want {
t.Fatalf("synced README =\n%s\nwant\n%s", got, want)
}
if res, problems, err := Sync(Options{Root: root}); err != nil || len(problems) > 0 || res != (SyncResult{}) {
t.Fatalf("second Sync = %+v %q %v", res, problemLines(problems), err)
}
// A refused README fence blocks every write, docs/ pages included.
tree["modules/alpha/README.md"] = readme + "\n```text src=modules/alpha/.env\n```\n"
tree["docs/setup/start.md"] = page("Start", "setup", 10, "```go src=pkg/lib.go#Greeting\nstale\n```\n")
root = snippetTree(t, tree)
before := treeContents(t, root)
res, problems, err = Sync(Options{Root: root})
if err != nil || res != (SyncResult{}) {
t.Fatalf("Sync with a refused README fence = %+v, %v", res, err)
}
assertProblems(t, problemLines(problems), []string{
"modules/alpha/README.md:21: snippet: modules/alpha/.env: path names a dotfile or .env file",
})
after := treeContents(t, root)
for p, b := range before {
if after[p] != b {
t.Errorf("Sync changed %s although a README reference was refused", p)
}
}
}

View File

@@ -19,6 +19,6 @@ go test ./modules/demo
```
```go src=modules/demo/example_test.go#ExampleHello
fmt.Println(demo.Hello("blog"))
// Output: Hello, blog
fmt.Println(demo.Hello("world"))
// Output: Hello, world
```

View File

@@ -1,3 +1,3 @@
rule: snippet
file: modules/demo/README.md
message: modules/demo/example_test.go#ExampleHello: module README code blocks are rendered as written
message: body differs from modules/demo/example_test.go#ExampleHello (run: summer docs:sync)