feat: add openapi asyncapi validate command
Merged
TR
3d ago+748+748+012345678901234567890123456789-29-29-01234567890123456789
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 asyncapicommand group withvalidate, 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:
--resolveloads references to other files and URLs (30 second HTTP timeout).--base-urisets the location relative references resolve against, mainly for stdin. It errors without--resolverather than silently doing nothing.--strictfails 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 witherrors.Is. cmd/openapinow depends on a root module pseudo-version that includes theasyncapipackage (second commit), per AGENTS.md. Noreplacedirective. This also meansarazzo validate/lintnow 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 fromasyncapi/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 validatehelp 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 cididn't catch it because the root./...doesn't include the nestedcmd/openapimodule, so its Go tests never run there. I've only fixed the test here. Running thecmd/openapitests inmise ciseems 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.gocovers:- 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-uriwithout--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
- a valid document, with and without
asyncapi/resolve_test.gochecks the disabled-reference diagnostics wrapErrExternalReferencesDisabled.test-cliexercisesasyncapi validateon the fixtures (including stdin with--base-uriand--strict), and the AsyncAPI Arazzo fixtures from #324.- The
cmd/openapimodule tests (gotestsum -- -race ./...fromcmd/openapi) pass, as does the standalone build withGOWORK=off. mise cipasses locally. It runs outside the sandbox because the JSON Schema suite needslocalhost: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. --resolveloads external references with a 30-second HTTP timeout,--base-urigives stdin a location to resolve against and requires--resolve, and--strictfails 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.ErrExternalReferencesDisabledso callers can tell unfollowed references from broken ones witherrors.Is. arazzo validatealso 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/openapinow depends on a root module pseudo-version that includes theasyncapipackage; its tests don't run inmise cibecause 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.