oas 20.0.1 → 20.1.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 20.1.0 (2022-12-05)
+
+* feat: new OpenAPI definition analyzer library (#722) ([5e0d563](https://github.com/readmeio/oas/commit/5e0d563)), closes [#722](https://github.com/readmeio/oas/issues/722)
+* docs: adding a ReadMe badge to the readme (#720) ([919a887](https://github.com/readmeio/oas/commit/919a887)), closes [#720](https://github.com/readmeio/oas/issues/720)
+* fix: keywords in package.json ([568e068](https://github.com/readmeio/oas/commit/568e068))
+* fix: reversing the logic order for common summary+descriptions (#721) ([c7d0015](https://github.com/readmeio/oas/commit/c7d0015)), closes [#721](https://github.com/readmeio/oas/issues/721)
+* chore: swapping out common param tests with a better spec ([ef54f63](https://github.com/readmeio/oas/commit/ef54f63))
+* chore: update out of date dependencies (#719) ([23632ba](https://github.com/readmeio/oas/commit/23632ba)), closes [#719](https://github.com/readmeio/oas/issues/719)
+
+
+
 ## <small>20.0.1 (2022-11-01)</small>
 
 * fix: issue with non-camelCase operationID generation (#708) ([7af590c](https://github.com/readmeio/oas/commit/7af590c)), closes [#708](https://github.com/readmeio/oas/issues/708)

package/README.md

@@ -9,10 +9,14 @@
 </p>
 
 <p align="center">
-  <a href="https://npm.im/oas"><img src="https://img.shields.io/npm/v/oas.svg?style=for-the-badge" alt="NPM Version"></a>
-  <a href="https://npm.im/oas"><img src="https://img.shields.io/node/v/oas.svg?style=for-the-badge" alt="Node Version"></a>
-  <a href="https://npm.im/oas"><img src="https://img.shields.io/npm/l/oas.svg?style=for-the-badge" alt="MIT License"></a>
-  <a href="https://github.com/readmeio/oas"><img src="https://img.shields.io/github/workflow/status/readmeio/oas/CI.svg?style=for-the-badge" alt="Build status"></a>
+  <a href="https://npm.im/oas"><img src="https://img.shields.io/npm/v/oas.svg?style=for-the-badge" alt="NPM Version" /></a>
+  <a href="https://npm.im/oas"><img src="https://img.shields.io/node/v/oas.svg?style=for-the-badge" alt="Node Version" /></a>
+  <a href="https://npm.im/oas"><img src="https://img.shields.io/npm/l/oas.svg?style=for-the-badge" alt="MIT License" /></a>
+  <a href="https://github.com/readmeio/oas"><img src="https://img.shields.io/github/workflow/status/readmeio/oas/CI.svg?style=for-the-badge" alt="Build status" /></a>
+</p>
+
+<p align="center">
+  <a href="https://readme.com"><img src="https://raw.githubusercontent.com/readmeio/.github/main/oss-badge.svg" /></a>
 </p>
 
 `oas` is the library that we've built at [ReadMe](https://readme.com) for powering everything we do related to [OpenAPI](https://www.openapis.org/); from our [Reference Guides](https://readme.com/documentation), to our [Metrics product](https://readme.com/metrics) or to other in-house tooling like [code generation](https://npm.im/@readme/oas-to-snippet), [request execution](https://npm.im/@readme/oas-to-har), and [SDK code generation](https://api.readme.dev/).

package/dist/analyzer/index.d.ts

@@ -0,0 +1,53 @@
+import type { OASDocument } from '../rmoas.types';
+interface OASAnalysisFeature {
+    present: boolean;
+    locations: number | string[];
+}
+interface OASAnalysisGeneral {
+    name: string;
+    found: number | string[];
+}
+export interface OASAnalysis {
+    general: {
+        mediaTypes: OASAnalysisGeneral;
+        operationTotal: OASAnalysisGeneral;
+        securityTypes: OASAnalysisGeneral;
+    };
+    openapi: {
+        additionalProperties: OASAnalysisFeature;
+        callbacks: OASAnalysisFeature;
+        circularRefs: OASAnalysisFeature;
+        discriminators: OASAnalysisFeature;
+        links: OASAnalysisFeature;
+        style: OASAnalysisFeature;
+        polymorphism: OASAnalysisFeature;
+        serverVariables: OASAnalysisFeature;
+        webhooks: OASAnalysisFeature;
+        xml: OASAnalysisFeature;
+    };
+    readme: {
+        'x-default': OASAnalysisFeature;
+        'x-readme.headers': OASAnalysisFeature;
+        'x-readme.proxy-enabled': OASAnalysisFeature;
+        'x-readme.samples-languages'?: OASAnalysisFeature;
+        'x-readme.code-samples': OASAnalysisFeature;
+        'x-readme.explorer-enabled': OASAnalysisFeature;
+        /**
+         * This extension is deprecated.
+         */
+        'x-readme.samples-enabled'?: OASAnalysisFeature;
+        /**
+         * RAW_BODY is specific to our Manual API editor and we don't recommend anyone writing their
+         * own API definition should use it so this is considered deprecated.
+         */
+        raw_body?: OASAnalysisFeature;
+    };
+}
+/**
+ * Analyze a given OpenAPI or Swagger definition for any OpenAPI, JSON Schema, and ReadMe-specific
+ * feature uses it may contain.
+ *
+ * @todo this might be worth moving into the `oas` package at some point
+ */
+export default function analyzer(definition: OASDocument): Promise<OASAnalysis>;
+export {};

package/dist/analyzer/index.js

@@ -0,0 +1,200 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+exports.__esModule = true;
+var OPENAPI_QUERIES = __importStar(require("./queries/openapi"));
+var README_QUERIES = __importStar(require("./queries/readme"));
+/**
+ * Analyze a given OpenAPI or Swagger definition for any OpenAPI, JSON Schema, and ReadMe-specific
+ * feature uses it may contain.
+ *
+ * @todo this might be worth moving into the `oas` package at some point
+ */
+function analyzer(definition) {
+    return __awaiter(this, void 0, void 0, function () {
+        var additionalProperties, callbacks, circularRefs, discriminators, links, parameterSerialization, polymorphism, serverVariables, webhooks, xml, authDefaults, codeSampleLanguages, customCodeSamples, codeSamplesDisabled, disabledCorsProxy, explorerDisabled, staticHeaders, rawBody, analysis;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    additionalProperties = OPENAPI_QUERIES.additionalProperties(definition);
+                    callbacks = OPENAPI_QUERIES.callbacks(definition);
+                    return [4 /*yield*/, OPENAPI_QUERIES.circularRefs(definition)];
+                case 1:
+                    circularRefs = _a.sent();
+                    discriminators = OPENAPI_QUERIES.discriminators(definition);
+                    links = OPENAPI_QUERIES.links(definition);
+                    parameterSerialization = OPENAPI_QUERIES.parameterSerialization(definition);
+                    polymorphism = OPENAPI_QUERIES.polymorphism(definition);
+                    serverVariables = OPENAPI_QUERIES.serverVariables(definition);
+                    webhooks = OPENAPI_QUERIES.webhooks(definition);
+                    xml = OPENAPI_QUERIES.xml(definition);
+                    authDefaults = README_QUERIES.authDefaults(definition);
+                    codeSampleLanguages = README_QUERIES.codeSampleLanguages(definition);
+                    customCodeSamples = README_QUERIES.customCodeSamples(definition);
+                    codeSamplesDisabled = README_QUERIES.codeSamplesDisabled(definition);
+                    disabledCorsProxy = README_QUERIES.corsProxyDisabled(definition);
+                    explorerDisabled = README_QUERIES.explorerDisabled(definition);
+                    staticHeaders = README_QUERIES.staticHeaders(definition);
+                    rawBody = README_QUERIES.rawBody(definition);
+                    analysis = {
+                        general: {
+                            mediaTypes: {
+                                name: 'Media Type',
+                                found: OPENAPI_QUERIES.mediaTypes(definition)
+                            },
+                            operationTotal: {
+                                name: 'Operation',
+                                found: OPENAPI_QUERIES.totalOperations(definition)
+                            },
+                            securityTypes: {
+                                name: 'Security Type',
+                                found: OPENAPI_QUERIES.securityTypes(definition)
+                            }
+                        },
+                        openapi: {
+                            additionalProperties: {
+                                present: !!additionalProperties.length,
+                                locations: additionalProperties
+                            },
+                            callbacks: {
+                                present: !!callbacks.length,
+                                locations: callbacks
+                            },
+                            circularRefs: {
+                                present: !!circularRefs.length,
+                                locations: circularRefs
+                            },
+                            discriminators: {
+                                present: !!discriminators.length,
+                                locations: discriminators
+                            },
+                            links: {
+                                present: !!links.length,
+                                locations: links
+                            },
+                            style: {
+                                present: !!parameterSerialization.length,
+                                locations: parameterSerialization
+                            },
+                            polymorphism: {
+                                present: !!polymorphism.length,
+                                locations: polymorphism
+                            },
+                            serverVariables: {
+                                present: !!serverVariables.length,
+                                locations: serverVariables
+                            },
+                            webhooks: {
+                                present: !!webhooks.length,
+                                locations: webhooks
+                            },
+                            xml: {
+                                present: !!xml.length,
+                                locations: xml
+                            }
+                        },
+                        readme: {
+                            'x-default': {
+                                present: !!authDefaults.length,
+                                locations: authDefaults
+                            },
+                            'x-readme.code-samples': {
+                                present: !!customCodeSamples.length,
+                                locations: customCodeSamples
+                            },
+                            'x-readme.headers': {
+                                present: !!staticHeaders.length,
+                                locations: staticHeaders
+                            },
+                            'x-readme.explorer-enabled': {
+                                present: !!explorerDisabled.length,
+                                locations: explorerDisabled
+                            },
+                            'x-readme.proxy-enabled': {
+                                present: !!disabledCorsProxy.length,
+                                locations: disabledCorsProxy
+                            },
+                            'x-readme.samples-languages': {
+                                present: !!codeSampleLanguages.length,
+                                locations: codeSampleLanguages
+                            }
+                        }
+                    };
+                    // We should only surface analysis for deprecated features and extensions if they have them as
+                    // there's no reason to give them information about something they can't use and should no longer
+                    // know about.
+                    if (codeSamplesDisabled.length) {
+                        analysis.readme['x-readme.samples-enabled'] = {
+                            present: !!codeSamplesDisabled.length,
+                            locations: codeSamplesDisabled
+                        };
+                    }
+                    if (rawBody.length) {
+                        analysis.readme.raw_body = {
+                            present: !!rawBody.length,
+                            locations: rawBody
+                        };
+                    }
+                    return [2 /*return*/, analysis];
+            }
+        });
+    });
+}
+exports["default"] = analyzer;

package/dist/analyzer/queries/openapi.d.ts

@@ -0,0 +1,94 @@
+import type { OASDocument } from '../../rmoas.types';
+/**
+ * Determine if a given API definition uses the `additionalProperties` schema property.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object}
+ */
+export declare function additionalProperties(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition utilizes `callbacks`.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callbackObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject}
+ */
+export declare function callbacks(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition has circular refs.
+ *
+ * @todo improve the accuracy of this query
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object}
+ */
+export declare function circularRefs(definition: OASDocument): Promise<string[]>;
+/**
+ * Determine if a given API definition utilizes discriminators.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#discriminatorObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminatorObject}
+ */
+export declare function discriminators(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition utilizes `links`.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#linkObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#linkObject}
+ */
+export declare function links(definition: OASDocument): string[];
+/**
+ * Determine all of the available media types used within an API definition.
+ *
+ * @todo This query currently picks up false positives if there is an object named `content`.
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#request-body-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#request-body-object}
+ */
+export declare function mediaTypes(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition uses parameter serialization.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object}
+ */
+export declare function parameterSerialization(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition utilizes schema polymorphism and/of interitance.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object}
+ */
+export declare function polymorphism(definition: OASDocument): string[];
+/**
+ * Determine every kind of security type that a given API definition has documented.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#securitySchemeObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject}
+ */
+export declare function securityTypes(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition utilizes server variables.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverVariableObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject}
+ */
+export declare function serverVariables(definition: OASDocument): string[];
+/**
+ * Determine how many operations are defined in a given API definition.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operationObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject}
+ */
+export declare function totalOperations(definition: OASDocument): number;
+/**
+ * Determine if a given API definition utilizes `webhooks` support in OpenAPI 3.1.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasObject}
+ */
+export declare function webhooks(definition: OASDocument): string[];
+/**
+ * Determine if a given API definition has XML schemas, payloads, or responses.
+ *
+ * @todo detect `+xml` media types
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#xmlObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#xmlObject}
+ */
+export declare function xml(definition: OASDocument): string[];

package/dist/analyzer/queries/openapi.js

@@ -0,0 +1,222 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+exports.xml = exports.webhooks = exports.totalOperations = exports.serverVariables = exports.securityTypes = exports.polymorphism = exports.parameterSerialization = exports.mediaTypes = exports.links = exports.discriminators = exports.circularRefs = exports.callbacks = exports.additionalProperties = void 0;
+var __1 = __importDefault(require("../.."));
+var util_1 = require("../util");
+/**
+ * Determine if a given API definition uses the `additionalProperties` schema property.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object}
+ */
+function additionalProperties(definition) {
+    return (0, util_1.query)(['$..additionalProperties'], definition).map(function (res) { return res.pointer; });
+}
+exports.additionalProperties = additionalProperties;
+/**
+ * Determine if a given API definition utilizes `callbacks`.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callbackObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject}
+ */
+function callbacks(definition) {
+    return (0, util_1.query)(['$.components.callbacks', '$.paths..callbacks'], definition).map(function (res) { return res.pointer; });
+}
+exports.callbacks = callbacks;
+/**
+ * Determine if a given API definition has circular refs.
+ *
+ * @todo improve the accuracy of this query
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object}
+ */
+function circularRefs(definition) {
+    return __awaiter(this, void 0, void 0, function () {
+        var oas, results;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    oas = new __1["default"](JSON.parse(JSON.stringify(definition)));
+                    // Dereferencing will update the passed in variable, which we don't want to do, so we
+                    // instantiated `Oas` with a clone.
+                    return [4 /*yield*/, oas.dereference()];
+                case 1:
+                    // Dereferencing will update the passed in variable, which we don't want to do, so we
+                    // instantiated `Oas` with a clone.
+                    _a.sent();
+                    results = Array.from(new Set((0, util_1.query)(['$..$ref'], oas.api).map(function (res) { return res.value; })));
+                    results.sort();
+                    return [2 /*return*/, results];
+            }
+        });
+    });
+}
+exports.circularRefs = circularRefs;
+/**
+ * Determine if a given API definition utilizes discriminators.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#discriminatorObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminatorObject}
+ */
+function discriminators(definition) {
+    return (0, util_1.query)(['$..discriminator'], definition).map(function (res) { return res.pointer; });
+}
+exports.discriminators = discriminators;
+/**
+ * Determine if a given API definition utilizes `links`.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#linkObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#linkObject}
+ */
+function links(definition) {
+    return (0, util_1.query)(['$..links'], definition).map(function (res) { return res.pointer; });
+}
+exports.links = links;
+/**
+ * Determine all of the available media types used within an API definition.
+ *
+ * @todo This query currently picks up false positives if there is an object named `content`.
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#request-body-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#request-body-object}
+ */
+function mediaTypes(definition) {
+    var results = Array.from(new Set((0, util_1.query)(['$..paths..content'], definition)
+        .map(function (res) {
+        // This'll transform `results`, which looks like `[['application/json'], ['text/xml']]`
+        // into `['application/json', 'text/xml']`.
+        return Object.keys(res.value);
+    })
+        .flat()));
+    results.sort();
+    return results;
+}
+exports.mediaTypes = mediaTypes;
+/**
+ * Determine if a given API definition uses parameter serialization.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object}
+ */
+function parameterSerialization(definition) {
+    return (0, util_1.query)(['$..parameters[*].style^'], definition).map(function (res) { return res.pointer; });
+}
+exports.parameterSerialization = parameterSerialization;
+/**
+ * Determine if a given API definition utilizes schema polymorphism and/of interitance.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schema-object}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object}
+ */
+function polymorphism(definition) {
+    var results = Array.from(new Set((0, util_1.query)(['$..allOf^', '$..anyOf^', '$..oneOf^'], definition).map(function (res) { return res.pointer; })));
+    results.sort();
+    return results;
+}
+exports.polymorphism = polymorphism;
+/**
+ * Determine every kind of security type that a given API definition has documented.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#securitySchemeObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securitySchemeObject}
+ */
+function securityTypes(definition) {
+    return Array.from(new Set((0, util_1.query)(['$.components.securitySchemes..type'], definition).map(function (res) { return res.value; })));
+}
+exports.securityTypes = securityTypes;
+/**
+ * Determine if a given API definition utilizes server variables.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverVariableObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject}
+ */
+function serverVariables(definition) {
+    return (0, util_1.query)(['$.servers..variables^'], definition).map(function (res) { return res.pointer; });
+}
+exports.serverVariables = serverVariables;
+/**
+ * Determine how many operations are defined in a given API definition.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operationObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject}
+ */
+function totalOperations(definition) {
+    return (0, util_1.query)(['$..paths[*]'], definition)
+        .map(function (res) { return Object.keys(res.value); })
+        .flat().length;
+}
+exports.totalOperations = totalOperations;
+/**
+ * Determine if a given API definition utilizes `webhooks` support in OpenAPI 3.1.
+ *
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasObject}
+ */
+function webhooks(definition) {
+    return (0, util_1.query)(['$.webhooks[*]'], definition).map(function (res) { return res.pointer; });
+}
+exports.webhooks = webhooks;
+/**
+ * Determine if a given API definition has XML schemas, payloads, or responses.
+ *
+ * @todo detect `+xml` media types
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#xmlObject}
+ * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#xmlObject}
+ */
+function xml(definition) {
+    return (0, util_1.query)([
+        '$.components.schemas..xml^',
+        '$..parameters..xml^',
+        '$..requestBody..xml^',
+        "$..requestBody..['application/xml']",
+        "$..requestBody..['application/xml-external-parsed-entity']",
+        "$..requestBody..['application/xml-dtd']",
+        "$..requestBody..['text/xml']",
+        "$..requestBody..['text/xml-external-parsed-entity']",
+        '$..requestBody.content[?(@property.match(/\\+xml$/i))]',
+        "$..responses..['application/xml']",
+        "$..responses..['application/xml-external-parsed-entity']",
+        "$..responses..['application/xml-dtd']",
+        "$..responses..['text/xml']",
+        "$..responses..['text/xml-external-parsed-entity']",
+        '$..responses[*].content[?(@property.match(/\\+xml$/i))]',
+    ], definition).map(function (res) { return res.pointer; });
+}
+exports.xml = xml;