fix: resolve files specified in the rules and decorators parameters relative to the config file (#2259)

tatomyr · web-flow · commit d8e419c0ed0d · 2025-08-18T13:31:06.000+02:00
diff --git a/.changeset/dull-singers-lick.md b/.changeset/dull-singers-lick.md
@@ -0,0 +1,7 @@
+---
+"@redocly/openapi-core": patch
+"@redocly/cli": patch
+---
+
+Fixed an issue where files specified in decorators parameters were not always resolved correctly.
+The resolution logic now properly locates the specified files relative to the config file for `info-description-override`, `media-type-examples-override`, `operation-description-override`, and `tag-description-override` decorators.
diff --git a/__tests__/bundle/info-description-override-error/redocly.yaml b/__tests__/bundle/info-description-override-error/redocly.yaml
@@ -4,4 +4,4 @@ apis:
 
 decorators:
   info-description-override:
-    filePath: ./test.md
+    filePath: ./non-existing.md
diff --git a/__tests__/bundle/info-description-override-error/snapshot.txt b/__tests__/bundle/info-description-override-error/snapshot.txt
@@ -1,7 +1,7 @@
 [1] main.yaml:8:16 at #/info/description
 
 Failed to read markdown override file for "info.description".
-ENOENT: no such file or directory, open './test.md'
+ENOENT: no such file or directory, open './__tests__/bundle/info-description-override-error/non-existing.md'
 
  6 | title: Example OpenAPI 3 definition.
  7 | version: 1.0.0
diff --git a/__tests__/bundle/media-type-examples-override/examples/request.yaml b/__tests__/bundle/media-type-examples-override/examples/request.yaml
@@ -0,0 +1 @@
+name: Test
diff --git a/__tests__/bundle/media-type-examples-override/examples/response.yaml b/__tests__/bundle/media-type-examples-override/examples/response.yaml
@@ -0,0 +1,2 @@
+- Foo
+- Bar
diff --git a/__tests__/bundle/media-type-examples-override/openapi.yaml b/__tests__/bundle/media-type-examples-override/openapi.yaml
@@ -0,0 +1,28 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Test
+paths:
+  /test:
+    post:
+      operationId: test
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TestRequest'
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+components:
+  schemas:
+    TestRequest:
+      type: object
+      properties:
+        name:
+          type: string
diff --git a/__tests__/bundle/media-type-examples-override/redocly.yaml b/__tests__/bundle/media-type-examples-override/redocly.yaml
@@ -0,0 +1,13 @@
+apis:
+  main:
+    root: openapi.yaml
+
+decorators:
+  media-type-examples-override:
+    operationIds:
+      test:
+        request:
+          application/json: ./examples/request.yaml
+        responses:
+          200:
+            application/json: ./examples/response.yaml
diff --git a/__tests__/bundle/media-type-examples-override/snapshot.txt b/__tests__/bundle/media-type-examples-override/snapshot.txt
@@ -0,0 +1,36 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Test
+paths:
+  /test:
+    post:
+      operationId: test
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TestRequest'
+            examples:
+              name: Test
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+              examples:
+                - Foo
+                - Bar
+components:
+  schemas:
+    TestRequest:
+      type: object
+      properties:
+        name:
+          type: string
+
+bundling openapi.yaml using configuration for api 'main'...
+📦 Created a bundle for openapi.yaml at stdout <test>ms.
diff --git a/__tests__/bundle/operation-description-override-error/redocly.yaml b/__tests__/bundle/operation-description-override-error/redocly.yaml
@@ -5,4 +5,4 @@ apis:
 decorators:
   operation-description-override:
     operationIds:
-      updatePet: ./update-pet-operation-description.md
+      updatePet: ./non-existing.md
diff --git a/__tests__/bundle/operation-description-override-error/snapshot.txt b/__tests__/bundle/operation-description-override-error/snapshot.txt
@@ -1,7 +1,7 @@
 [1] openapi.yaml:23:7 at #/paths/~1pet/put/operationId
 
 Failed to read markdown override file for operation "updatePet".
-ENOENT: no such file or directory, open './update-pet-operation-description.md'
+ENOENT: no such file or directory, open './__tests__/bundle/operation-description-override-error/non-existing.md'
 
 21 | summary: Update an existing pet
 22 | description: ''
diff --git a/__tests__/bundle/tag-description-override-error/redocly.yaml b/__tests__/bundle/tag-description-override-error/redocly.yaml
@@ -5,4 +5,4 @@ apis:
 decorators:
   tag-description-override:
     tagNames:
-      pet: ./pet-tag-description.md
+      pet: ./non-existing.md
diff --git a/__tests__/bundle/tag-description-override-error/snapshot.txt b/__tests__/bundle/tag-description-override-error/snapshot.txt
@@ -1,7 +1,7 @@
 [1] main.yaml:17:5 at #/tags/0
 
 Failed to read markdown override file for tag "pet".
-ENOENT: no such file or directory, open './pet-tag-description.md'
+ENOENT: no such file or directory, open './__tests__/bundle/tag-description-override-error/non-existing.md'
 
 15 |     email: email@redocly.com
 16 | tags:
diff --git a/packages/cli/src/commands/stats.ts b/packages/cli/src/commands/stats.ts
@@ -103,7 +103,8 @@ export async function handleStats({ argv, config, collectSpecData }: CommandArgs
   const startedAt = performance.now();
   const ctx: WalkContext = {
     problems: [],
-    oasVersion: specVersion,
+    specVersion,
+    config,
     visitorsData: {},
   };
 
diff --git a/packages/core/src/bundle.ts b/packages/core/src/bundle.ts
@@ -45,7 +45,7 @@ export function collectConfigPlugins(
   const visitorsData: PluginsCollectorVisitorData = { plugins: [], rootConfigDir };
   const ctx: BundleContext = {
     problems: [],
-    oasVersion: 'oas3_0', // TODO: change it after we rename oasVersion to specVersion
+    specVersion: 'oas3_0', // TODO: change it to a config-specific type
     refTypes: new Map<string, NormalizedNodeType>(),
     visitorsData: {
       [PLUGINS_COLLECTOR_VISITOR_ID]: visitorsData,
@@ -71,7 +71,7 @@ export function bundleConfig(
   const visitorsData: ConfigBundlerVisitorData = { plugins };
   const ctx: BundleContext = {
     problems: [],
-    oasVersion: 'oas3_0', // TODO: change it after we rename oasVersion to specVersion
+    specVersion: 'oas3_0', // TODO: change it to a config-specific type
     refTypes: new Map<string, NormalizedNodeType>(),
     visitorsData: {
       [CONFIG_BUNDLER_VISITOR_ID]: visitorsData,
@@ -179,7 +179,8 @@ export async function bundleDocument(opts: {
 
   const ctx: BundleContext = {
     problems: [],
-    oasVersion: specVersion,
+    specVersion,
+    config,
     refTypes: new Map<string, NormalizedNodeType>(),
     visitorsData: {},
   };
diff --git a/packages/core/src/decorators/common/info-description-override.ts b/packages/core/src/decorators/common/info-description-override.ts
@@ -1,18 +1,21 @@
-import { readFileAsStringSync } from '../../utils.js';
+import { readFileAsStringSync, resolveRelativePath } from '../../utils.js';
 
 import type { Oas3Decorator, Oas2Decorator } from '../../visitors.js';
 import type { UserContext } from '../../walk.js';
 
 export const InfoDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ filePath }) => {
   return {
     Info: {
-      leave(info, { report, location }: UserContext) {
+      leave(info, { report, location, config }: UserContext) {
         if (!filePath)
           throw new Error(
             `Parameter "filePath" is not provided for "info-description-override" rule`
           );
+
         try {
-          info.description = readFileAsStringSync(filePath);
+          info.description = readFileAsStringSync(
+            resolveRelativePath(filePath, config?.configPath)
+          );
         } catch (e) {
           report({
             message: `Failed to read markdown override file for "info.description".\n${e.message}`,
diff --git a/packages/core/src/decorators/common/media-type-examples-override.ts b/packages/core/src/decorators/common/media-type-examples-override.ts
@@ -1,4 +1,4 @@
-import { yamlAndJsonSyncReader } from '../../utils.js';
+import { resolveRelativePath, yamlAndJsonSyncReader } from '../../utils.js';
 import { isRef } from '../../ref-utils.js';
 
 import type { Oas3Decorator } from '../../visitors.js';
@@ -35,9 +35,12 @@ export const MediaTypeExamplesOverride: Oas3Decorator = ({ operationIds }) => {
             resolvedResponse.content = resolvedResponse.content ? resolvedResponse.content : {};
 
             Object.keys(properties.responses[responseCode]).forEach((mimeType) => {
+              const filePath = properties.responses[responseCode][mimeType];
               resolvedResponse.content![mimeType] = {
                 ...resolvedResponse.content![mimeType],
-                examples: yamlAndJsonSyncReader(properties.responses[responseCode][mimeType]),
+                examples: yamlAndJsonSyncReader(
+                  resolveRelativePath(filePath, ctx.config?.configPath)
+                ),
               };
             });
 
@@ -58,9 +61,12 @@ export const MediaTypeExamplesOverride: Oas3Decorator = ({ operationIds }) => {
           resolvedRequest.content = resolvedRequest.content ? resolvedRequest.content : {};
 
           Object.keys(properties.request).forEach((mimeType) => {
+            const filePath = properties.request[mimeType];
             resolvedRequest.content[mimeType] = {
               ...resolvedRequest.content[mimeType],
-              examples: yamlAndJsonSyncReader(properties.request[mimeType]),
+              examples: yamlAndJsonSyncReader(
+                resolveRelativePath(filePath, ctx.config?.configPath)
+              ),
             };
           });
           operation.requestBody = resolvedRequest;
diff --git a/packages/core/src/decorators/common/operation-description-override.ts b/packages/core/src/decorators/common/operation-description-override.ts
@@ -1,4 +1,4 @@
-import { readFileAsStringSync } from '../../utils.js';
+import { readFileAsStringSync, resolveRelativePath } from '../../utils.js';
 
 import type { Oas3Decorator, Oas2Decorator } from '../../visitors.js';
 import type { Oas2Operation } from '../../typings/swagger.js';
@@ -8,7 +8,7 @@ import type { UserContext } from '../../walk.js';
 export const OperationDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ operationIds }) => {
   return {
     Operation: {
-      leave(operation: Oas2Operation | Oas3Operation, { report, location }: UserContext) {
+      leave(operation: Oas2Operation | Oas3Operation, { report, location, config }: UserContext) {
         if (!operation.operationId) return;
         if (!operationIds)
           throw new Error(
@@ -17,7 +17,10 @@ export const OperationDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ op
         const operationId = operation.operationId;
         if (operationIds[operationId]) {
           try {
-            operation.description = readFileAsStringSync(operationIds[operationId]);
+            const filePath = operationIds[operationId];
+            operation.description = readFileAsStringSync(
+              resolveRelativePath(filePath, config?.configPath)
+            );
           } catch (e) {
             report({
               message: `Failed to read markdown override file for operation "${operationId}".\n${e.message}`,
diff --git a/packages/core/src/decorators/common/tag-description-override.ts b/packages/core/src/decorators/common/tag-description-override.ts
@@ -1,19 +1,22 @@
-import { readFileAsStringSync } from '../../utils.js';
+import { readFileAsStringSync, resolveRelativePath } from '../../utils.js';
 
 import type { Oas3Decorator, Oas2Decorator } from '../../visitors.js';
 import type { UserContext } from '../../walk.js';
 
 export const TagDescriptionOverride: Oas3Decorator | Oas2Decorator = ({ tagNames }) => {
   return {
     Tag: {
-      leave(tag, { report }: UserContext) {
+      leave(tag, { report, config }: UserContext) {
         if (!tagNames)
           throw new Error(
             `Parameter "tagNames" is not provided for "tag-description-override" rule`
           );
-        if (tagNames[tag.name]) {
+        const filePath = tagNames[tag.name];
+        if (filePath) {
           try {
-            tag.description = readFileAsStringSync(tagNames[tag.name]);
+            tag.description = readFileAsStringSync(
+              resolveRelativePath(filePath, config?.configPath)
+            );
           } catch (e) {
             report({
               message: `Failed to read markdown override file for tag "${tag.name}".\n${e.message}`,
diff --git a/packages/core/src/lint.ts b/packages/core/src/lint.ts
@@ -82,7 +82,8 @@ export async function lintDocument(opts: {
 
   const ctx: WalkContext = {
     problems: [],
-    oasVersion: specVersion,
+    specVersion,
+    config,
     visitorsData: {},
   };
 
@@ -136,7 +137,8 @@ export async function lintConfig(opts: {
 
   const ctx: WalkContext = {
     problems: [],
-    oasVersion: 'oas3_0', // TODO: use config-specific version; rename `oasVersion`
+    specVersion: 'oas3_0', // TODO: use config-specific version
+    config,
     visitorsData: {},
   };
 
diff --git a/packages/core/src/rules/common/scalar-property-missing-example.ts b/packages/core/src/rules/common/scalar-property-missing-example.ts
@@ -11,7 +11,7 @@ export const ScalarPropertyMissingExample: Oas3Rule | Oas2Rule = () => {
   return {
     SchemaProperties(
       properties: { [name: string]: Oas2Schema | Oas3Schema | Oas3_1Schema },
-      { report, location, oasVersion, resolve }: UserContext
+      { report, location, specVersion, resolve }: UserContext
     ) {
       for (const propName of Object.keys(properties)) {
         const propSchema = resolve(getOwn(properties, propName)).node;
@@ -26,7 +26,7 @@ export const ScalarPropertyMissingExample: Oas3Rule | Oas2Rule = () => {
         ) {
           report({
             message: `Scalar property should have "example"${
-              oasVersion === 'oas3_1' ? ' or "examples"' : ''
+              specVersion === 'oas3_1' ? ' or "examples"' : ''
             } defined.`,
             location: location.child(propName).key(),
           });
diff --git a/packages/core/src/utils.ts b/packages/core/src/utils.ts
@@ -4,6 +4,7 @@ import { minimatch } from 'minimatch';
 import pluralizeOne from 'pluralize';
 import { parseYaml } from './js-yaml/index.js';
 import { env } from './env.js';
+import { isAbsoluteUrl } from './ref-utils.js';
 
 import type { HttpResolveConfig } from './config/index.js';
 import type { UserContext } from './walk.js';
@@ -298,3 +299,10 @@ export function omit<O extends object, K extends keyof O>(obj: O, keys: K[]): Om
 
   return result;
 }
+
+export function resolveRelativePath(filePath: string, base?: string) {
+  if (isAbsoluteUrl(filePath) || base === undefined) {
+    return filePath;
+  }
+  return path.resolve(path.dirname(base), filePath);
+}
diff --git a/packages/core/src/walk.ts b/packages/core/src/walk.ts
