feat(oas): add ref name to analyzer (#918)

| 🚥 Resolves RM-11499 |
| :------------------- |

## 🧰 Changes

Add a check to the analyzer if the definition previously had a reference
in it. Once we dereference a file we add `x-readme-ref-name` as a way to
keep track of the previous name. This surfaces if that extension exists
in the definition being analyzed.

## 🧬 QA & Testing

Tests should pass, and analyzer should have a new `x-readme-ref-name`
field being returned.

---------

Co-authored-by: Jon Ursenbach <erunion@users.noreply.github.com>

packages/oas/src/analyzer/index.ts

@@ -30,6 +30,7 @@ export default async function analyzer(definition: OASDocument): Promise<OASAnal
   const explorerDisabled = README_QUERIES.explorerDisabled(definition);
   const staticHeaders = README_QUERIES.staticHeaders(definition);
   const rawBody = README_QUERIES.rawBody(definition);
+  const refNames = README_QUERIES.refNames(definition);
 
   const analysis: OASAnalysis = {
     general: {
@@ -113,6 +114,10 @@ export default async function analyzer(definition: OASDocument): Promise<OASAnal
         present: !!codeSampleLanguages.length,
         locations: codeSampleLanguages,
       },
+      'x-readme-ref-name': {
+        present: !!refNames.length,
+        locations: refNames,
+      },
     },
   };
 

packages/oas/src/analyzer/queries/readme.ts

@@ -131,3 +131,11 @@ export function staticHeaders(definition: OASDocument) {
     })
     .map(res => refizePointer(res.pointer));
 }
+
+/**
+ * Determine if a given API definition previously had references by checking if we added the
+ * `x-readme-ref-name` extension after dereferencing.
+ */
+export function refNames(definition: OASDocument) {
+  return query(["$..['x-readme-ref-name']"], definition).map(res => refizePointer(res.pointer));
+}

packages/oas/src/analyzer/types.ts

@@ -33,6 +33,12 @@ export interface OASAnalysis {
      */
     raw_body?: OASAnalysisFeature;
     'x-default': OASAnalysisFeature;
+
+    /**
+     * x-readme-ref-name is added by our tooling after dereferencing so our UI can display the
+     * reference name.
+     */
+    'x-readme-ref-name': OASAnalysisFeature;
     'x-readme.code-samples': OASAnalysisFeature;
     'x-readme.explorer-enabled': OASAnalysisFeature;
     'x-readme.headers': OASAnalysisFeature;

packages/oas/test/analyzer/__snapshots__/index.test.ts.snap

@@ -88,6 +88,10 @@ exports[`analyzer > should should analyzer an OpenAPI definition 1`] = `
       "locations": [],
       "present": false,
     },
+    "x-readme-ref-name": {
+      "locations": [],
+      "present": false,
+    },
     "x-readme.code-samples": {
       "locations": [],
       "present": false,

packages/oas/test/analyzer/queries/readme.test.ts

@@ -3,6 +3,7 @@ import type { OASDocument } from '../../../src/types.js';
 import { describe, beforeAll, expect, it } from 'vitest';
 
 import * as QUERIES from '../../../src/analyzer/queries/readme.js';
+import Oas from '../../../src/index.js';
 
 function loadSpec(r: any) {
   return r.default as unknown as OASDocument;
@@ -189,4 +190,20 @@ describe('analyzer queries (ReadMe)', () => {
       expect(QUERIES.authDefaults(petstore)).toHaveLength(0);
     });
   });
+
+  describe('`x-readme-ref-name` extension', () => {
+    it('should detect usage of `x-readme-ref-name` for defining reference names', () => {
+      const oas = Oas.init(petstore);
+      // Need to dereference it for this extension to be added
+      oas.dereference();
+      expect(QUERIES.refNames(oas.api)).toStrictEqual([
+        '#/components/schemas/ApiResponse/x-readme-ref-name',
+        '#/components/schemas/Category/x-readme-ref-name',
+        '#/components/schemas/Order/x-readme-ref-name',
+        '#/components/schemas/Pet/x-readme-ref-name',
+        '#/components/schemas/Tag/x-readme-ref-name',
+        '#/components/schemas/User/x-readme-ref-name',
+      ]);
+    });
+  });
 });