Files
archie/tools/docsgen/main_test.go
T
sam 34c436fa99 build(tools): lint the tools module in the gate
golangci-lint ran ./... from the repository root, which stops at the root
module, so the tools module was never linted and had drifted unseen. task
check already closes this hole for tests with test:tools; lint now has the
same shape in lint:tools, which runs in the tools directory rather than
passing a path prefix that only rewrites output paths.

Fixes the six issues that had accumulated behind it:

stripJSComments was 21 cyclomatic complexity against a cap of 15, with the
comment-skipping and literal-copying loops inlined into one scanner. It is
four named functions now, and the De Morgan warning went with the rewrite. It
had no test despite deciding whether a commented-out call reads as a live
consumer, so it has one: literals that look like comments, comment markers
inside strings, escapes, and unterminated literals and block comments.

docsgen's missing-artifact error ended in punctuation, and three test type
assertions were unchecked, which panic rather than fail when the generated
artifact does not have the shape the case assumes.
2026-09-22 00:26:18 +10:00

519 lines
14 KiB
Go

package main
import (
"bytes"
"encoding/json"
"os"
"path/filepath"
"reflect"
"strings"
"testing"
"github.com/invopop/jsonschema"
)
type contractWithConflictingDefinition struct {
Value conflictingDefinition `json:"value"`
}
type conflictingDefinition struct {
Value string `json:"value"`
}
func TestRunWritesDeterministicContractData(t *testing.T) {
repoRoot := filepath.Clean("../..")
outputDir := t.TempDir()
outputs := []string{
filepath.Join(outputDir, "first.json"),
filepath.Join(outputDir, "second.json"),
}
for _, output := range outputs {
if err := run(repoRoot, output); err != nil {
t.Fatalf("run(%q) error = %v", output, err)
}
}
first, err := os.ReadFile(outputs[0])
if err != nil {
t.Fatalf("read first output: %v", err)
}
second, err := os.ReadFile(outputs[1])
if err != nil {
t.Fatalf("read second output: %v", err)
}
if !bytes.Equal(first, second) {
t.Fatal("repeated generation produced different bytes")
}
var data struct {
GeneratedBy string `json:"generatedBy"`
Schemas map[string]json.RawMessage `json:"schemas"`
}
if err := json.Unmarshal(first, &data); err != nil {
t.Fatalf("decode generated data: %v", err)
}
if data.GeneratedBy != "tools/docsgen" {
t.Fatalf("generatedBy = %q, want %q", data.GeneratedBy, "tools/docsgen")
}
for _, name := range []string{
"AgentExecutionRequest",
"AgentExecutionResult",
"MessageEvent",
} {
if _, ok := data.Schemas[name]; !ok {
t.Errorf("schemas[%q] is missing", name)
}
}
for name, schema := range data.Schemas {
assertSchemaRefsResolve(t, name, schema, data.Schemas)
}
}
func TestRunHonoursAbsoluteOutputPath(t *testing.T) {
repoRoot := filepath.Clean("../..")
outputDir := t.TempDir()
originalDir, err := os.Getwd()
if err != nil {
t.Fatalf("get working directory: %v", err)
}
for _, name := range []string{"first.yaml", "second.yaml"} {
output := filepath.Join(outputDir, name)
if err := run(repoRoot, output); err != nil {
t.Fatalf("run(%q) error = %v", name, err)
}
if _, err := os.Stat(output); err != nil {
t.Fatalf("generated output %q: %v", name, err)
}
}
currentDir, err := os.Getwd()
if err != nil {
t.Fatalf("get restored working directory: %v", err)
}
if currentDir != originalDir {
t.Fatalf("working directory = %q, want %q", currentDir, originalDir)
}
}
func TestCollectSchemaRejectsDuplicatePublishedName(t *testing.T) {
reflector := &jsonschema.Reflector{ExpandedStruct: true}
schemas := map[string]any{}
const name = "PublishedContract"
if err := collectSchema(reflector, schemas, name, reflect.TypeFor[struct {
First string `json:"first"`
}]()); err != nil {
t.Fatalf("collect first schema: %v", err)
}
err := collectSchema(reflector, schemas, name, reflect.TypeFor[struct {
Second int `json:"second"`
}]())
if err == nil {
t.Fatal("collect duplicate schema returned nil error")
}
}
func TestCollectSchemaRejectsConflictingDefinition(t *testing.T) {
reflector := &jsonschema.Reflector{ExpandedStruct: true}
schemas := map[string]any{
"conflictingDefinition": map[string]any{"type": "integer"},
}
err := collectSchema(
reflector,
schemas,
"PublishedContract",
reflect.TypeFor[contractWithConflictingDefinition](),
)
if err == nil {
t.Fatal("collect conflicting definition returned nil error")
}
if !strings.Contains(err.Error(), `conflicting schema definition "conflictingDefinition"`) {
t.Fatalf("collect conflicting definition error = %q", err)
}
}
func TestRunReportsFilesystemAndSourceErrors(t *testing.T) {
repoRoot := filepath.Clean("../..")
blocker := filepath.Join(t.TempDir(), "file")
if err := os.WriteFile(blocker, []byte("occupied"), 0o600); err != nil {
t.Fatalf("create blocker: %v", err)
}
tests := []struct {
name string
root string
output string
contains string
}{
{
name: "missing source tree",
root: t.TempDir(),
output: filepath.Join(t.TempDir(), "contracts.json"),
contains: "load Go comments",
},
{
name: "output parent is a file",
root: repoRoot,
output: filepath.Join(blocker, "contracts.json"),
contains: "create output directory",
},
{
name: "output is a directory",
root: repoRoot,
output: t.TempDir(),
contains: "write ",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
err := run(test.root, test.output)
if err == nil {
t.Fatal("run() returned nil error")
}
if !bytes.Contains([]byte(err.Error()), []byte(test.contains)) {
t.Fatalf("run() error = %q, want substring %q", err, test.contains)
}
})
}
}
func TestCheckAcceptsTheCommittedArtifact(t *testing.T) {
repoRoot := filepath.Clean("../..")
if err := check(repoRoot, defaultOutputPath); err != nil {
t.Fatalf("check(%q) error = %v; committed generated data is stale", defaultOutputPath, err)
}
}
func TestCheckReportsChangedSchema(t *testing.T) {
repoRoot := filepath.Clean("../..")
output := filepath.Join(t.TempDir(), "contracts.json")
if err := run(repoRoot, output); err != nil {
t.Fatalf("run() error = %v", err)
}
mutateGeneratedData(t, output, func(data map[string]any) {
schemas := mapAt(t, data, "schemas")
mapAt(t, schemas, "AgentExecutionResult")["title"] = "tampered"
})
err := check(repoRoot, output)
if err == nil {
t.Fatal("check() returned nil error for a changed artifact")
}
for _, want := range []string{"changed", "AgentExecutionResult", "agentexec.Result"} {
if !strings.Contains(err.Error(), want) {
t.Errorf("check() error = %q, want substring %q", err, want)
}
}
}
func TestCheckReportsRemovedSchema(t *testing.T) {
repoRoot := filepath.Clean("../..")
output := filepath.Join(t.TempDir(), "contracts.json")
if err := run(repoRoot, output); err != nil {
t.Fatalf("run() error = %v", err)
}
mutateGeneratedData(t, output, func(data map[string]any) {
delete(mapAt(t, data, "schemas"), "MessageEvent")
})
err := check(repoRoot, output)
if err == nil {
t.Fatal("check() returned nil error for a removed schema")
}
if !strings.Contains(err.Error(), "MessageEvent") {
t.Errorf("check() error = %q, want the removed schema named", err)
}
}
func TestCheckReportsMissingArtifact(t *testing.T) {
repoRoot := filepath.Clean("../..")
output := filepath.Join(t.TempDir(), "contracts.json")
err := check(repoRoot, output)
if err == nil {
t.Fatal("check() returned nil error for a missing artifact")
}
if !strings.Contains(err.Error(), "missing") {
t.Fatalf("check() error = %q, want it to report a missing artifact", err)
}
if _, statErr := os.Stat(output); statErr == nil {
t.Fatal("check() created the missing artifact instead of reporting it")
}
}
func TestParseOptions(t *testing.T) {
tests := []struct {
name string
args []string
wantMode mode
wantOut string
wantErr string
}{
{name: "write by default", wantMode: modeWrite, wantOut: defaultOutputPath},
{name: "check first", args: []string{"check"}, wantMode: modeCheck, wantOut: defaultOutputPath},
{
name: "check with flags",
args: []string{"check", "--repo-root", ".."},
wantMode: modeCheck,
wantOut: defaultOutputPath,
},
{
name: "check honours out",
args: []string{"check", "--out", "/tmp/artifacts.json"},
wantMode: modeCheck,
wantOut: "/tmp/artifacts.json",
},
{
name: "check after flags would otherwise silently write",
args: []string{"--repo-root", "..", "check"},
wantErr: "unexpected argument",
},
{name: "misspelled subcommand", args: []string{"chekc"}, wantErr: "unexpected argument"},
{
name: "stray trailing argument",
args: []string{"--out", "/tmp/artifacts.json", "stray"},
wantErr: "unexpected argument",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
got, err := parseOptions(test.args)
if test.wantErr != "" {
if err == nil {
t.Fatalf("parseOptions(%q) returned nil error, want %q", test.args, test.wantErr)
}
if !strings.Contains(err.Error(), test.wantErr) {
t.Fatalf("parseOptions(%q) error = %q, want substring %q", test.args, err, test.wantErr)
}
return
}
if err != nil {
t.Fatalf("parseOptions(%q) error = %v", test.args, err)
}
if got.mode != test.wantMode {
t.Errorf("parseOptions(%q).mode = %v, want %v", test.args, got.mode, test.wantMode)
}
if got.out != test.wantOut {
t.Errorf("parseOptions(%q).out = %q, want %q", test.args, got.out, test.wantOut)
}
})
}
}
func TestSchemaProvenanceFollowsNestedDefinitions(t *testing.T) {
schemas := map[string]any{
"Root": map[string]any{
"properties": map[string]any{
"middle": map[string]any{"$ref": "#/schemas/Middle"},
},
},
"Middle": map[string]any{
"properties": map[string]any{
"leaf": map[string]any{"$ref": "#/schemas/Leaf"},
},
},
"Leaf": map[string]any{"type": "string"},
}
provenance := schemaProvenance(schemas, map[string]string{"Root": "example.Root"})
if got := provenance["Root"]; got != "example.Root" {
t.Errorf("provenance[Root] = %q, want the root definition", got)
}
if got := provenance["Middle"]; got != "reached from example.Root" {
t.Errorf("provenance[Middle] = %q, want it reached from the root", got)
}
// Leaf is reachable only through Middle. A one-level walk misses it, and the
// report then claims no authoritative definition exists.
if got := provenance["Leaf"]; got != "reached from example.Root" {
t.Errorf("provenance[Leaf] = %q, want it reached from the root transitively", got)
}
}
func TestObsoleteArtifactsReportsUnownedFileInAnOwnedDirectory(t *testing.T) {
root := t.TempDir()
dir := filepath.Join(root, "docs", "data", "generated")
if err := os.MkdirAll(dir, 0o755); err != nil {
t.Fatalf("create generated dir: %v", err)
}
for name, body := range map[string]string{
"contracts.json": "{}\n", // owned
"orphaned.json": "{}\n", // obsolete
"notes.txt": "not json\n",
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o600); err != nil {
t.Fatalf("write %s: %v", name, err)
}
}
problems := obsoleteArtifacts(root, dir)
if len(problems) != 1 {
t.Fatalf("obsoleteArtifacts() = %q, want exactly the orphan", problems)
}
if !strings.Contains(problems[0], "orphaned.json") || !strings.Contains(problems[0], "obsolete") {
t.Fatalf("obsoleteArtifacts() = %q, want the orphan named", problems)
}
}
func TestObsoleteArtifactsNeverJudgesAnUnownedDirectory(t *testing.T) {
root := t.TempDir()
// An arbitrary --out location: the JSON beside the artifact belongs to
// whoever put it there, and docsgen must not claim it as its own.
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "someone-elses.json"), []byte("{}\n"), 0o600); err != nil {
t.Fatalf("write foreign json: %v", err)
}
if problems := obsoleteArtifacts(root, dir); len(problems) != 0 {
t.Fatalf("obsoleteArtifacts() = %q, want none for an unowned directory", problems)
}
}
func TestCheckNeverModifiesTheWorkingTree(t *testing.T) {
repoRoot := filepath.Clean("../..")
outputDir := t.TempDir()
output := filepath.Join(outputDir, "contracts.json")
if err := run(repoRoot, output); err != nil {
t.Fatalf("run() error = %v", err)
}
mutateGeneratedData(t, output, func(data map[string]any) {
data["generatedBy"] = "tampered"
})
before, err := os.ReadFile(output)
if err != nil {
t.Fatalf("read before: %v", err)
}
beforeInfo, err := os.Stat(output)
if err != nil {
t.Fatalf("stat before: %v", err)
}
if err := check(repoRoot, output); err == nil {
t.Fatal("check() returned nil error for a changed artifact")
}
after, err := os.ReadFile(output)
if err != nil {
t.Fatalf("read after: %v", err)
}
if !bytes.Equal(before, after) {
t.Fatal("check() rewrote the artifact under test")
}
afterInfo, err := os.Stat(output)
if err != nil {
t.Fatalf("stat after: %v", err)
}
if beforeInfo.Mode() != afterInfo.Mode() {
t.Fatalf("check() changed the artifact mode: %v -> %v", beforeInfo.Mode(), afterInfo.Mode())
}
if entries, err := os.ReadDir(outputDir); err != nil {
t.Fatalf("read output dir: %v", err)
} else if len(entries) != 1 {
t.Fatalf("check() left %d files in the output dir, want 1", len(entries))
}
}
func mutateGeneratedData(t *testing.T, path string, mutate func(map[string]any)) {
t.Helper()
raw, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read %s: %v", path, err)
}
var data map[string]any
if err := json.Unmarshal(raw, &data); err != nil {
t.Fatalf("decode %s: %v", path, err)
}
mutate(data)
body, err := json.MarshalIndent(data, "", " ")
if err != nil {
t.Fatalf("encode %s: %v", path, err)
}
if err := os.WriteFile(path, append(body, '\n'), 0o600); err != nil {
t.Fatalf("write %s: %v", path, err)
}
}
func TestRewriteRef(t *testing.T) {
tests := map[string]string{
"definition": "#/schemas/Contract",
"external": "https://example.com/schema.json",
"empty name": "#/$defs/",
}
for name, want := range tests {
t.Run(name, func(t *testing.T) {
input := want
if name == "definition" {
input = "#/$defs/Contract"
}
if got := rewriteRef(input); got != want {
t.Fatalf("rewriteRef(%q) = %q, want %q", input, got, want)
}
})
}
}
func assertSchemaRefsResolve(
t *testing.T,
name string,
raw json.RawMessage,
schemas map[string]json.RawMessage,
) {
t.Helper()
var value any
if err := json.Unmarshal(raw, &value); err != nil {
t.Fatalf("decode schema %q: %v", name, err)
}
walkJSON(value, func(ref string) {
const prefix = "#/schemas/"
if !strings.HasPrefix(ref, "#") {
return
}
if !strings.HasPrefix(ref, prefix) {
t.Errorf("schema %q contains unresolved local reference %q", name, ref)
return
}
target := ref[len(prefix):]
if _, ok := schemas[target]; !ok {
t.Errorf("schema %q references missing schema %q", name, target)
}
})
}
func walkJSON(value any, visitRef func(string)) {
switch node := value.(type) {
case map[string]any:
for key, child := range node {
if key == "$ref" {
if ref, ok := child.(string); ok {
visitRef(ref)
}
continue
}
walkJSON(child, visitRef)
}
case []any:
for _, child := range node {
walkJSON(child, visitRef)
}
}
}
// mapAt returns the nested object at key, failing the test rather than panicking
// when the generated artifact does not have the shape the case assumes.
func mapAt(t *testing.T, parent map[string]any, key string) map[string]any {
t.Helper()
child, ok := parent[key].(map[string]any)
if !ok {
t.Fatalf("%s is %T, want an object", key, parent[key])
}
return child
}