Merge branch 'main' into main

.github/workflows/smoke-plugins.yaml

@@ -0,0 +1,92 @@
+name: Plugins smoke tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+env:
+  CI: true
+  REDOCLY_TELEMETRY: off
+
+jobs:
+  prepare-smoke-plugins:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Prepare Smoke
+        run: bash ./scripts/prepare-smoke-plugins.sh
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke-plugins/
+          key: cache-plugins-${{ github.run_id }}-${{ github.run_attempt }}
+
+  run-smoke-plugins--npm--node-22:
+    needs: prepare-smoke-plugins
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke-plugins/
+          key: cache-plugins-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 22
+      - run: bash ./__tests__/smoke-plugins/run-smoke.sh
+
+  run-smoke-plugins--npm--node-20:
+    needs: prepare-smoke-plugins
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke-plugins/
+          key: cache-plugins-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - run: bash ./__tests__/smoke-plugins/run-smoke.sh
+
+  run-smoke-plugins--npm--node-18:
+    needs: prepare-smoke-plugins
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke-plugins/
+          key: cache-plugins-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: bash ./__tests__/smoke-plugins/run-smoke.sh
+
+  run-smoke-plugins--npm--node-16:
+    needs: prepare-smoke-plugins
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke-plugins/
+          key: cache-plugins-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+      - run: bash ./__tests__/smoke-plugins/run-smoke.sh
+
+  run-smoke-plugins--npm--node-14:
+    needs: prepare-smoke-plugins
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke-plugins/
+          key: cache-plugins-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 14
+      - run: bash ./__tests__/smoke-plugins/run-smoke.sh

.github/workflows/smoke.yaml

@@ -26,6 +26,32 @@ jobs:
           path: __tests__/smoke/
           key: cache-${{ github.run_id }}-${{ github.run_attempt }}
 
+  run-smoke--npm--node-22:
+    needs: prepare-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke/
+          key: cache-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 22
+      - run: bash ./__tests__/smoke/run-smoke.sh "npm i redocly-cli.tgz" "npm run"
+
+  run-smoke--npm--node-22--redoc:
+    needs: prepare-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke/
+          key: cache-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 22
+      - run: bash ./__tests__/smoke/run-smoke.sh "npm i redoc redocly-cli.tgz" "npm run"
+
   run-smoke--npm--node-20:
     needs: prepare-smoke
     runs-on: ubuntu-latest
@@ -130,6 +156,32 @@ jobs:
           node-version: 14
       - run: bash ./__tests__/smoke/run-smoke.sh "npm i redoc redocly-cli.tgz" "npm run"
 
+  run-smoke--yarn--node-22:
+    needs: prepare-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke/
+          key: cache-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 22
+      - run: bash ./__tests__/smoke/run-smoke.sh "yarn add ./redocly-cli.tgz" "yarn"
+
+  run-smoke--yarn--node-22--redoc:
+    needs: prepare-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v3
+        with:
+          path: __tests__/smoke/
+          key: cache-${{ github.run_id }}-${{ github.run_attempt }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 22
+      - run: bash ./__tests__/smoke/run-smoke.sh "yarn add redoc ./redocly-cli.tgz" "yarn"
+
   run-smoke--yarn--node-20:
     needs: prepare-smoke
     runs-on: ubuntu-latest

__tests__/bundle/bundle-external-value/external-value.json

@@ -0,0 +1,4 @@
+{
+  "foo": "bar",
+  "key": "value"
+}

__tests__/bundle/bundle-external-value/redocly.yaml

@@ -0,0 +1,8 @@
+apis:
+  first:
+    root: ./test-success.yaml
+  second:
+    root: ./test-wrong-examples.yaml
+
+extends:
+  - recommended

__tests__/bundle/bundle-external-value/snapshot.js

@@ -0,0 +1,59 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`E2E bundle bundle-external-value 1`] = `
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Example.com
+  termsOfService: https://example.com/terms/
+  contact:
+    email: contact@example.com
+    url: http://example.com/contact
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  description: OpenAPI description with external example
+security: []
+paths:
+  /:
+    post:
+      summary: Test request externalValue with relative reference in examples
+      requestBody:
+        content:
+          application/xml:
+            schema:
+              type: object
+            examples:
+              test-resolved:
+                summary: Example should resolved to value
+                value:
+                  foo: bar
+                  key: value
+              test-no-resolved:
+                summary: Example shouldn't be resolved to value
+                value:
+                  type: object
+                externalValue: ./external-value.json
+components: {}
+
+bundling ./test-success.yaml...
+📦 Created a bundle for ./test-success.yaml at stdout <test>ms.
+bundling ./test-wrong-examples.yaml...
+[1] test-wrong-examples.yaml:27:17 at #/paths/~1/post/requestBody/content/application~1xml/examples/test-wrong-ref
+
+Can't resolve $ref: ENOENT: no such file or directory './__tests__/bundle/bundle-external-value/external-value-bad-path.json'
+
+25 | examples:
+26 |   test-wrong-ref:
+27 |     summary: Example shouldn't resolved to value
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+28 |     externalValue: './external-value-bad-path.json'
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+29 |
+
+Error was generated by the bundler rule.
+
+
+❌ Errors encountered while bundling ./test-wrong-examples.yaml: bundle not created (use --force to ignore errors).
+
+`;

__tests__/bundle/bundle-external-value/test-success.yaml

@@ -0,0 +1,33 @@
+openapi: 3.1.0
+security: []
+info:
+  version: 1.0.0
+  title: Example.com
+  termsOfService: https://example.com/terms/
+  contact:
+    email: contact@example.com
+    url: http://example.com/contact
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  description: OpenAPI description with external example
+components: {}
+
+paths:
+  /:
+    post:
+      summary: Test request externalValue with relative reference in examples
+      requestBody:
+        content:
+          application/xml:
+            schema:
+              type: object
+            examples:
+              test-resolved:
+                summary: Example should resolved to value
+                externalValue: './external-value.json'
+              test-no-resolved:
+                summary: Example shouldn't be resolved to value
+                value:
+                  type: object
+                externalValue: './external-value.json'

__tests__/bundle/bundle-external-value/test-wrong-examples.yaml

@@ -0,0 +1,28 @@
+openapi: 3.1.0
+security: []
+info:
+  version: 1.0.0
+  title: Example.com
+  termsOfService: https://example.com/terms/
+  contact:
+    email: contact@example.com
+    url: http://example.com/contact
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  description: OpenAPI description with external example
+components: {}
+
+paths:
+  /:
+    post:
+      summary: Test request externalValue with relative reference in examples
+      requestBody:
+        content:
+          application/xml:
+            schema:
+              type: object
+            examples:
+              test-wrong-ref:
+                summary: Example shouldn't resolved to value
+                externalValue: './external-value-bad-path.json'

__tests__/smoke-plugins/local-plugin.js

@@ -0,0 +1,3 @@
+module.exports = function localPlugin() {
+  return { id: 'local-plugin' };
+};

__tests__/smoke-plugins/message-schema.yaml

@@ -0,0 +1,4 @@
+type: object
+properties:
+  message:
+    type: string

__tests__/smoke-plugins/openapi.yaml

@@ -0,0 +1,19 @@
+openapi: 3.1.0
+servers:
+  - url: http://redocly-example.com
+info:
+  title: Sample API
+  version: 1.0.0
+paths:
+  /hello:
+    get:
+      operationId: getMessage
+      security: []
+      summary: Get a greeting message
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: ./message-schema.yaml

__tests__/smoke-plugins/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "test-project-smoke-plugins",
+  "scripts": {
+    "redocly-version": "redocly --version",
+    "redocly-lint": "redocly lint openapi.yaml"
+  },
+  "dependencies": {
+    "@redocly/portal-plugin-async-api": "1.0.273"
+  }
+}

__tests__/smoke-plugins/redocly.yaml

@@ -0,0 +1,5 @@
+extends:
+  - recommended
+plugins:
+  - '@redocly/portal-plugin-async-api'
+  - local-plugin.js

__tests__/smoke-plugins/run-smoke.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+set -eo pipefail # Fail on script errors
+
+cd __tests__/smoke-plugins
+echo
+echo "Directory content:"
+ls -a
+echo
+
+# Install plugin package
+npm i
+
+# Install CLI globally
+npm i redocly-cli.tgz -g
+
+# Actual smoke test - executing the command provided as the second argument
+npm run redocly-version
+npm run  redocly-lint

docs/changelog.md

@@ -7,6 +7,14 @@ toc:
 
 <!-- do-not-remove -->
 
+## 1.25.5 (2024-10-04)
+
+### Patch Changes
+
+- Fixed an issue where the bundle command did not resolve links in `externalValue`.
+- Fixed an issue where the plugins in external NPM packages could not be resolved if the CLI package was installed globally.
+- Updated @redocly/openapi-core to v1.25.5.
+
 ## 1.25.4 (2024-09-30)
 
 ### Patch Changes

package-lock.json

@@ -13739,10 +13739,10 @@
     },
     "packages/cli": {
       "name": "@redocly/cli",
-      "version": "1.25.4",
+      "version": "1.25.5",
       "license": "MIT",
       "dependencies": {
-        "@redocly/openapi-core": "1.25.4",
+        "@redocly/openapi-core": "1.25.5",
         "abort-controller": "^3.0.0",
         "chokidar": "^3.5.1",
         "colorette": "^1.2.0",
@@ -13796,7 +13796,7 @@
     },
     "packages/core": {
       "name": "@redocly/openapi-core",
-      "version": "1.25.4",
+      "version": "1.25.5",
       "license": "MIT",
       "dependencies": {
         "@redocly/ajv": "^8.11.2",
@@ -16460,7 +16460,7 @@
     "@redocly/cli": {
       "version": "file:packages/cli",
       "requires": {
-        "@redocly/openapi-core": "1.25.4",
+        "@redocly/openapi-core": "1.25.5",
         "@types/configstore": "^5.0.1",
         "@types/glob": "^8.1.0",
         "@types/pluralize": "^0.0.29",

packages/cli/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @redocly/cli
 
+## 1.25.5
+
+### Patch Changes
+
+- Fixed an issue where the bundle command did not resolve links in `externalValue`.
+- Fixed an issue where the plugins in external NPM packages could not be resolved if the CLI package was installed globally.
+- Updated @redocly/openapi-core to v1.25.5.
+
 ## 1.25.4
 
 ### Patch Changes

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/cli",
-  "version": "1.25.4",
+  "version": "1.25.5",
   "description": "",
   "license": "MIT",
   "bin": {
@@ -36,7 +36,7 @@
     "Roman Hotsiy <roman@redoc.ly> (https://redoc.ly/)"
   ],
   "dependencies": {
-    "@redocly/openapi-core": "1.25.4",
+    "@redocly/openapi-core": "1.25.5",
     "abort-controller": "^3.0.0",
     "chokidar": "^3.5.1",
     "colorette": "^1.2.0",

packages/core/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @redocly/openapi-core
 
+## 1.25.5
+
+### Patch Changes
+
+- Fixed an issue where the bundle command did not resolve links in `externalValue`.
+- Fixed an issue where the plugins in external NPM packages could not be resolved if the CLI package was installed globally.
+
 ## 1.25.4
 
 ### Patch Changes

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/openapi-core",
-  "version": "1.25.4",
+  "version": "1.25.5",
   "description": "",
   "main": "lib/index.js",
   "engines": {

packages/core/src/bundle.ts

@@ -379,6 +379,25 @@ function makeBundleVisitor(
         }
       },
     },
+    Example: {
+      leave(node: any, ctx: UserContext) {
+        if (node.externalValue && node.value === undefined) {
+          const resolved = ctx.resolve({ $ref: node.externalValue });
+
+          if (!resolved.location || resolved.node === undefined) {
+            reportUnresolvedRef(resolved, ctx.report, ctx.location);
+            return;
+          }
+
+          if (keepUrlRefs && isAbsoluteUrl(node.externalValue)) {
+            return;
+          }
+
+          node.value = ctx.resolve({ $ref: node.externalValue }).node;
+          delete node.externalValue;
+        }
+      },
+    },
     Root: {
       enter(root: any, ctx: any) {
         rootLocation = ctx.location;

packages/core/src/config/config-resolvers.ts

@@ -139,7 +139,7 @@ export async function resolvePlugins(
         const absolutePluginPath = existsSync(maybeAbsolutePluginPath)
           ? maybeAbsolutePluginPath
           : // For plugins imported from packages specifically
-            require.resolve(plugin);
+            require.resolve(plugin, { paths: [configDir] });
 
         if (!pluginsCache.has(absolutePluginPath)) {
           let requiredPlugin: ImportedPlugin | undefined;

packages/core/src/resolve.ts

@@ -335,6 +335,28 @@ export async function resolveDocument(opts: {
         });
         resolvePromises.push(promise);
       }
+
+      // handle example.externalValue as reference
+      if (node.externalValue) {
+        const promise = followRef(
+          rootNodeDocument,
+          { $ref: node.externalValue },
+          {
+            prev: null,
+            node,
+          }
+        ).then((resolvedRef) => {
+          if (resolvedRef.resolved) {
+            resolveRefsInParallel(
+              resolvedRef.node,
+              resolvedRef.document,
+              resolvedRef.nodePointer!,
+              type
+            );
+          }
+        });
+        resolvePromises.push(promise);
+      }
     }
 
     async function followRef(

packages/core/src/rules/oas3/__tests__/fixtures/external-value.yaml

@@ -0,0 +1,2 @@
+a: foo
+b: 100

packages/core/src/rules/oas3/__tests__/no-invalid-media-type-examples.test.ts

@@ -553,7 +553,7 @@ describe('no-invalid-media-type-examples', () => {
                             type: number
                       examples:
                         first:
-                          externalValue: "https://example.com/example.json"
+                          externalValue: ./fixtures/external-value.yaml
       `,
       'foobar.yaml'
     );

scripts/prepare-smoke-plugins.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# For npm (Mutates packages/cli/package.json)
+npm run pack:prepare
+
+cp ./redocly-cli.tgz ./openapi-core.tgz ./__tests__/smoke-plugins
+
+echo "Current directory:"
+pwd
+echo
+echo "Current directory content:"
+ls -a
+echo
+echo "Target directory content:"
+ls -a __tests__/smoke-plugins/
+echo