test(orval): cover double-linked cross-file $ref chain (#1935) (#3409)

* test(orval): cover double-linked cross-file $ref chain (#1935)

* test(orval): align path key in #1935 fixture with userId path param

Make the standalone projects.yaml a valid OpenAPI document by changing
its path key from `/projects` to `/users/{userId}/projects` so the
declared `userId` path parameter matches the path template. Update the
root $ref accordingly to use the JSON Pointer / percent-encoded escape,
mirroring the existing issue-3380 fixture. No change to bundled output.

Author: wadakatu

packages/orval/src/import-specs.test.ts

@@ -908,6 +908,78 @@ describe('dereferenceExternalRefs', () => {
     expect(result).not.toHaveProperty('x-ext');
   });
 
+  // Regression test for https://github.com/orval-labs/orval/issues/1935
+  it('should resolve a barrel $ref that crosses into a second external doc', () => {
+    // The middle external doc ("barrel") only re-exports a schema as a $ref
+    // into a third external doc ("concrete"). The cross-doc rewrite in
+    // `replaceXExtRefs` must collapse the chain so the merged barrel schema
+    // ends up pointing at the resolved schema in the main spec, not at the
+    // raw `#/x-ext/concrete/...` ref it was bundled with.
+    const input = {
+      openapi: '3.0.3',
+      info: { title: 'Demo', version: '0.0.0' },
+      paths: {},
+      components: {
+        schemas: {
+          UserProjectDTO: {
+            $ref: '#/x-ext/barrel/components/schemas/UserProjectDTO',
+          },
+        },
+      },
+      'x-ext': {
+        barrel: {
+          openapi: '3.0.3',
+          info: { title: 'Barrel', version: '0.0.0' },
+          components: {
+            schemas: {
+              UserProjectDTO: {
+                $ref: '#/x-ext/concrete/components/schemas/UserProject',
+              },
+            },
+          },
+        },
+        concrete: {
+          openapi: '3.0.3',
+          info: { title: 'Concrete', version: '0.0.0' },
+          components: {
+            schemas: {
+              UserProject: {
+                type: 'object',
+                required: ['id', 'title'],
+                properties: {
+                  id: { type: 'string' },
+                  title: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = dereferenceExternalRef(input) as OpenApiDocument;
+    const schemas = result.components?.schemas;
+
+    // Both ends of the chain are merged into the main spec.
+    expect(schemas?.UserProject).toEqual({
+      type: 'object',
+      required: ['id', 'title'],
+      properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+      },
+    });
+
+    // The barrel entry collapses to an internal $ref pointing at the
+    // resolved concrete schema — the x-ext hop must be rewritten, otherwise
+    // downstream resolveRef() throws "Ref not found".
+    expect(schemas?.UserProjectDTO).toEqual({
+      $ref: '#/components/schemas/UserProject',
+    });
+
+    expect(result).not.toHaveProperty('x-ext');
+  });
+
   // Regression test for https://github.com/orval-labs/orval/issues/394
   it('should resolve internal $ref inside an external parameter against the external doc', () => {
     const input = {

tests/__snapshots__/default/issue-1935-double-linked-ref/endpoints.ts

@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1935 - double-linked $ref
+ * OpenAPI spec version: 1.0.0
+ */
+import axios from 'axios';
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+
+import type { UserProject } from './model';
+
+/**
+ * @summary Retrieve all related projects for the userId
+ */
+export const getUserProjects = (
+  userId: string,
+  options?: AxiosRequestConfig,
+): Promise<AxiosResponse<UserProject[]>> => {
+  return axios.get(`/users/${userId}/projects`, options);
+};
+
+export type GetUserProjectsResult = AxiosResponse<UserProject[]>;

tests/__snapshots__/default/issue-1935-double-linked-ref/model/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1935 - double-linked $ref
+ * OpenAPI spec version: 1.0.0
+ */
+
+export * from './userProject';
+export * from './userProjectDTO';

tests/__snapshots__/default/issue-1935-double-linked-ref/model/userProject.ts

@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1935 - double-linked $ref
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserProject {
+  id: string;
+  title: string;
+  description?: string;
+}

tests/__snapshots__/default/issue-1935-double-linked-ref/model/userProjectDTO.ts

@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.11.0 🍺
+ * Do not edit manually.
+ * Issue 1935 - double-linked $ref
+ * OpenAPI spec version: 1.0.0
+ */
+import type { UserProject } from './userProject';
+
+export type UserProjectDTO = UserProject;

tests/api-generation.spec.ts

@@ -297,6 +297,47 @@ test('default issue-3380 resolves external path-item $refs with escaped pointers
   expect(content).toContain('`/pets/${petId}`');
 });
 
+test('default issue-1935 resolves a $ref chain across three external files', async () => {
+  // Regression for #1935: an operation defined in one file (path-item $ref)
+  // whose response schema $refs into a second file that itself only
+  // re-exports the schema via a $ref to a third concrete-schema file used
+  // to abort with `Ref not found: ../schemas/index.yaml#/components/schemas/
+  // UserProjectDTO`. The bundler must follow the chain through both hops so
+  // the operation resolves to the third file's concrete object schema. Keep
+  // this focused assertion alongside the snapshot so #1935 fails with a
+  // targeted message instead of a full-file snapshot diff.
+  const root = (file: string) =>
+    readFile(
+      generated('default', 'issue-1935-double-linked-ref', file),
+      'utf8',
+    );
+  const model = (file: string) =>
+    readFile(
+      generated('default', 'issue-1935-double-linked-ref', 'model', file),
+      'utf8',
+    );
+
+  // The operation imports the concrete third-file schema (not the barrel
+  // alias) and uses it as the response item type.
+  const endpoints = await root('endpoints.ts');
+  expect(endpoints).toContain("import type { UserProject } from './model';");
+  expect(endpoints).toContain('Promise<AxiosResponse<UserProject[]>>');
+
+  // The concrete schema from the third file is emitted as an interface.
+  const userProject = await model('userProject.ts');
+  expect(userProject).toContain('export interface UserProject {');
+  expect(userProject).toContain('id: string;');
+  expect(userProject).toContain('title: string;');
+
+  // The barrel re-export collapses to a type alias pointing at the resolved
+  // schema — proving the second hop of the chain was followed.
+  const userProjectDTO = await model('userProjectDTO.ts');
+  expect(userProjectDTO).toContain(
+    "import type { UserProject } from './userProject';",
+  );
+  expect(userProjectDTO).toContain('export type UserProjectDTO = UserProject;');
+});
+
 test('react-query issue-1522 passes the enabled option into the queryOptions mutator', async () => {
   // Regression for #1522: when `allParamsOptional` and a custom `queryOptions`
   // mutator are combined, the auto-generated `enabled` guard (which disables

tests/configs/default.config.ts

@@ -705,6 +705,17 @@ export default defineConfig({
       target: '../specifications/issue-3380/issue-3380.yaml',
     },
   },
+  'issue-1935-double-linked-ref': {
+    output: {
+      target: '../generated/default/issue-1935-double-linked-ref/endpoints.ts',
+      schemas: '../generated/default/issue-1935-double-linked-ref/model',
+      clean: true,
+      formatter: 'prettier',
+    },
+    input: {
+      target: '../specifications/issue-1935/issue-1935.yaml',
+    },
+  },
   'boolean-discriminator': {
     output: {
       target: '../generated/default/boolean-discriminator/endpoints.ts',

tests/specifications/issue-1935/issue-1935.yaml

@@ -0,0 +1,13 @@
+openapi: 3.1.0
+info:
+  title: Issue 1935 - double-linked $ref
+  version: 1.0.0
+
+# Regression for #1935: a $ref chain that crosses three external files.
+# - paths.<...>      → external path-item file (path/projects.yaml)
+# - that file's response schema → external schemas barrel (schemas/index.yaml)
+# - the barrel re-exports         → external concrete schema file (schemas/UserProjectDTO.yaml)
+paths:
+  '/users/{userId}/projects':
+    $ref: './path/projects.yaml#/paths/~1users~1%7BuserId%7D~1projects'
+components: {}

tests/specifications/issue-1935/parameters/userId.yaml

@@ -0,0 +1,13 @@
+openapi: 3.1.0
+info:
+  title: userId path parameter
+  version: 1.0.0
+paths: {}
+components:
+  parameters:
+    userId:
+      name: userId
+      in: path
+      required: true
+      schema:
+        type: string

tests/specifications/issue-1935/path/projects.yaml

@@ -0,0 +1,22 @@
+openapi: 3.1.0
+info:
+  title: User Projects
+  version: 1.0.0
+paths:
+  /users/{userId}/projects:
+    get:
+      operationId: getUserProjects
+      summary: Retrieve all related projects for the userId
+      parameters:
+        - $ref: '../parameters/userId.yaml#/components/parameters/userId'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '../schemas/index.yaml#/components/schemas/UserProjectDTO'
+        '500':
+          description: Error