Skip to content

decree-docs: add doc model, schema loaders, and JSON output#936

Merged
zeevdr merged 1 commit into
mainfrom
914-decree-docs-model
Jun 12, 2026
Merged

decree-docs: add doc model, schema loaders, and JSON output#936
zeevdr merged 1 commit into
mainfrom
914-decree-docs-model

Conversation

@zeevdr

@zeevdr zeevdr commented Jun 12, 2026

Copy link
Copy Markdown
Member

Summary

  • The architectural core of decree-docs (epic Epic: decree-docs — advanced schema docs generator #921): a strongly-typed docmodel package that supersets the minimal sdk/tools/docgen schema (info, named examples, externalDocs, version_description, allowed_schemes — no untyped fields), so every later backend renders from one complete model.
  • The JSON shape is the contract for third-party renderers (the goal stated in Publish meta-schema for schema YAML structure (v0.1.0) #117): lowerCamel keys, omitempty optionals, path-sorted fields, and a docModelVersion root marker, all documented in the package doc and pinned by golden fixtures plus a canonical-form test.
  • Loaders populate the model from a schema YAML (via sdk/tools/validate) and from a server (via a narrow loader.SchemaClient interface that *adminclient.Client satisfies); both canonicalize so the equivalence guarantee is structural, not fixture luck. Two drift tests mirror cmd/decree's: every adminclient and every file-format property must be mapped or explicitly listed as not-documented.
  • Server-only fields (ID, ParentVersion, Checksum, Published, CreatedAt) are excluded from the model — schema YAML cannot express them, and including them would force the file/server equivalence test to zero them, weakening the guarantee.
  • CLI: decree-docs generate --file <schema> --format json; server-mode dialing flags are deferred to decree-docs: config file and template override system #918 (config surface) — the scaffold's dependency footprint deliberately excludes grpctransport until then.

Test plan

  • make test — all modules pass, including the three new packages
  • ./scripts/check-coverage.sh — contrib/decree-docs 99.1%, ratchet floor raised 88.8 → 99.0
  • make lint-go clean; gofumpt -l empty; go build/go vet clean
  • Golden JSON fixtures (full + minimal schemas) and loader equivalence test (file vs fake-transport server load, deep-equal)
  • Binary E2E: generate --file testdata/full.schema.yaml --format json exits 0, byte-identical to the golden

Closes #914

Define the tool's own documentation model in docmodel: a complete,
strongly-typed superset of the core docgen schema with a versioned,
lowerCamel JSON serialization as the contract for third-party renderers.
Add loaders that populate it from schema YAML (via sdk/tools/validate)
and from a server through the adminclient interface seam, canonicalized
so both sources produce deep-equal models for equivalent content, and
wire a generate subcommand running --file/--format json end to end with
golden fixtures pinning the shape.

Closes #914

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@zeevdr zeevdr added this to the Docs Toolkit milestone Jun 12, 2026
@zeevdr zeevdr added size: M Moderate — a day or two, clear scope priority: P2 Nice-to-have labels Jun 12, 2026
@codecov

codecov Bot commented Jun 12, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@zeevdr zeevdr merged commit 0e0d4f2 into main Jun 12, 2026
21 checks passed
@zeevdr zeevdr deleted the 914-decree-docs-model branch June 12, 2026 05:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority: P2 Nice-to-have size: M Moderate — a day or two, clear scope

Projects

None yet

Development

Successfully merging this pull request may close these issues.

decree-docs: doc model, schema loaders, and JSON output

1 participant