fix: Pin Spectral rulesets and run local binary in spec validations - #1415
Merged
andmatei merged 8 commits intoAug 5, 2026
Merged
Conversation
…idations ## Proposed changes The OpenAPI Spec Release fails in all environments when Spectral crashes (exit code 2, "Cannot read properties of null (reading 'enum')") in the `required-validations` job. The crash is nondeterministic: the release workflows invoke Spectral via `npx -- @stoplight/spectral-cli@<version>`, which pins only the CLI and lets its transitive dependencies float on caret ranges. Depending on whether the npx cache is warm, `@stoplight/spectral-rulesets` resolves to either 1.21.3 (from the lockfile) or a newer version whose `duplicated-entry-in-enum` rule dropped the `@ &&` null guard from its JSONPath `given` expression, causing it to dereference `.enum` on the single `null` value present in a preview request-body example and abort. This removes the nondeterminism so the lockfile strictly governs which rulesets version runs: - Add npm `overrides` to `package.json` (and the lockfile root) pinning `@stoplight/spectral-rulesets`, `@stoplight/spectral-core`, and `@stoplight/spectral-functions` so the resolved dependency tree is reproducible. - Invoke the locally installed `./node_modules/.bin/spectral` binary instead of `npx -- @stoplight/spectral-cli@<version>` in the lint steps of `required-spec-validations.yml` and `optional-spec-validations.yml`, so the lockfile (not the npx cache) determines the executed versions. - Use `npm ci` instead of `npm install` in both workflows so the lockfile is honoured strictly. _Jira ticket:_ CLOUDP-429023 ## Checklist - [ ] I have signed the [MongoDB CLA](https://www.mongodb.com/legal/contributor-agreement) - [ ] I have added tests that prove my fix is effective or that my feature works ### Changes to Spectral - [x] I have read the [README](../tools/spectral/README.md) file for Spectral Updates ## Further comments The `spectral_version` workflow inputs are left in place because caller workflows (`release-spec.yml`, `release-spec-runner.yml`) still pass them; removing them is out of scope here. Follow-ups noted on the ticket remain outside this repository: getting the meaningless `query: null` removed from the `chartsDashboards:import` preview example upstream, and reporting the missing null guard in `duplicated-entry-in-enum` to Stoplight.
Contributor
Author
|
Sage Bot can help with this pull request. Just |
andmatei
changed the title
# Conflicts: # package-lock.json # package.json
andmatei
marked this pull request as ready for review
August 5, 2026 13:25
andmatei
requested review from
andmatei,
andreaangiolillo,
drinkbird,
maks-m-mongo-leaf,
matt-condon,
saisundar and
wtrocki
August 5, 2026 13:25
matt-condon
approved these changes
Aug 5, 2026
andmatei
deleted the
sage-bot/CLOUDP-429023/sage-CLOUDP-429023-1785843153209
branch
August 5, 2026 14:20
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
The OpenAPI Spec Release fails in all environments when Spectral crashes
(exit code 2,
Cannot read properties of null (reading 'enum')) in therequired-validationsjob. The release workflows previously usednpm installand
npx, allowing the Spectral toolchain to drift from the dependency treereviewed in this repository's lockfile.
This change makes the Spectral toolchain reproducible:
@stoplight/spectral-rulesets@1.22.7.npm ci, so CI strictly honorspackage-lock.json.spectral_versionworkflow input and all of its callers.request-body example contains a nested
nullvalue.proposed and validated together.
Jira ticket: CLOUDP-429023
Checklist
Changes to Spectral
Further comments
Stoplight tracked the null crash in
#2959, fixed it in
#2960, and published the
fix in
@stoplight/spectral-rulesets@1.22.7.The rulesets package is therefore declared directly at the fixed version
instead of being constrained with an npm override.
The
query: nullvalue in thechartsDashboards:importexample is validCharts export behavior, including in version 9 export files. The regression
test intentionally retains this case. Improving the broader, abbreviated MMS
example would be separate contract and documentation work rather than part of
this Spectral fix.
Important
MongoDB Contribution Guidelines
This pull request was generated by sage-bot on behalf of andrei.matei@mongodb.com (ticket assignee). The assignee must self-review the changes before requesting review from another engineer.
The assignee is not allowed to merge their own PR without approval from another engineer.