Files
archie/tools/docsgen/main.go
T

539 lines
15 KiB
Go

// 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 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() {
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 with: go -C tools run ./docsgen --repo-root ..",
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
}