feat(11.1-01): verify src= code blocks and add summer docs:sync
- src= fences name a file, a Go declaration or Example body, or a docs:start region - confinement: relative clean paths inside the root, no dotfiles or .env, no nested go.mod modules, Examples need // Output:, test regions must run - a drifted or missing snippet is a problem, so docs:build writes nothing - docs:sync rewrites drifted fence bodies in place - fences render in figure.code with a source caption; .md fences keep only the language - bonfire ExampleCall is the first verified example, shown in setup/installation
This commit is contained in:
Jakub Zych
@@ -147,3 +147,232 @@ func TestReadmeIngestion(t *testing.T) {
|
||||
t.Errorf("search index missing the alpha Usage entry: %s", search)
|
||||
}
|
||||
}
|
||||
|
||||
const snippetSite = `title: Acme
|
||||
description: Acme docs.
|
||||
sections:
|
||||
- name: setup
|
||||
title: Setup
|
||||
`
|
||||
|
||||
const libGo = `package lib
|
||||
|
||||
// Greeting returns a greeting.
|
||||
func Greeting(name string) string {
|
||||
return "Hello, " + name
|
||||
}
|
||||
|
||||
const (
|
||||
// A is the first.
|
||||
A = 1
|
||||
B = 2
|
||||
)
|
||||
`
|
||||
|
||||
const libTestGo = `package lib
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestGreeting(t *testing.T) {
|
||||
// docs:start call
|
||||
got := Greeting("x")
|
||||
// docs:end call
|
||||
if got == "" || check() == "" {
|
||||
t.Fatal("empty")
|
||||
}
|
||||
}
|
||||
|
||||
func check() string {
|
||||
// docs:start called
|
||||
return Greeting("y")
|
||||
// docs:end called
|
||||
}
|
||||
|
||||
func helper() string {
|
||||
// docs:start orphan
|
||||
return "x"
|
||||
// docs:end orphan
|
||||
}
|
||||
|
||||
func ExampleGreeting() {
|
||||
fmt.Println(Greeting("blog"))
|
||||
// Output: Hello, blog
|
||||
}
|
||||
|
||||
func ExampleB() {
|
||||
_ = Greeting("x")
|
||||
}
|
||||
`
|
||||
|
||||
// snippetTree is a repository fixture with Go sources, tests and YAML that
|
||||
// src= references can name.
|
||||
func snippetTree(t *testing.T, extra map[string]string) string {
|
||||
t.Helper()
|
||||
files := map[string]string{
|
||||
"go.mod": "module example.com/acme\n\ngo 1.27\n",
|
||||
"docs/site.yaml": snippetSite,
|
||||
"docs/index.md": page("Acme docs", "index", 0, "Hello.\n"),
|
||||
"pkg/lib.go": libGo,
|
||||
"pkg/lib_test.go": libTestGo,
|
||||
"config/app.yaml": "app:\n # docs:start db\n db:\n host: localhost\n # docs:end db\n",
|
||||
"nested/go.mod": "module example.com/nested\n",
|
||||
"nested/x.go": "package nested\n\n// X is x.\nconst X = 1\n",
|
||||
"nested/x_test.go": "package nested\n",
|
||||
"notests/a.go": "package notests\n\n// A is a.\nconst A = 1\n",
|
||||
"docs/setup/start.md": page("Start", "setup", 10, "Text.\n"),
|
||||
}
|
||||
for k, v := range extra {
|
||||
files[k] = v
|
||||
}
|
||||
return writeTree(t, files)
|
||||
}
|
||||
|
||||
func TestSnippetForms(t *testing.T) {
|
||||
root := snippetTree(t, nil)
|
||||
for _, tc := range []struct {
|
||||
ref Ref
|
||||
want string
|
||||
}{
|
||||
{Ref{Path: "pkg/lib.go"}, libGo},
|
||||
{Ref{Path: "pkg/lib.go", Fragment: "Greeting"}, "// Greeting returns a greeting.\nfunc Greeting(name string) string {\n\treturn \"Hello, \" + name\n}"},
|
||||
{Ref{Path: "pkg/lib.go", Fragment: "A"}, "// A is the first.\n\tA = 1"},
|
||||
{Ref{Path: "pkg/lib.go", Fragment: "B"}, "B = 2"},
|
||||
{Ref{Path: "pkg/lib_test.go", Fragment: "ExampleGreeting"}, "fmt.Println(Greeting(\"blog\"))\n// Output: Hello, blog"},
|
||||
{Ref{Path: "pkg/lib_test.go", Fragment: "call"}, "got := Greeting(\"x\")"},
|
||||
{Ref{Path: "pkg/lib_test.go", Fragment: "called"}, "return Greeting(\"y\")"},
|
||||
{Ref{Path: "pkg/lib_test.go", Fragment: "check"}, "func check() string {\n\t// docs:start called\n\treturn Greeting(\"y\")\n\t// docs:end called\n}"},
|
||||
{Ref{Path: "config/app.yaml", Fragment: "db"}, "db:\n host: localhost"},
|
||||
} {
|
||||
got, err := Extract(root, tc.ref)
|
||||
if err != nil {
|
||||
t.Errorf("Extract(%s): %v", tc.ref, err)
|
||||
continue
|
||||
}
|
||||
if got != tc.want {
|
||||
t.Errorf("Extract(%s) = %q, want %q", tc.ref, got, tc.want)
|
||||
}
|
||||
}
|
||||
for _, ref := range []Ref{{Path: "pkg/lib.go", Fragment: "Missing"}, {Path: "pkg/nope.go"}, {Path: "config/app.yaml", Fragment: "nope"}} {
|
||||
if _, err := Extract(root, ref); err != errSnippetNotFound {
|
||||
t.Errorf("Extract(%s) err = %v, want not found", ref, err)
|
||||
}
|
||||
}
|
||||
if ref, ok := ParseSrc("go src=pkg/lib.go#Greeting title=x"); !ok || ref != (Ref{Path: "pkg/lib.go", Fragment: "Greeting"}) {
|
||||
t.Errorf("ParseSrc = %+v %v", ref, ok)
|
||||
}
|
||||
if _, ok := ParseSrc("go"); ok {
|
||||
t.Error("ParseSrc found src= in a bare info string")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSnippetConfinement(t *testing.T) {
|
||||
outside := filepath.Join(t.TempDir(), "secret.txt")
|
||||
if err := os.WriteFile(outside, []byte("secret\n"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
cases := []struct{ src, want string }{
|
||||
{"/etc/passwd", "path must be relative"},
|
||||
{"../x.go", "must not leave the repository root"},
|
||||
{".env", "dotfile or .env file"},
|
||||
{"config/prod.env", "dotfile or .env file"},
|
||||
{"nested/x.go#X", "nested module nested/go.mod"},
|
||||
{"escape.txt", "outside the repository root"},
|
||||
{"notests/a.go#A", "no _test.go files"},
|
||||
{"pkg/lib_test.go#ExampleB", "has no // Output: comment"},
|
||||
{"pkg/lib_test.go#orphan", "not inside a Test or Example function"},
|
||||
{"pkg/lib_test.go#helper", "not inside a Test or Example function"},
|
||||
{"pkg/nope.go", "pkg/nope.go not found"},
|
||||
}
|
||||
var body strings.Builder
|
||||
lines := map[string]int{}
|
||||
line := 8 // frontmatter (6 lines), "# Snippets", blank
|
||||
for _, tc := range cases {
|
||||
body.WriteString("```go src=" + tc.src + "\n```\n\n")
|
||||
line++
|
||||
lines[tc.src] = line
|
||||
line += 2
|
||||
}
|
||||
root := snippetTree(t, map[string]string{
|
||||
"docs/setup/snippets.md": page("Snippets", "setup", 20, body.String()),
|
||||
"config/prod.env": "SECRET=1\n",
|
||||
})
|
||||
if err := os.Symlink(outside, filepath.Join(root, "escape.txt")); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
problems, err := Check(Options{Root: root})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
got := problemLines(problems)
|
||||
if len(got) != len(cases) {
|
||||
t.Errorf("got %d problems, want %d:\n%s", len(got), len(cases), strings.Join(got, "\n"))
|
||||
}
|
||||
for _, tc := range cases {
|
||||
prefix := "docs/setup/snippets.md:" + strconv.Itoa(lines[tc.src]) + ": snippet: "
|
||||
if !slices.ContainsFunc(got, func(g string) bool { return strings.HasPrefix(g, prefix) && strings.Contains(g, tc.want) }) {
|
||||
t.Errorf("src=%s: no problem %q...%q in\n%s", tc.src, prefix, tc.want, strings.Join(got, "\n"))
|
||||
}
|
||||
}
|
||||
if _, _, err := Build(Options{Root: root, Out: filepath.Join(t.TempDir(), "site")}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSyncRewritesDrift(t *testing.T) {
|
||||
doc := page("Start", "setup", 10, "Intro.\n\n- In a list:\n\n ```go src=pkg/lib.go#Greeting\n func stale() {}\n ```\n\n"+
|
||||
"```yaml src=config/app.yaml#db\ndb:\n host: localhost\n```\n\nOutro.\n")
|
||||
root := snippetTree(t, map[string]string{"docs/setup/start.md": doc})
|
||||
path := filepath.Join(root, "docs/setup/start.md")
|
||||
|
||||
problems, err := Check(Options{Root: root})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
want := "docs/setup/start.md:13: snippet: body differs from pkg/lib.go#Greeting (run: summer docs:sync)"
|
||||
if got := problemLines(problems); !slices.Equal(got, []string{want}) {
|
||||
t.Fatalf("problems = %q, want [%q]", got, want)
|
||||
}
|
||||
out := filepath.Join(t.TempDir(), "site")
|
||||
if _, problems, err := Build(Options{Root: root, Out: out}); err != nil || len(problems) != 1 {
|
||||
t.Fatalf("Build with drift: %v %v", err, problems)
|
||||
}
|
||||
if _, err := os.Stat(out); err == nil {
|
||||
t.Fatal("Build wrote output despite a drifted snippet")
|
||||
}
|
||||
|
||||
res, problems, err := Sync(Options{Root: root})
|
||||
if err != nil || len(problems) > 0 {
|
||||
t.Fatalf("Sync: %v %v", err, problems)
|
||||
}
|
||||
if res != (SyncResult{Snippets: 1, Files: 1}) {
|
||||
t.Fatalf("Sync = %+v, want 1 snippet in 1 file", res)
|
||||
}
|
||||
got, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
wantDoc := strings.Replace(doc, " func stale() {}\n",
|
||||
" // Greeting returns a greeting.\n func Greeting(name string) string {\n \treturn \"Hello, \" + name\n }\n", 1)
|
||||
if string(got) != wantDoc {
|
||||
t.Fatalf("synced file =\n%s\nwant\n%s", got, wantDoc)
|
||||
}
|
||||
if res, _, err := Sync(Options{Root: root}); err != nil || res != (SyncResult{}) {
|
||||
t.Fatalf("second Sync = %+v, %v; want up to date", res, err)
|
||||
}
|
||||
if problems, err := Check(Options{Root: root}); err != nil || len(problems) > 0 {
|
||||
t.Fatalf("Check after Sync: %v %q", err, problemLines(problems))
|
||||
}
|
||||
if _, problems, err := Build(Options{Root: root, Out: out}); err != nil || len(problems) > 0 {
|
||||
t.Fatalf("Build after Sync: %v %v", err, problems)
|
||||
}
|
||||
md, err := os.ReadFile(filepath.Join(out, "setup/start.md"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if strings.Contains(string(md), "src=") || !strings.Contains(string(md), " ```go\n") || !strings.Contains(string(md), "```yaml\n") {
|
||||
t.Errorf("start.md fences not reduced to the language word:\n%s", md)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user