beads/cmd/bd/schema.go
matt wilkie ecb9e92735
feat(cli): bd schema — JSON Schema for --json/export output (carries #4413, griels) (#5098)
* Add `bd schema` command emitting JSON Schema for output records

`bd schema` reflects the canonical issue/dependency output structs
(internal/types) into a JSON Schema via invopop/jsonschema, so consumers can
codegen typed models (datamodel-code-generator, quicktype, ...) instead of
hand-mirroring the --json / export format. Because the schema is generated from
the same structs bd serializes, it cannot drift from the actual output the way
docs/JSON_SCHEMA.md or a downstream consumer model (e.g. beads-mcp's Pydantic
models) can. Output carries schema_version (== JSONSchemaVersion).

Promotes invopop/jsonschema from an indirect to a direct dependency.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
(cherry picked from commit 2bb8d2c305)

* Enumerate status/type/dependency values in `bd schema` + add tests

- Add canonical AllStatuses / AllIssueTypes / AllDependencyTypes lists to
  internal/types and derive Status.IsValid / IssueType.IsValid from them, so
  validation and the schema enums share one source (behaviour-preserving;
  internal/types tests pass).
- `bd schema` now enriches the status, issue_type, and dependency `type`
  fields with their allowed values via a jsonschema Mapper sourced from those
  lists, so the published schema constrains them instead of emitting a bare
  "string" — exactly the constraint hand-mirrored consumers can't track.
- Extract schemaDocument() so the command is unit-testable without a workspace
  or DB; add cmd/bd/schema_test.go asserting valid JSON, schema_version, the
  issue/dependency records, required fields, and the populated enums.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
(cherry picked from commit 9beb73d023)

* Fix misspell + regenerate CLI docs for `bd schema`

- internal/types: "recognises" -> "recognizes" (misspell lint).
- Regenerate docs/CLI_REFERENCE.md, the website CLI reference pages, and
  llms-full.txt to cover the new `bd schema` command (via
  scripts/generate-cli-docs.sh + generate-llms-full.sh from a canonical
  pure-go build). The CLI-docs freshness gate now passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
(cherry picked from commit 1cd9be76c6)

* fixup: errcheck on outputJSONRaw, godoc placement, go.mod tidy for bd schema

- cmd/bd/schema.go: switch schemaCmd.Run to RunE and return the
  outputJSONRaw error instead of discarding it, matching the
  return-outputJSON(...) pattern used elsewhere in cmd/bd (e.g.
  branch.go, audit.go, comment.go).
- internal/types/types.go: reorder the AllIssueTypes var and its
  godoc so each comment sits directly above its own declaration; the
  cherry-picked var block had split IsValid's godoc comment across
  the inserted var.
- go.mod: go mod tidy after the cherry-picked invopop/jsonschema
  v0.14.0 direct-require resolution; drops the now-unneeded
  mailru/easyjson indirect entry.

Agent-Signature: claude-code-sonnet-medium on behalf of matt wilkie

* fix(schema): skip store init — the command reflects static types only

Without skipStoreAnnotation, bd schema ran the PersistentPreRunE store open
and failed outside a workspace or on a CGO-less build, defeating the
command's storage-free design.

Agent-Signature: claude-fable-5-medium on behalf of matt wilkie

---------

Co-authored-by: Ellis Breen <1263585+griels@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-27 14:16:56 -07:00

94 lines
3.5 KiB
Go

package main
import (
"reflect"
"github.com/invopop/jsonschema"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/types"
)
// schemaCmd emits the JSON Schema for bd's canonical --json / export output
// record types.
//
// The schema is generated by reflection from the same internal/types structs
// that bd serializes, so by construction it cannot drift from the actual output
// the way a hand-maintained doc (docs/JSON_SCHEMA.md) or a downstream consumer
// model (e.g. beads-mcp's Pydantic models) can. The named string enums (status,
// issue_type, dependency type) are enriched with their allowed values, sourced
// from the same internal/types lists that validation uses. The emitted
// schema_version matches JSONSchemaVersion and bumps with it.
//
// Consumers can codegen typed models from this output (datamodel-code-generator
// for Python/Pydantic, quicktype, etc.) instead of hand-mirroring the format.
var schemaCmd = &cobra.Command{
Use: "schema",
Short: "Print the JSON Schema for bd's --json / export output",
// The schema is reflected from static Go types; no store is needed, and
// opening one would make this fail outside a workspace (or on a CGO-less
// build) for no reason.
Annotations: map[string]string{skipStoreAnnotation: "1"},
Long: `Print the JSON Schema for bd's canonical output record types.
The schema is reflected from the same Go structs bd serializes, so it stays in
lockstep with the actual --json / export output. Use it to generate typed
consumer models (datamodel-code-generator, quicktype, ...) rather than
hand-maintaining them.
bd schema | jq '.types.issue' # the issue record schema
bd schema | jq '.types.dependency' # the dependency record schema`,
RunE: func(cmd *cobra.Command, args []string) error {
// Raw: the document carries its own schema_version; do not double-wrap
// it in the --json envelope.
return outputJSONRaw(schemaDocument())
},
}
// schemaDocument builds the JSON Schema document for bd's canonical output
// record types. Split out from the command so it can be unit-tested without a
// workspace or database.
func schemaDocument() map[string]interface{} {
reflector := &jsonschema.Reflector{
// Inline referenced types so each record schema is self-contained and
// directly consumable by codegen tools.
DoNotReference: true,
// Enrich bd's named string enums with their allowed values.
Mapper: enumMapper,
}
return map[string]interface{}{
"schema_version": JSONSchemaVersion,
"types": map[string]*jsonschema.Schema{
"issue": reflector.Reflect(&types.Issue{}),
"dependency": reflector.Reflect(&types.Dependency{}),
},
}
}
// enumMapper maps bd's named string enum types to a string schema enumerating
// their allowed values, so the published schema constrains them instead of
// emitting a bare "string". Values come from the canonical internal/types lists
// that validation also consults, so the schema cannot drift from them.
func enumMapper(t reflect.Type) *jsonschema.Schema {
switch t {
case reflect.TypeOf(types.Status("")):
return stringEnum(types.AllStatuses)
case reflect.TypeOf(types.IssueType("")):
return stringEnum(types.AllIssueTypes)
case reflect.TypeOf(types.DependencyType("")):
return stringEnum(types.AllDependencyTypes)
}
return nil
}
func stringEnum[T ~string](values []T) *jsonschema.Schema {
enum := make([]any, len(values))
for i, v := range values {
enum[i] = string(v)
}
return &jsonschema.Schema{Type: "string", Enum: enum}
}
func init() {
rootCmd.AddCommand(schemaCmd)
}