fix(docsgen): address three review findings on the check mode
All three Greptile findings were valid against the code; each is fixed at its cause rather than at the symptom, and each fix is covered by a test that fails when the fix is reverted. **Check could silently write.** `check` was matched only as the first argument, and leftover positional arguments were never inspected. So `docsgen --repo-root .. check` — and any misspelled subcommand — fell through to the write path and overwrote the artifact the check promises not to touch. That is the exact guarantee the mode exists to provide, so the failure was silent and in the wrong direction. Extracted argument handling into a testable `parseOptions` and made a leftover positional argument an error with usage text. Switched the flag set from `ExitOnError` to `ContinueOnError` so the error surfaces as a value rather than a process exit, which is what makes it testable. **Obsolete detection claimed files it does not own.** It treated every sibling `.json` as docsgen's and reported it obsolete, so checking an artifact in a mixed-use directory produced a false stale result, and the documented target layout — which anticipates further named artifacts in `docs/data/generated/` (catalog.json, AsyncAPI output) — would have been reported stale as soon as a second artifact legitimately existed. Ownership is now declared rather than inferred: `generatedArtifacts` maps each directory docsgen owns end-to-end to the names it produces there, and a directory docsgen does not own is never judged. A new unit test pins both halves — the orphan inside an owned directory is still caught, and a foreign `.json` in an arbitrary `--out` directory is not. **Provenance traversal stopped at one level.** Refs were walked only inside the top-level contract schemas, so a definition reachable solely through another definition resolved to "no authoritative definition found" — the diagnostic lying about the code it points at. Replaced the single pass with a breadth-first walk that follows discovered definitions transitively, seeded with every published contract first so a definition reachable from several contracts is attributed to the alphabetically first rather than to whichever the walk happened to reach. `walkSchemaRefs` now iterates map keys in sorted order for the same reason. `schemaProvenance` takes its roots as a parameter, which is what makes the transitive case testable without real types. Verified by mutation: with each fix reverted in turn, its test fails — `parseOptions(["--repo-root" ".." "check"]) returned nil error`, `obsoleteArtifacts() = [...someone-elses.json is obsolete...]`, and `provenance[Leaf] = ""`. Control run passes unmutated, and the file is byte-identical after restoration. Also confirmed end to end that the previously silent invocation now exits non-zero with usage instead of writing, and that the committed artifact is untouched by it. `task check`: exit 0, 0 failures.
This commit is contained in:
1 parent
52aa774afc
commit
2825b82a80
2 files changed
+266
-58
No files matched your search
+143
-44
@@ -7,6 +7,7 @@ import (
|
||||
"errors"
|
||||
"flag"
|
||||
"fmt"
|
||||
"io"
|
||||
"io/fs"
|
||||
"log"
|
||||
"os"
|
||||
@@ -32,17 +33,52 @@ const (
|
||||
modeCheck
|
||||
)
|
||||
|
||||
// generatedArtifacts declares the directories docsgen owns end-to-end, and the
|
||||
// file names it produces in each. Obsolete detection is scoped to these
|
||||
// directories: an arbitrary --out location is not ours to judge, and the target
|
||||
// layout anticipates further named artifacts here (catalog.json, AsyncAPI
|
||||
// output), which must not be reported as stale merely for existing.
|
||||
var generatedArtifacts = map[string][]string{
|
||||
"docs/data/generated": {"contracts.json"},
|
||||
}
|
||||
|
||||
// options is a parsed command line.
|
||||
type options struct {
|
||||
mode mode
|
||||
repoRoot string
|
||||
out string
|
||||
}
|
||||
|
||||
func main() {
|
||||
args := os.Args[1:]
|
||||
parsed, err := parseOptions(os.Args[1:])
|
||||
if err != nil {
|
||||
log.Fatalf("docsgen: %v", err)
|
||||
}
|
||||
|
||||
if parsed.mode == modeCheck {
|
||||
err = check(parsed.repoRoot, parsed.out)
|
||||
} else {
|
||||
err = run(parsed.repoRoot, parsed.out)
|
||||
}
|
||||
if err != nil {
|
||||
log.Fatalf("docsgen: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// parseOptions resolves the optional `check` subcommand and the flags that
|
||||
// follow it. A leftover positional argument is an error rather than something
|
||||
// to ignore: `docsgen --repo-root .. check` would otherwise quietly fall through
|
||||
// to the write path and overwrite the artifact that check promises not to
|
||||
// touch, and a misspelled subcommand would do the same silently.
|
||||
func parseOptions(args []string) (options, error) {
|
||||
selected := modeWrite
|
||||
// `check` is a subcommand, not a flag: it selects a comparison instead of a
|
||||
// write, and the flag package would treat it as a positional argument.
|
||||
if len(args) > 0 && args[0] == "check" {
|
||||
selected = modeCheck
|
||||
args = args[1:]
|
||||
}
|
||||
|
||||
flags := flag.NewFlagSet("docsgen", flag.ExitOnError)
|
||||
flags := flag.NewFlagSet("docsgen", flag.ContinueOnError)
|
||||
flags.SetOutput(io.Discard)
|
||||
repoRoot := flags.String("repo-root", "..", "path to the Archie repository root")
|
||||
out := flags.String(
|
||||
"out",
|
||||
@@ -50,18 +86,17 @@ func main() {
|
||||
"output path relative to the repository root",
|
||||
)
|
||||
if err := flags.Parse(args); err != nil {
|
||||
log.Fatalf("docsgen: %v", err)
|
||||
return options{}, err
|
||||
}
|
||||
if extra := flags.Args(); len(extra) > 0 {
|
||||
return options{}, fmt.Errorf(
|
||||
"unexpected argument %q; usage: docsgen [check] [--repo-root DIR] [--out PATH] "+
|
||||
"(`check` must come first)",
|
||||
extra[0],
|
||||
)
|
||||
}
|
||||
|
||||
var err error
|
||||
if selected == modeCheck {
|
||||
err = check(*repoRoot, *out)
|
||||
} else {
|
||||
err = run(*repoRoot, *out)
|
||||
}
|
||||
if err != nil {
|
||||
log.Fatalf("docsgen: %v", err)
|
||||
}
|
||||
return options{mode: selected, repoRoot: *repoRoot, out: *out}, nil
|
||||
}
|
||||
|
||||
// check regenerates the artifact into a temporary directory and compares it
|
||||
@@ -109,7 +144,7 @@ func check(repoRoot, outPath string) error {
|
||||
}
|
||||
|
||||
problems := compareArtifacts(relative, expected, committed)
|
||||
problems = append(problems, obsoleteArtifacts(absRoot, committedPath)...)
|
||||
problems = append(problems, obsoleteArtifacts(absRoot, filepath.Dir(committedPath))...)
|
||||
if len(problems) == 0 {
|
||||
fmt.Printf("docsgen: %s is up to date\n", relative)
|
||||
return nil
|
||||
@@ -135,7 +170,7 @@ func compareArtifacts(relative string, expected, committed []byte) []string {
|
||||
return []string{fmt.Sprintf("%s: committed output is unreadable: %v", relative, err)}
|
||||
}
|
||||
|
||||
provenance := schemaProvenance(expectedSchemas)
|
||||
provenance := schemaProvenance(expectedSchemas, contractRoots())
|
||||
var problems []string
|
||||
for _, name := range sortedSchemaNames(expectedSchemas) {
|
||||
committedSchema, ok := committedSchemas[name]
|
||||
@@ -168,60 +203,105 @@ func compareArtifacts(relative string, expected, committed []byte) []string {
|
||||
}
|
||||
|
||||
// obsoleteArtifacts reports committed generated files in the artifact's
|
||||
// directory that the generator no longer produces, so a renamed or deleted
|
||||
// artifact cannot linger as dead documentation.
|
||||
func obsoleteArtifacts(absRoot, committedPath string) []string {
|
||||
entries, err := os.ReadDir(filepath.Dir(committedPath))
|
||||
// obsoleteArtifacts reports files present in a directory docsgen owns that the
|
||||
// generator no longer produces, so a renamed or deleted artifact cannot linger
|
||||
// as dead documentation. A directory docsgen does not own is never judged: its
|
||||
// JSON belongs to someone else.
|
||||
func obsoleteArtifacts(absRoot, dir string) []string {
|
||||
owned, ours := ownedArtifacts(absRoot, dir)
|
||||
if !ours {
|
||||
return nil
|
||||
}
|
||||
entries, err := os.ReadDir(dir)
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
owned := filepath.Base(committedPath)
|
||||
var problems []string
|
||||
for _, entry := range entries {
|
||||
if entry.IsDir() || entry.Name() == owned {
|
||||
if entry.IsDir() || owned[entry.Name()] {
|
||||
continue
|
||||
}
|
||||
if filepath.Ext(entry.Name()) != ".json" {
|
||||
continue
|
||||
}
|
||||
full := filepath.Join(filepath.Dir(committedPath), entry.Name())
|
||||
problems = append(problems, fmt.Sprintf(
|
||||
"%s is obsolete: no generator in tools/docsgen produces it",
|
||||
displayPath(absRoot, full),
|
||||
displayPath(absRoot, filepath.Join(dir, entry.Name())),
|
||||
))
|
||||
}
|
||||
return problems
|
||||
}
|
||||
|
||||
// ownedArtifacts reports which file names docsgen owns in dir, and whether dir
|
||||
// is one docsgen owns at all.
|
||||
func ownedArtifacts(absRoot, dir string) (map[string]bool, bool) {
|
||||
relative, err := filepath.Rel(absRoot, dir)
|
||||
if err != nil {
|
||||
return nil, false
|
||||
}
|
||||
names, ours := generatedArtifacts[filepath.ToSlash(relative)]
|
||||
if !ours {
|
||||
return nil, false
|
||||
}
|
||||
owned := make(map[string]bool, len(names))
|
||||
for _, name := range names {
|
||||
owned[name] = true
|
||||
}
|
||||
return owned, true
|
||||
}
|
||||
|
||||
// schemaProvenance names the authoritative Go definition behind each published
|
||||
// schema, so a drift report points at the code that must be reviewed rather
|
||||
// than only at the generated file.
|
||||
func schemaProvenance(schemas map[string]any) map[string]string {
|
||||
provenance := map[string]string{}
|
||||
types := currentContractTypes()
|
||||
names := make([]string, 0, len(types))
|
||||
for name := range types {
|
||||
names = append(names, name)
|
||||
// than only at the generated file. roots maps each published contract to its
|
||||
// Go definition; every other schema is attributed to the contract that pulled
|
||||
// it in, transitively, because a definition reachable only through another
|
||||
// definition still belongs to the contract that caused it to be published.
|
||||
func schemaProvenance(schemas map[string]any, roots map[string]string) map[string]string {
|
||||
// attribution maps each schema to the published contract it came in under.
|
||||
attribution := make(map[string]string, len(roots))
|
||||
queue := make([]string, 0, len(roots))
|
||||
for _, name := range sortedStringKeys(roots) {
|
||||
attribution[name] = name
|
||||
queue = append(queue, name)
|
||||
}
|
||||
// Sorted: a nested definition referenced by several contracts would
|
||||
// otherwise be attributed to whichever contract map iteration reached
|
||||
// first, making the diagnostic nondeterministic.
|
||||
sort.Strings(names)
|
||||
for _, name := range names {
|
||||
t := types[name]
|
||||
provenance[name] = t.PkgPath() + "." + t.Name()
|
||||
}
|
||||
for _, name := range names {
|
||||
walkSchemaRefs(schemas[name], func(target string) {
|
||||
if _, known := provenance[target]; known {
|
||||
|
||||
// Breadth-first, seeded with every contract before any nested definition is
|
||||
// followed, so a definition reachable from several contracts is attributed
|
||||
// to the alphabetically first of them rather than to whichever the walk
|
||||
// happened to reach.
|
||||
for len(queue) > 0 {
|
||||
current := queue[0]
|
||||
queue = queue[1:]
|
||||
root := attribution[current]
|
||||
walkSchemaRefs(schemas[current], func(target string) {
|
||||
if _, known := attribution[target]; known {
|
||||
return
|
||||
}
|
||||
provenance[target] = "reached from " + provenance[name]
|
||||
attribution[target] = root
|
||||
queue = append(queue, target)
|
||||
})
|
||||
}
|
||||
|
||||
provenance := make(map[string]string, len(attribution))
|
||||
for name, root := range attribution {
|
||||
if source, isRoot := roots[name]; isRoot {
|
||||
provenance[name] = source
|
||||
continue
|
||||
}
|
||||
provenance[name] = "reached from " + roots[root]
|
||||
}
|
||||
return provenance
|
||||
}
|
||||
|
||||
func sortedStringKeys(values map[string]string) []string {
|
||||
keys := make([]string, 0, len(values))
|
||||
for key := range values {
|
||||
keys = append(keys, key)
|
||||
}
|
||||
sort.Strings(keys)
|
||||
return keys
|
||||
}
|
||||
|
||||
func describeProvenance(provenance map[string]string, name string) string {
|
||||
if source, ok := provenance[name]; ok {
|
||||
return "authoritative definition: " + source
|
||||
@@ -229,10 +309,29 @@ func describeProvenance(provenance map[string]string, name string) string {
|
||||
return "no authoritative definition found"
|
||||
}
|
||||
|
||||
// contractRoots labels each published contract with the Go definition it comes
|
||||
// from, which is what makes a drift report name code rather than a file.
|
||||
func contractRoots() map[string]string {
|
||||
types := currentContractTypes()
|
||||
roots := make(map[string]string, len(types))
|
||||
for name, t := range types {
|
||||
roots[name] = t.PkgPath() + "." + t.Name()
|
||||
}
|
||||
return roots
|
||||
}
|
||||
|
||||
func walkSchemaRefs(value any, visit func(target string)) {
|
||||
switch node := value.(type) {
|
||||
case map[string]any:
|
||||
for key, child := range node {
|
||||
// Sorted so a schema reachable by more than one path is visited in the
|
||||
// same order every run; provenance must not depend on map iteration.
|
||||
keys := make([]string, 0, len(node))
|
||||
for key := range node {
|
||||
keys = append(keys, key)
|
||||
}
|
||||
sort.Strings(keys)
|
||||
for _, key := range keys {
|
||||
child := node[key]
|
||||
if key == "$ref" {
|
||||
if ref, ok := child.(string); ok {
|
||||
if target, found := strings.CutPrefix(ref, "#/schemas/"); found {
|
||||
|
||||
+123
-14
@@ -245,23 +245,132 @@ func TestCheckReportsMissingArtifact(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestCheckReportsObsoleteArtifact(t *testing.T) {
|
||||
repoRoot := filepath.Clean("../..")
|
||||
outputDir := t.TempDir()
|
||||
if err := run(repoRoot, filepath.Join(outputDir, "contracts.json")); err != nil {
|
||||
t.Fatalf("run() error = %v", err)
|
||||
}
|
||||
obsolete := filepath.Join(outputDir, "orphaned.json")
|
||||
if err := os.WriteFile(obsolete, []byte("{}\n"), 0o600); err != nil {
|
||||
t.Fatalf("write obsolete artifact: %v", err)
|
||||
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",
|
||||
},
|
||||
}
|
||||
|
||||
err := check(repoRoot, filepath.Join(outputDir, "contracts.json"))
|
||||
if err == nil {
|
||||
t.Fatal("check() returned nil error for an obsolete artifact")
|
||||
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)
|
||||
}
|
||||
})
|
||||
}
|
||||
if !strings.Contains(err.Error(), "obsolete") || !strings.Contains(err.Error(), "orphaned.json") {
|
||||
t.Fatalf("check() error = %q, want the obsolete file named", err)
|
||||
}
|
||||
|
||||
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)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user