fix: Pin Spectral rulesets and run local binary in spec validations

.github/dependabot.yml

@@ -20,6 +20,10 @@ updates:
     schedule:
       interval: weekly
       day: tuesday
+    groups:
+      spectral:
+        patterns:
+          - "@stoplight/spectral-*"
     commit-message:
       prefix: "chore"
   - package-ecosystem: npm

.github/workflows/optional-spec-validations.yml

@@ -2,10 +2,6 @@ name: 'Optional Spec Validations'
 on:
   workflow_call:
     inputs:
-      spectral_version:
-        description: 'Version of Spectral to use'
-        type: string
-        required: true
       env:
         description: 'Environment to generate the OpenAPI Spec for.'
         required: true
@@ -17,11 +13,6 @@ on:
         required: true
   workflow_dispatch:
     inputs:
-      spectral_version:
-        description: 'Version of Spectral to use'
-        type: string
-        required: true
-        default: 'latest'
       env:
         description: 'Environment to validate the OpenAPI Spec for.'
         type: choice
@@ -49,7 +40,7 @@ jobs:
           node-version: '20.x'
           cache: 'npm'
       - name: Install npm dependencies
-        run: npm install
+        run: npm ci
       - name: Download openapi-foas
         uses: actions/download-artifact@v8
         with:
@@ -58,14 +49,12 @@ jobs:
           run-id: ${{ github.run_id }}
       - name: Validate the FOAS can be used to generate Postman collection
         id: spectral-validation
-        env:
-          SPECTRAL_VERSION: ${{ inputs.spectral_version }}
         run: |
           cp -rf "openapi-foas.json" "./tools/postman/openapi/atlas-api.json"
           pushd tools/postman
           make convert_to_collection
-          npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint ./tmp/collection.json --ruleset=./validation/spectral.yaml
           popd
+          npm run spectral-lint -- ./tools/postman/tmp/collection.json --ruleset=./tools/postman/validation/spectral.yaml
 
   retry-handler:
     needs: [ optional-validations ]

.github/workflows/release-spec-runner.yml

@@ -59,7 +59,6 @@ jobs:
       aws_s3_role_to_assume: ${{ vars.AWS_S3_ROLE_TO_ASSUME }}
       env: dev
       branch: dev
-      spectral_version: ${{ vars.SPECTRAL_VERSION }}
       foascli_version: ${{ vars.FOASCLI_VERSION }}
       atlas_admin_v2_doc_id: ${{vars.ATLAS_ADMIN_V2_DOC_ID_DEV }}
 
@@ -79,7 +78,6 @@ jobs:
         aws_s3_bucket: ${{ vars.S3_BUCKET_QA}}
         env: qa
         branch: qa
-        spectral_version: ${{ vars.SPECTRAL_VERSION }}
         foascli_version: ${{ vars.FOASCLI_VERSION }}
         atlas_admin_v2_doc_id: ${{vars.ATLAS_ADMIN_V2_DOC_ID_QA }}
 
@@ -99,7 +97,6 @@ jobs:
         aws_s3_bucket: ${{ vars.S3_BUCKET_STAGING}}
         env: stage
         branch: staging
-        spectral_version: ${{ vars.SPECTRAL_VERSION }}
         foascli_version: ${{ vars.FOASCLI_VERSION }}
         atlas_admin_v2_doc_id: ${{vars.ATLAS_ADMIN_V2_DOC_ID_STAGING }}
 
@@ -121,7 +118,6 @@ jobs:
         aws_s3_bucket: ${{ vars.S3_BUCKET_PROD}}
         env: prod
         branch: main
-        spectral_version: ${{ vars.SPECTRAL_VERSION }}
         foascli_version: ${{ vars.FOASCLI_VERSION }}
         atlas_prod_base_url: ${{ vars.ATLAS_PROD_BASE_URL }}
         atlas_admin_v2_doc_id: ${{vars.ATLAS_ADMIN_V2_DOC_ID }}

.github/workflows/release-spec.yml

@@ -18,10 +18,6 @@ on:
         description: 'Branch to release the OpenAPI Spec to.'
         required: true
         type: string
-      spectral_version:
-        description: 'Version of Spectral to use.'
-        required: true
-        type: string
       foascli_version:
         description: 'Version of FOASCLI to use.'
         required: true
@@ -86,7 +82,6 @@ jobs:
     secrets:
       api_bot_pat: ${{ secrets.api_bot_pat }}
     with:
-      spectral_version: ${{ inputs.spectral_version }}
       env: ${{ inputs.env }}
 
   # Optional validations won't stop the release but only open a GH issue if they fail
@@ -99,7 +94,6 @@ jobs:
       jira_api_token: ${{ secrets.jira_api_token }}
     with:
       env: ${{ inputs.env }}
-      spectral_version: ${{ vars.SPECTRAL_VERSION }}
 
   release:
       name: Release OpenAPI Spec for V2 APIs

.github/workflows/required-spec-validations.yml

@@ -2,10 +2,6 @@ name: 'Required Spec Validations'
 on:
   workflow_call:
     inputs:
-      spectral_version:
-        description: 'Version of Spectral to use'     
-        type: string
-        required: true
       env:
         description: 'Environment to generate the OpenAPI Spec for.'
         required: true
@@ -28,7 +24,7 @@ jobs:
             node-version: '22.x'
             cache: 'npm'
         - name: Install npm dependencies
-          run: npm install
+          run: npm ci
         - name: Download openapi-foas
           uses: actions/download-artifact@v8
           with:
@@ -37,13 +33,10 @@ jobs:
             run-id: ${{ github.run_id }}
         - name: Run IPA validation
           id: ipa-spectral-validation
-          run: |
-            npx spectral lint openapi-foas.json --ruleset=./tools/spectral/ipa/ipa-spectral.yaml
-        - name: Run 
+          run: npm run spectral-lint -- openapi-foas.json --ruleset=./tools/spectral/ipa/ipa-spectral.yaml
+        - name: Run Spectral validation
           id: spectral-validation
-          env:
-            SPECTRAL_VERSION: ${{ inputs.spectral_version }}
-          run: npx -- @stoplight/spectral-cli@"${SPECTRAL_VERSION}" lint openapi-foas.yaml --ruleset=tools/spectral/.spectral.yaml
+          run: npm run spectral-lint -- openapi-foas.yaml --ruleset=tools/spectral/.spectral.yaml
         - name: Install Go
           uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e
           with:

.github/workflows/spectral-lint.yml

@@ -33,7 +33,7 @@ jobs:
           node-version: '20.x'
           cache: 'npm'
       - name: Install npm dependencies
-        run: npm install
+        run: npm ci
       - name: Fetch OAS file from Dev Branch
         run: curl -O "https://raw.githubusercontent.com/mongodb/openapi/refs/heads/dev/openapi/.raw/v2.yaml"
         working-directory: ${{ github.workspace }}
@@ -44,5 +44,4 @@ jobs:
           file_glob: openapi/.raw/v2.yaml
           spectral_ruleset: tools/spectral/.spectral.yaml #If updated, need to update in MMS too.
       - name: IPA validation action
-        run: npx spectral lint v2.yaml --ruleset=./tools/spectral/ipa/ipa-spectral.yaml
-
+        run: npm run spectral-lint -- v2.yaml --ruleset=./tools/spectral/ipa/ipa-spectral.yaml

package.json

@@ -9,6 +9,7 @@
         "gen-ipa-docs": "node tools/spectral/ipa/scripts/generateRulesetReadme.js",
         "ipa-validation": "spectral lint  ./openapi/.raw/v2.yaml --ruleset=./tools/spectral/ipa/ipa-spectral.yaml",
         "ipa-filter-violations": "node tools/spectral/ipa/scripts/filter-ipa-violations.js",
+        "spectral-lint": "spectral lint",
         "spectral-validation": "spectral lint ./openapi/.raw/v2.yaml --ruleset=./tools/spectral/.spectral.yaml",
         "test": "jest",
         "precommit": "husky"
@@ -24,11 +25,12 @@
     },
     "dependencies": {
         "@aws-sdk/client-s3": "^3.1101.0",
-        "@stoplight/spectral-cli": "^6.16.1",
-        "@stoplight/spectral-core": "^1.23.1",
-        "@stoplight/spectral-functions": "^1.10.5",
-        "@stoplight/spectral-ref-resolver": "^1.0.5",
-        "@stoplight/spectral-ruleset-bundler": "^1.7.0",
+        "@stoplight/spectral-cli": "6.16.1",
+        "@stoplight/spectral-core": "1.23.1",
+        "@stoplight/spectral-functions": "1.10.5",
+        "@stoplight/spectral-ref-resolver": "1.0.5",
+        "@stoplight/spectral-ruleset-bundler": "1.7.0",
+        "@stoplight/spectral-rulesets": "1.22.7",
         "apache-arrow": "^21.2.0",
         "dotenv": "^17.4.2",
         "eslint-plugin-jest": "^29.16.0",

tools/spectral/__tests__/spectralNullExample.test.js

@@ -0,0 +1,43 @@
+import { Spectral } from '@stoplight/spectral-core';
+import { oas } from '@stoplight/spectral-rulesets';
+
+describe('Spectral OAS ruleset compatibility', () => {
+  it('does not crash when a request-body example contains a null value', async () => {
+    const spectral = new Spectral();
+    spectral.setRuleset(oas);
+
+    const document = {
+      openapi: '3.0.3',
+      info: {
+        title: 'Null example regression',
+        version: '1.0.0',
+      },
+      paths: {
+        '/dashboards/import': {
+          post: {
+            responses: {
+              200: {
+                description: 'OK',
+              },
+            },
+            requestBody: {
+              content: {
+                'application/json': {
+                  example: {
+                    items: {
+                      'item-1': {
+                        query: null,
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    await expect(spectral.run(JSON.stringify(document))).resolves.toEqual(expect.any(Array));
+  });
+});