The site's sidebar held the landing page and one guide next to seventeen architecture records, the migration register, the review procedure and five PRDs. Nothing there is secret -- every development page may be read by anyone -- but a reader who wants to know what Archie is and how to point an event at it was meeting contributor material with no signal that it was not for them. One source tree now yields two sets: public (index, guides/) under /docs/, and development (architecture/, prds/) under /dev/, each with its own artifact and its own derived sidebar. archive/, inspiration/, news/ and the credential notes stay out of both, unchanged. Selective PRD publication is gone rather than carried over. It existed only because settled architecture cites PRDs and a link to a held-back target fails the generator, so five PRDs published to keep those citations alive; with both halves of every such citation in the development set, the exception has no work left to do. Both sets are generated in one pass over one url map, so a citation that crosses between them resolves to the base its target is served under, and the refusal now fires only for a target genuinely in neither set. Widening the set exposed a scanner bug worth its own note: the link regex matched `Resolve[T](i, src, exportPath)` inside a code span and refused the page for a link to `i,`. Code spans and fenced blocks are now skipped, because what a renderer draws as a link is the only thing this tool may rewrite or refuse a page for. docs/prds/public-and-dev-docs.md records the decision. Draft: the three choices in it are the maintainer's, the write-up is not yet reviewed.
547 lines
16 KiB
Go
547 lines
16 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 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
|
|
}
|