fix: keep sibling keywords when a referenced schema has a root-level $ref

.changeset/root-ref-sibling-keywords.md

@@ -0,0 +1,6 @@
+---
+'@redocly/openapi-core': minor
+'@redocly/cli': minor
+---
+
+Fixed the `bundle` command losing schema keywords (such as `title`, `properties`, or `required`) written next to a `$ref` when the referenced schemas started with their own `$ref`.

packages/core/src/__tests__/bundle.test.ts

@@ -976,6 +976,140 @@ describe('sibling $ref resolution by spec', () => {
     expect(problems).toHaveLength(0);
     expect(res.parsed).toMatchSnapshot();
   });
+
+  it('should keep sibling keywords when an external schema file has a root-level $ref', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/sibling-refs/openapi-root-ref-siblings.yaml'),
+    });
+
+    expect(problems).toHaveLength(0);
+    expect((res.parsed as any).components.schemas.BadRequest).toEqual({
+      title: 'Bad request',
+      type: 'object',
+      $ref: '#/components/schemas/BaseProblem',
+      properties: {
+        status: { type: 'integer', minimum: 400, maximum: 400 },
+      },
+      required: ['status'],
+    });
+    expect(
+      (res.parsed as any).paths['/demo'].get.responses['400'].content['application/json'].schema
+    ).toEqual({ $ref: '#/components/schemas/BadRequest' });
+  });
+
+  it('should bundle refs inside $ref siblings that collide with resolved schema keys', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/sibling-refs/openapi-sibling-collision.yaml'),
+    });
+
+    expect(problems).toHaveLength(0);
+    const schema = (res.parsed as any).paths['/demo'].get.responses['200'].content[
+      'application/json'
+    ].schema;
+    expect(schema).toEqual({
+      $ref: '#/components/schemas/Test',
+      properties: {
+        second: { $ref: '#/components/schemas/BaseProblem' },
+      },
+    });
+    expect((res.parsed as any).components.schemas.BaseProblem).toEqual({
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+      },
+    });
+  });
+
+  it('should not crash when a $ref with siblings resolves to null', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          title: Test
+          version: 1.0.0
+        paths: {}
+        components:
+          schemas:
+            Nullish:
+              $ref: '#/components/schemas/Target'
+              description: composed over null
+            Target: null
+      `,
+      ''
+    );
+
+    const { bundle: res, problems } = await bundleDocument({
+      document,
+      externalRefResolver: new BaseResolver(),
+      config: await createConfig({}),
+      types: Oas3Types,
+    });
+
+    expect(problems).toHaveLength(0);
+    expect((res.parsed as any).components.schemas.Nullish).toEqual({
+      $ref: '#/components/schemas/Target',
+      description: 'composed over null',
+    });
+  });
+
+  it('should bundle discriminator mappings that point to composed schemas', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/sibling-refs/openapi-discriminator-mapping.yaml'),
+    });
+
+    expect(problems).toHaveLength(0);
+    const schemas = (res.parsed as any).components.schemas;
+    expect(schemas.Pet.discriminator.mapping.cat).toEqual('#/components/schemas/Cat');
+    expect(schemas.Cat).toEqual({
+      title: 'Cat',
+      $ref: '#/components/schemas/BaseProblem',
+      properties: {
+        toy: { $ref: '#/components/schemas/Toy' },
+      },
+    });
+    expect(schemas.Toy).toEqual({ type: 'string' });
+  });
+
+  it('should keep referenced composed schemas when removing unused components', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/sibling-refs/openapi-root-ref-siblings.yaml'),
+      removeUnusedComponents: true,
+    });
+
+    expect(problems).toHaveLength(0);
+    expect(Object.keys((res.parsed as any).components.schemas).sort()).toEqual([
+      'BadRequest',
+      'BaseProblem',
+    ]);
+  });
+
+  it('should keep sibling keywords when a referenced component has a root-level $ref', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/sibling-refs/openapi-root-ref-siblings.yaml'),
+    });
+
+    expect(problems).toHaveLength(0);
+    const schemas = (res.parsed as any).components.schemas;
+    expect(schemas.Problem).toEqual({
+      $ref: '#/components/schemas/ProblemAlias',
+      description: 'Composed problem',
+    });
+    expect(schemas.ProblemAlias).toEqual({
+      $ref: '#/components/schemas/BaseProblem',
+      title: 'Problem alias',
+    });
+    expect(schemas.BaseProblem).toEqual({
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+      },
+    });
+  });
 });
 
 describe('bundle with --component-names-strategy title', () => {

packages/core/src/__tests__/fixtures/sibling-refs/openapi-discriminator-mapping.yaml

@@ -0,0 +1,23 @@
+openapi: 3.1.0
+info:
+  title: Discriminator mapping to a composed schema
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      discriminator:
+        propertyName: type
+        mapping:
+          cat: ./schemas/Cat.yaml

packages/core/src/__tests__/fixtures/sibling-refs/openapi-root-ref-siblings.yaml

@@ -0,0 +1,24 @@
+openapi: 3.1.0
+info:
+  title: Root-level $ref with sibling keywords
+  version: 1.0.0
+paths:
+  /demo:
+    get:
+      responses:
+        '400':
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: ./schemas/BadRequest.yaml
+components:
+  schemas:
+    BadRequest:
+      $ref: ./schemas/BadRequest.yaml
+    ProblemAlias:
+      $ref: ./schemas/BaseProblem.yaml
+      title: Problem alias
+    Problem:
+      $ref: '#/components/schemas/ProblemAlias'
+      description: Composed problem

packages/core/src/__tests__/fixtures/sibling-refs/openapi-sibling-collision.yaml

@@ -0,0 +1,25 @@
+openapi: 3.1.0
+info:
+  title: Sibling properties colliding with the referenced schema keys
+  version: 1.0.0
+paths:
+  /demo:
+    get:
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Test'
+                properties:
+                  second:
+                    $ref: ./schemas/BaseProblem.yaml
+components:
+  schemas:
+    Test:
+      type: object
+      title: Test schema
+      properties:
+        first:
+          type: integer

packages/core/src/__tests__/fixtures/sibling-refs/schemas/BadRequest.yaml

@@ -0,0 +1,10 @@
+title: Bad request
+type: object
+$ref: ./BaseProblem.yaml
+properties:
+  status:
+    type: integer
+    minimum: 400
+    maximum: 400
+required:
+  - status

packages/core/src/__tests__/fixtures/sibling-refs/schemas/BaseProblem.yaml

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

packages/core/src/__tests__/fixtures/sibling-refs/schemas/Cat.yaml

@@ -0,0 +1,5 @@
+title: Cat
+$ref: ./BaseProblem.yaml
+properties:
+  toy:
+    $ref: ./Toy.yaml

packages/core/src/__tests__/fixtures/sibling-refs/schemas/Toy.yaml

@@ -0,0 +1 @@
+type: string

packages/core/src/__tests__/resolve.test.ts

@@ -411,6 +411,72 @@ describe('collect refs', () => {
     expect(Array.from(resolvedRefs.values()).pop()!.node).toEqual({ type: 'string' });
   });
 
+  it('should record a $ref with sibling keys as a chain hop while following transitive refs', async () => {
+    const rootDocument = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          $ref: "#/aliased"
+        aliased:
+          $ref: '#/target'
+          description: alias with sibling
+        target:
+          contact: {}
+      `,
+      'foobar.yaml'
+    );
+
+    const resolvedRefs = await resolveDocument({
+      rootDocument,
+      externalRefResolver: new BaseResolver(),
+      rootType: normalizeTypes(Oas3Types).Root,
+    });
+
+    const aliasedRef = resolvedRefs.get('foobar.yaml::#/aliased')!;
+    expect(aliasedRef.node).toEqual({ contact: {} });
+    expect(aliasedRef.chain).toHaveLength(1);
+    expect(aliasedRef.chain![0].node).toEqual({
+      $ref: '#/target',
+      description: 'alias with sibling',
+    });
+    expect(aliasedRef.chain![0].location.pointer).toEqual('#/aliased');
+    expect(resolvedRefs.get('foobar.yaml::#/target')!.node).toEqual({ contact: {} });
+  });
+
+  it('should record each level of a multi-hop composed chain independently', async () => {
+    const rootDocument = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        info:
+          $ref: "#/first"
+        first:
+          $ref: '#/second'
+          description: first hop
+        second:
+          $ref: '#/target'
+          description: second hop
+        target:
+          contact: {}
+      `,
+      'foobar.yaml'
+    );
+
+    const resolvedRefs = await resolveDocument({
+      rootDocument,
+      externalRefResolver: new BaseResolver(),
+      rootType: normalizeTypes(Oas3Types).Root,
+    });
+
+    const outerRef = resolvedRefs.get('foobar.yaml::#/first')!;
+    expect(outerRef.node).toEqual({ contact: {} });
+    expect(outerRef.chain!.map((hop) => hop.location.pointer)).toEqual(['#/first', '#/second']);
+
+    // the inner resolution must not be polluted by outer hops
+    const innerRef = resolvedRefs.get('foobar.yaml::#/second')!;
+    expect(innerRef.node).toEqual({ contact: {} });
+    expect(innerRef.chain!.map((hop) => hop.location.pointer)).toEqual(['#/second']);
+  });
+
   it('should throw error if ref is folder', async () => {
     const cwd = path.join(__dirname, 'fixtures/resolve');
     const rootDocument = parseYamlToDocument(