539 lines
15 KiB
Go
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
|
|
}
|