feat: add openapi asyncapi validate command

Merged
TR
3d ago
+748-29

Stacked on #324 (then #323, #322 and #321). Review those first; this PR's base is the #324 branch.

Why

The asyncapi package can parse, resolve and validate AsyncAPI 3.x documents, but there was no way to use it from the CLI. This adds openapi asyncapi validate, the Stage 4 command from the plan.

What changed

  • New openapi asyncapi command group with validate, taking a file or stdin like the other validate commands.
  • Local by default. Nothing outside the document is read. In-document references are still resolved, so traits and cross-object checks run. References to other files and URLs are reported as warnings (they aren't known to be broken) and listed under a "Not checked" section that points at --resolve.
  • Flags:
    • --resolve loads references to other files and URLs (30 second HTTP timeout).
    • --base-uri sets the location relative references resolve against, mainly for stdin. It errors without --resolve rather than silently doing nothing.
    • --strict fails on warnings. Hints never fail.
  • Honest output. Schemas in formats that aren't validated (Avro, Protobuf) and bindings are counted under "Not checked", so a pass isn't mistaken for full coverage. Unsupported versions (including 2.x) report only the version error and say the rest wasn't checked, instead of a pile of 3.x-model noise.
  • Library: asyncapi.ErrExternalReferencesDisabled, wrapped by the diagnostics for references that weren't followed, so callers can tell them apart from broken ones with errors.Is.
  • cmd/openapi now depends on a root module pseudo-version that includes the asyncapi package (second commit), per AGENTS.md. No replace directive. This also means arazzo validate/lint now check AsyncAPI sources from #324.
  • Docs: root README (package, command group and quick examples), new cmd/openapi/commands/asyncapi/README.md, root help text, and a pointer from asyncapi/README.md.

Review notes

  • Exit status: 0 when there are no errors (warnings and hints allowed), 1 for errors, unsupported versions, unreadable input, or warnings with --strict. That's how errors and warnings are told apart; I didn't add a separate exit code for strict failures.
  • Fixed in passing: the arazzo validate help text still said AsyncAPI sources aren't checked, which #324 changed. Its CLI test (TestValidateArazzo_Success) also expected the old "AsyncAPI isn't checked" hint and had been failing since #324. mise ci didn't catch it because the root ./... doesn't include the nested cmd/openapi module, so its Go tests never run there. I've only fixed the test here. Running the cmd/openapi tests in mise ci seems worth a separate change.
  • The pseudo-version points at this branch's first commit. If anything in the root module changes in review, the bump needs redoing with the new SHA.

Testing

  • cmd/openapi/commands/asyncapi/validate_test.go covers:
    • a valid document, with and without --resolve
    • unfollowed references being warnings, and failing with --strict
    • a broken external reference that only shows up with --resolve
    • stdin with and without --base-uri, and --base-uri without --resolve
    • formats not validated, hints not failing with --strict
    • an invalid document, a 2.x document, a missing file, unparseable input and a stdin read error
  • asyncapi/resolve_test.go checks the disabled-reference diagnostics wrap ErrExternalReferencesDisabled.
  • test-cli exercises asyncapi validate on the fixtures (including stdin with --base-uri and --strict), and the AsyncAPI Arazzo fixtures from #324.
  • The cmd/openapi module tests (gotestsum -- -race ./... from cmd/openapi) pass, as does the standalone build with GOWORK=off.
  • mise ci passes locally. It runs outside the sandbox because the JSON Schema suite needs localhost:1234.

Summary by cubic

Adds openapi asyncapi validate, the first CLI path to the asyncapi package's AsyncAPI 3.x validation. arazzo validate and lint now also check AsyncAPI sources, and their stale help text and test expectations saying otherwise were fixed.

Validation behavior

  • Only the document itself is read by default; in-document references still resolve, but references to other files and URLs are warnings listed under a "Not checked" section pointing at --resolve.
  • --resolve loads external references with a 30-second HTTP timeout, --base-uri gives stdin a location to resolve against and requires --resolve, and --strict fails on warnings (hints never fail).
  • Unvalidated content (Avro/Protobuf schemas, protocol bindings) is counted under "Not checked", and unsupported versions, including 2.x, report only the version error.
  • Resolution wraps disabled-external-reference diagnostics in asyncapi.ErrExternalReferencesDisabled so callers can tell unfollowed references from broken ones with errors.Is.
  • arazzo validate also checks AsyncAPI step header parameters against the headers their messages declare, reported as warnings.
  • Exit status is 0 with no errors (warnings and hints allowed), 1 for errors, warnings with --strict, or unreadable or unsupported input.

Notes

  • cmd/openapi now depends on a root module pseudo-version that includes the asyncapi package; its tests don't run in mise ci because the nested module isn't covered by ./..., which is why the stale arazzo test went unnoticed.
  • New tests cover command registration and resolution failures, and the CLI module was re-pinned to the latest AsyncAPI stack root module after the stage 5 merge.