Skip to content

feat: output validation and --check mode for CI - #17

Merged
includeamin merged 9 commits into
mainfrom
check-mode
Nov 21, 2026
Merged

includeamin merged 9 commits into
mainfrom
check-mode

Conversation

@includeamin

Copy link
Copy Markdown
Owner

Summary

  • Validator: new validate(&Value) -> Vec<Finding> in openapi-aggregator-core. It is a hand-written semantic validator (pure, no new dependencies, wasm-safe) that checks what an aggregation can actually break: dangling or unbundled $refs, duplicate operationIds, missing responses, undeclared, unused or duplicate path parameters, ambiguous paths, unknown security schemes, undeclared tags, invalid component names, and the required document fields. It is not a full OpenAPI JSON Schema validation. Each finding has a severity, a code and a JSON-pointer location, and uncertain rules are warnings.
  • CLI --check: merges, validates and exits non-zero on problems. With -o <file> it also verifies the file is up to date by comparing parsed data, so formatting, YAML vs JSON and key order never count as a difference, and prints a unified diff when it is stale. It never writes and prints nothing to stdout. --deny-warnings (requires --check) also fails on merge, conversion and validation warnings.
  • Exit codes: 0 passed, 1 validation errors, denied warnings or a merge/config failure, 2 output file missing or out of date. If both apply, exit 1 and the diff is still printed. Known caveat, documented: clap usage errors also exit 2.
  • Playground: findings are returned by the wasm aggregate and shown in the problems panel as validation problems, with the output still visible. The status shows "Merged with validation errors" when relevant.
  • Runs without --check are unchanged.

Notes

  • similar is added to the CLI crate only (for the diff).
  • Existing web and wasm test fixtures that defined operations without responses were fixed, since that is genuinely invalid OpenAPI.
  • A path item that is itself a $ref is skipped for path-parameter checks (covered by a test).

Test plan

  • cargo test --workspace: unit tests for every rule, a no-false-positive suite (Petstore 3.0, Petstore 2.0 after conversion, a 3.1 webhooks-only spec, $refd and path-item-level parameters), and 13 CLI binary tests covering exit codes, diffs, format and key-order independence, missing and unparseable output files, and that check mode never writes
  • cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --check
  • cd web && npm test (78 tests, every playground example validates clean), npm run typecheck, npm run e2e

@includeamin
includeamin merged commit d0f2f54 into main Nov 21, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant