summercms/cmd/summer/docs_test.go

package main

import (
	"bufio"
	"bytes"
	"io/fs"
	"os"
	"path/filepath"
	"regexp"
	"slices"
	"strings"
	"testing"

	"git.golem15.com/golem15/summercms/internal/docsite"
	"git.golem15.com/golem15/summercms/modules/bonfire"
)

const repoRoot = "../.."

// TestDocsTree fails with every problem line in the real docs tree.
func TestDocsTree(t *testing.T) {
	problems, err := docsite.Check(docsite.Options{Root: repoRoot})
	if err != nil {
		t.Fatal(err)
	}
	for _, p := range problems {
		t.Error(p.String())
	}
}

// buildRealTree runs docs:build on the real tree into a temp dir and returns
// the output dir and the command output.
func buildRealTree(t *testing.T) (string, string) {
	t.Helper()
	out := filepath.Join(t.TempDir(), "site")
	var buf bytes.Buffer
	root, err := bonfire.NewRoot("summer", toolCommands(), &buf)
	if err != nil {
		t.Fatal(err)
	}
	root.SetArgs([]string{"docs:build", "--root", repoRoot, "--out", out})
	if err := root.Execute(); err != nil {
		t.Fatalf("docs:build: %v\n%s", err, buf.String())
	}
	return out, buf.String()
}

func TestDocsBuildRealTree(t *testing.T) {
	out, stdout := buildRealTree(t)
	if !regexp.MustCompile(`docs:build: wrote \d+ pages to `).MatchString(stdout) {
		t.Fatalf("output = %q, want a wrote-pages line", stdout)
	}
	for _, name := range []string{
		"index.html", "index.md",
		"setup/installation.html", "setup/installation.md",
		"llms.txt", "llms-full.txt", "search-index.json",
		"assets/site.css", docsite.MarkerFile,
	} {
		if _, err := os.Stat(filepath.Join(out, name)); err != nil {
			t.Errorf("missing %s: %v", name, err)
		}
	}
}

// frameworkModules lists modules/<m> directories that hold a non-test Go
// file, discovered independently of docsite.
func frameworkModules(t *testing.T) []string {
	t.Helper()
	entries, err := os.ReadDir(filepath.Join(repoRoot, "modules"))
	if err != nil {
		t.Fatal(err)
	}
	var names []string
	for _, e := range entries {
		if !e.IsDir() {
			continue
		}
		goFiles, err := filepath.Glob(filepath.Join(repoRoot, "modules", e.Name(), "*.go"))
		if err != nil {
			t.Fatal(err)
		}
		if slices.ContainsFunc(goFiles, func(f string) bool { return !strings.HasSuffix(f, "_test.go") }) {
			names = append(names, e.Name())
		}
	}
	if len(names) == 0 {
		t.Fatal("no framework modules found")
	}
	return names
}

func TestEveryModuleInSidebar(t *testing.T) {
	out, _ := buildRealTree(t)
	index, err := os.ReadFile(filepath.Join(out, "index.html"))
	if err != nil {
		t.Fatal(err)
	}
	start := bytes.Index(index, []byte(`<nav class="sidebar" aria-label="Documentation">`))
	end := bytes.Index(index[max(start, 0):], []byte("</nav>"))
	if start < 0 || end < 0 {
		t.Fatal("index.html has no sidebar nav")
	}
	sidebar := string(index[start : start+end])
	for _, m := range frameworkModules(t) {
		if _, err := os.Stat(filepath.Join(out, "api", m+".html")); err != nil {
			t.Errorf("module %s has no API page: %v", m, err)
		}
		if !strings.Contains(sidebar, `href="/api/`+m+`.html"`) {
			t.Errorf("sidebar does not link api/%s.html", m)
		}
	}
}

// TestDocsAIOutputsInSync asserts that the page tree, the .html pages, the
// .md siblings, llms.txt and llms-full.txt all list the same pages in the
// same reading order.
func TestDocsAIOutputsInSync(t *testing.T) {
	pages, problems, err := docsite.Pages(docsite.Options{Root: repoRoot})
	if err != nil || len(problems) > 0 {
		t.Fatalf("Pages: %v %v", err, problems)
	}
	var want []string
	for _, p := range pages {
		want = append(want, p.URL)
	}
	out, _ := buildRealTree(t)

	var htmlFiles, mdFiles []string
	if err := filepath.WalkDir(out, func(p string, d fs.DirEntry, err error) error {
		if err != nil || d.IsDir() {
			return err
		}
		rel, _ := filepath.Rel(out, p)
		rel = filepath.ToSlash(rel)
		if strings.HasPrefix(rel, "assets/") {
			return nil
		}
		switch filepath.Ext(rel) {
		case ".html":
			htmlFiles = append(htmlFiles, strings.TrimSuffix(rel, ".html"))
		case ".md":
			mdFiles = append(mdFiles, strings.TrimSuffix(rel, ".md"))
		}
		return nil
	}); err != nil {
		t.Fatal(err)
	}
	sorted := slices.Sorted(slices.Values(want))
	slices.Sort(htmlFiles)
	slices.Sort(mdFiles)
	if !slices.Equal(htmlFiles, sorted) {
		t.Errorf(".html pages = %v, want %v", htmlFiles, sorted)
	}
	if !slices.Equal(mdFiles, sorted) {
		t.Errorf(".md pages = %v, want %v", mdFiles, sorted)
	}

	llms := readLines(t, filepath.Join(out, "llms.txt"))
	if len(llms) == 0 || llms[0] != "# SummerCMS" {
		t.Fatalf("llms.txt line 1 = %q, want # SummerCMS", first(llms))
	}
	if next := nextNonEmpty(llms, 1); next < 0 || !strings.HasPrefix(llms[next], "> ") {
		t.Errorf("llms.txt: the line after the H1 must be a > summary")
	}
	item := regexp.MustCompile(`^- \[[^\]]+\]\(/([^)]+)\.md\): \S`)
	var linked []string
	for i, line := range llms {
		if strings.HasPrefix(line, "## ") {
			if next := nextNonEmpty(llms, i+1); next < 0 || !strings.HasPrefix(llms[next], "- [") {
				t.Errorf("llms.txt: %q is not followed by a link list", line)
			}
		}
		if m := item.FindStringSubmatch(line); m != nil {
			linked = append(linked, m[1])
		}
	}
	if !slices.Equal(linked, want) {
		t.Errorf("llms.txt links = %v, want %v", linked, want)
	}

	var sources []string
	for _, line := range readLines(t, filepath.Join(out, "llms-full.txt")) {
		if rest, ok := strings.CutPrefix(line, "Source: /"); ok {
			sources = append(sources, strings.TrimSuffix(rest, ".html"))
		}
	}
	if !slices.Equal(sources, want) {
		t.Errorf("llms-full.txt sources = %v, want %v", sources, want)
	}
}

func readLines(t *testing.T, path string) []string {
	t.Helper()
	f, err := os.Open(path)
	if err != nil {
		t.Fatal(err)
	}
	defer f.Close()
	var lines []string
	sc := bufio.NewScanner(f)
	sc.Buffer(make([]byte, 0, 1<<20), 1<<24)
	for sc.Scan() {
		lines = append(lines, sc.Text())
	}
	if err := sc.Err(); err != nil {
		t.Fatal(err)
	}
	return lines
}

func nextNonEmpty(lines []string, from int) int {
	for i := from; i < len(lines); i++ {
		if strings.TrimSpace(lines[i]) != "" {
			return i
		}
	}
	return -1
}

func first(lines []string) string {
	if len(lines) == 0 {
		return ""
	}
	return lines[0]
}