// Command docsgen generates reference schemas from Archie-owned Go contracts. package main import ( "bytes" "encoding/json" "errors" "flag" "fmt" "io" "io/fs" "log" "os" "path/filepath" "reflect" "sort" "strings" "github.com/invopop/jsonschema" "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/gateway" ) // defaultOutputPath is the committed artifact docsgen owns, relative to the // repository root. const defaultOutputPath = "docs/data/generated/contracts.json" type mode int const ( modeWrite mode = iota modeCheck ) // generatedArtifacts declares the directories whose contents are generated // end-to-end, and every file name accounted for 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. // // docs/data/generated is shared. docsgen writes contracts.json from the // Go contract types; tools/docsite writes docs.json and dev-docs.json from the // Markdown sources, one per published set. Each tool verifies its OWN files, and // all three are named here because this map is the directory's ownership record: // whichever tool runs first must not report the others' artifacts as unaccounted // files. docsgen does not verify the docsite artifacts, and tools/docsite keeps no // registry of its own for that reason -- one fact, one home. var generatedArtifacts = map[string][]string{ "docs/data/generated": {"contracts.json", "docs.json", "dev-docs.json"}, } // options is a parsed command line. type options struct { mode mode repoRoot string out string } func main() { 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 if len(args) > 0 && args[0] == "check" { selected = modeCheck args = args[1:] } 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", defaultOutputPath, "output path relative to the repository root", ) if err := flags.Parse(args); err != nil { 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], ) } return options{mode: selected, repoRoot: *repoRoot, out: *out}, nil } // check regenerates the artifact into a temporary directory and compares it // with the committed output. It never writes to the working tree, so a failing // check leaves the tree exactly as it found it -- the author, not the gate, // applies the regenerated bytes. func check(repoRoot, outPath string) error { absRoot, err := filepath.Abs(repoRoot) if err != nil { return fmt.Errorf("resolve repository root: %w", err) } committedPath := outPath if !filepath.IsAbs(committedPath) { committedPath = filepath.Join(absRoot, committedPath) } relative := displayPath(absRoot, committedPath) tmpDir, err := os.MkdirTemp("", "docsgen-check-") if err != nil { return fmt.Errorf("create temporary directory: %w", err) } defer func() { _ = os.RemoveAll(tmpDir) }() // Reuse the write path so check and generate can never disagree about // what the committed bytes should be. generatedPath := filepath.Join(tmpDir, filepath.Base(committedPath)) if err := write(absRoot, generatedPath, true); err != nil { return err } expected, err := os.ReadFile(generatedPath) if err != nil { return fmt.Errorf("read generated artifact: %w", err) } committed, err := os.ReadFile(committedPath) if errors.Is(err, fs.ErrNotExist) { return fmt.Errorf( "%s is missing; regenerate it by running `go -C tools run ./docsgen --repo-root ..` from the tools module", relative, ) } if err != nil { return fmt.Errorf("read %s: %w", relative, err) } problems := compareArtifacts(relative, expected, committed) problems = append(problems, obsoleteArtifacts(absRoot, filepath.Dir(committedPath))...) if len(problems) == 0 { fmt.Printf("docsgen: %s is up to date\n", relative) return nil } return fmt.Errorf( "%s is stale; regenerate it with: go -C tools run ./docsgen --repo-root ..\n %s", relative, strings.Join(problems, "\n "), ) } // compareArtifacts reports every schema whose generated form differs from the // committed form, plus a whole-file difference the schema view cannot see // (whitespace or key ordering). func compareArtifacts(relative string, expected, committed []byte) []string { expectedSchemas, err := decodeSchemas(expected) if err != nil { return []string{fmt.Sprintf("%s: generated output is unreadable: %v", relative, err)} } committedSchemas, err := decodeSchemas(committed) if err != nil { return []string{fmt.Sprintf("%s: committed output is unreadable: %v", relative, err)} } provenance := schemaProvenance(expectedSchemas, contractRoots()) var problems []string for _, name := range sortedSchemaNames(expectedSchemas) { committedSchema, ok := committedSchemas[name] if !ok { problems = append(problems, fmt.Sprintf( "schema %q is missing from the committed output (%s)", name, describeProvenance(provenance, name), )) continue } if !reflect.DeepEqual(expectedSchemas[name], committedSchema) { problems = append(problems, fmt.Sprintf( "schema %q changed (%s)", name, describeProvenance(provenance, name), )) } } for _, name := range sortedSchemaNames(committedSchemas) { if _, ok := expectedSchemas[name]; !ok { problems = append(problems, fmt.Sprintf( "schema %q is obsolete: no Archie-owned contract defines it", name, )) } } if len(problems) == 0 && !bytes.Equal(expected, committed) { problems = append(problems, "content differs from generated form (whitespace or key ordering)") } return problems } // 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 } var problems []string for _, entry := range entries { if entry.IsDir() || owned[entry.Name()] { continue } if filepath.Ext(entry.Name()) != ".json" { continue } problems = append(problems, fmt.Sprintf( "%s is obsolete: no generator in tools/docsgen produces it", 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. 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) } // 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 } 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 } 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: // 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 { visit(target) } } continue } walkSchemaRefs(child, visit) } case []any: for _, child := range node { walkSchemaRefs(child, visit) } } } func decodeSchemas(body []byte) (map[string]any, error) { var data struct { Schemas map[string]any `json:"schemas"` } if err := json.Unmarshal(body, &data); err != nil { return nil, err } return data.Schemas, nil } func sortedSchemaNames(schemas map[string]any) []string { names := make([]string, 0, len(schemas)) for name := range schemas { names = append(names, name) } sort.Strings(names) return names } func run(repoRoot, outPath string) error { absRoot, err := filepath.Abs(repoRoot) if err != nil { return fmt.Errorf("resolve repository root: %w", err) } return write(absRoot, outPath, false) } // displayPath prefers a repository-relative path for diagnostics, falling back // to the path as given when the target sits outside the repository (a temp // directory under check, or an explicit --out). func displayPath(absRoot, path string) string { relative, err := filepath.Rel(absRoot, path) if err != nil || strings.HasPrefix(relative, "..") { return filepath.ToSlash(path) } return filepath.ToSlash(relative) } func write(absRoot, outPath string, quiet bool) error { reflector := &jsonschema.Reflector{ ExpandedStruct: true, DoNotReference: false, } if err := loadGoComments(reflector, absRoot); err != nil { return fmt.Errorf("load Go comments: %w", err) } schemas := map[string]any{} types := currentContractTypes() names := make([]string, 0, len(types)) for name := range types { names = append(names, name) } sort.Strings(names) for _, name := range names { if err := collectSchema(reflector, schemas, name, types[name]); err != nil { return fmt.Errorf("reflect %s: %w", name, err) } } rewriteDefRefs(schemas) body, err := json.MarshalIndent(struct { GeneratedBy string `json:"generatedBy"` Schemas map[string]any `json:"schemas"` }{ GeneratedBy: "tools/docsgen", Schemas: schemas, }, "", " ") if err != nil { return fmt.Errorf("marshal documentation data: %w", err) } body = append(body, '\n') destination := outPath if !filepath.IsAbs(destination) { destination = filepath.Join(absRoot, destination) } if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil { return fmt.Errorf("create output directory: %w", err) } if err := os.WriteFile(destination, body, 0o644); err != nil { return fmt.Errorf("write %s: %w", destination, err) } if !quiet { fmt.Printf("docsgen: wrote %d schemas to %s\n", len(schemas), destination) } return nil } // currentContractTypes adapts the pre-domain-registry contract set during the // architecture migration. Delete it when agent execution and messaging expose // domain-owned documentation registries; docsgen must then consume those // registries directly. func currentContractTypes() map[string]reflect.Type { return map[string]reflect.Type{ "AgentExecutionRequest": reflect.TypeFor[agentexec.Request](), "AgentExecutionResult": reflect.TypeFor[agentexec.Result](), "MessageEvent": reflect.TypeFor[gateway.MessageEvent](), } } func loadGoComments(reflector *jsonschema.Reflector, repoRoot string) error { const modulePath = "github.com/samcharles93/archie-core" if err := reflector.AddGoComments("", filepath.Join(repoRoot, "internal")); err != nil { return err } rootPrefix := filepath.ToSlash(repoRoot) + "/" comments := make(map[string]string, len(reflector.CommentMap)) for name, comment := range reflector.CommentMap { relativeName := strings.TrimPrefix(filepath.ToSlash(name), rootPrefix) comments[modulePath+"/"+relativeName] = comment } reflector.CommentMap = comments return nil } func collectSchema( reflector *jsonschema.Reflector, schemas map[string]any, name string, t reflect.Type, ) error { if _, exists := schemas[name]; exists { return fmt.Errorf("duplicate published schema name %q", name) } raw, err := json.Marshal(reflector.ReflectFromType(t)) if err != nil { return err } var tree map[string]any if err := json.Unmarshal(raw, &tree); err != nil { return err } defs, _ := tree["$defs"].(map[string]any) delete(tree, "$defs") delete(tree, "$schema") delete(tree, "$id") schemas[name] = tree for defName, defSchema := range defs { if existing, exists := schemas[defName]; exists { if !reflect.DeepEqual(existing, defSchema) { return fmt.Errorf("conflicting schema definition %q", defName) } continue } schemas[defName] = defSchema } return nil } func rewriteDefRefs(schemas map[string]any) { for name, schema := range schemas { schemas[name] = rewriteNode(schema) } } func rewriteNode(value any) any { switch node := value.(type) { case map[string]any: for key, child := range node { if key == "$ref" { if ref, ok := child.(string); ok { node[key] = rewriteRef(ref) continue } } node[key] = rewriteNode(child) } return node case []any: for index, child := range node { node[index] = rewriteNode(child) } return node default: return value } } func rewriteRef(ref string) string { const prefix = "#/$defs/" if len(ref) > len(prefix) && ref[:len(prefix)] == prefix { return "#/schemas/" + ref[len(prefix):] } return ref }