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

@@ -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)
}
}