@redocly/openapi-core 0.0.0-snapshot.1737554067

package/README.md

@@ -0,0 +1,268 @@
+# openapi-core
+
+See https://github.com/Redocly/redocly-cli
+
+> [!IMPORTANT]
+> The `openapi-core package` is designed for our internal use; the interfaces that are considered safe to use are documented below.
+> Some of the function arguments are not documented below because they are not intended for public use.
+> Avoid using any functions or features that are not documented below.
+> If your use case is not documented below, please open an issue.
+
+## Basic usage
+
+### Lint from file system
+
+[Lint](https://redocly.com/docs/cli/commands/lint/) a file, optionally with a [config file](https://redocly.com/docs/cli/configuration/).
+
+```js
+import { lint, loadConfig } from '@redocly/openapi-core';
+
+const pathToApi = 'openapi.yaml';
+const config = await loadConfig({ configPath: 'optional/path/to/redocly.yaml' });
+const lintResults = await lint({ ref: pathToApi, config });
+```
+
+The content of `lintResults` describes any errors or warnings found during linting; an empty array means no problems were found.
+For each problem, the rule, severity, feedback message and a location object are provided.
+To learn more, [check the `lint` function section](#lint).
+
+### Bundle from file system
+
+[Bundle](https://redocly.com/docs/cli/commands/bundle/) an API description into a single structure, optionally with a [config file](https://redocly.com/docs/cli/configuration/).
+
+```js
+import { bundle, loadConfig } from '@redocly/openapi-core';
+
+const pathToApi = 'openapi.yaml';
+const config = await loadConfig({ configPath: 'optional/path/to/redocly.yaml' });
+const bundleResults = await bundle({ ref: pathToApi, config });
+```
+
+In `bundleResults`, the `bundle.parsed` field has the bundled API description.
+For more information, [check the `bundle` function section](#bundle).
+
+### Lint from memory with config
+
+[Lint](https://redocly.com/docs/cli/commands/lint/) an API description, with configuration defined. This is useful if the API description you're working with isn't a file on disk.
+
+```js
+import { lintFromString, createConfig, stringifyYaml } from '@redocly/openapi-core';
+
+const config = await createConfig(
+  {
+    extends: ['minimal'],
+    rules: {
+      'operation-description': 'error',
+    },
+  },
+  {
+    // optionally provide config path for resolving $refs and proper error locations
+    configPath: 'optional/path/to/redocly.yaml',
+  }
+);
+const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
+const lintResults = await lintFromString({
+  source,
+  // optionally pass path to the file for resolving $refs and proper error locations
+  absoluteRef: 'optional/path/to/openapi.yaml',
+  config,
+});
+```
+
+### Lint from memory with a custom plugin
+
+[Lint](https://redocly.com/docs/cli/commands/lint/) an API description, with configuration including a [custom plugin](https://redocly.com/docs/cli/custom-plugins/) to define a rule.
+
+```js
+import { lintFromString, createConfig, stringifyYaml } from '@redocly/openapi-core';
+
+const CustomRule = (ruleOptions) => {
+  return {
+    Operation() {
+      // some rule logic
+    },
+  };
+};
+
+const config = await createConfig({
+  extends: ['recommended'],
+  plugins: [
+    {
+      id: 'pluginId',
+      rules: {
+        oas3: {
+          customRule1: CustomRule,
+        },
+        oas2: {
+          customRule1: CustomRule, // if the same rule can handle both oas3 and oas2
+        },
+      },
+      decorators: {
+        // ...
+      },
+    },
+  ],
+  // enable rule
+  rules: {
+    'pluginId/customRule1': 'error',
+  },
+  decorators: {
+    // ...
+  },
+});
+
+const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
+const lintResults = await lintFromString({
+  source,
+  // optionally pass path to the file for resolving $refs and proper error locations
+  absoluteRef: 'optional/path/to/openapi.yaml',
+  config,
+});
+```
+
+### Bundle from memory
+
+[Bundle](https://redocly.com/docs/cli/commands/bundle/) an API description into a single structure, using default configuration.
+
+```js
+import { bundleFromString, createConfig } from '@redocly/openapi-core';
+
+const config = await createConfig({}); // create empty config
+const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
+const bundleResults = await bundleFromString({
+  source,
+  // optionally pass path to the file for resolving $refs and proper error locations
+  absoluteRef: 'optional/path/to/openapi.yaml',
+  config,
+});
+```
+
+## API
+
+### `createConfig`
+
+Creates a config object from a JSON or YAML string or JS object.
+Resolves remote config from `extends` (if there are URLs or local fs paths).
+
+```ts
+async function createConfig(
+  // JSON or YAML string or object with Redocly config
+  config: string | RawUniversalConfig,
+  options?: {
+    // optional path to the config file for resolving $refs and proper error locations
+    configPath?: string;
+  }
+): Promise<Config>;
+```
+
+### `loadConfig`
+
+Loads a config object from a file system. If `configPath` is not provided,
+it tries to find `redocly.yaml` in the current working directory.
+
+```ts
+async function loadConfig(options?: {
+  // optional path to the config file for resolving $refs and proper error locations
+  configPath?: string;
+  // allows to add custom `extends` additionally to one from the config file
+  customExtends?: string[];
+}): Promise<Config>;
+```
+
+### `lint`
+
+Lint an OpenAPI document from the file system.
+
+```ts
+async function lint(options: {
+  // path to the OpenAPI document root
+  ref: string;
+  // config object
+  config: Config;
+}): Promise<NormalizedProblem[]>;
+```
+
+### `lintFromString`
+
+Lint an OpenAPI document from a string.
+
+```ts
+async function lintFromString(options: {
+  // OpenAPI document string
+  source: string;
+  // optional path to the OpenAPI document for resolving $refs and proper error locations
+  absoluteRef?: string;
+  // config object
+  config: Config;
+}): Promise<NormalizedProblem[]>;
+```
+
+### `bundle`
+
+Bundle an OpenAPI document from the file system.
+
+```ts
+async function bundle(options: {
+  // path to the OpenAPI document root
+  ref: string;
+  // config object
+  config: Config;
+  // whether to fully dereference $refs, resulting document won't have any $ref
+  // warning: this can produce circular objects
+  dereference?: boolean;
+  // whether to remove unused components (schemas, parameters, responses, etc)
+  removeUnusedComponents?: boolean;
+  // whether to keep $ref pointers to the http URLs and resolve only local fs $refs
+  keepUrlRefs?: boolean;
+}): Promise<{
+    bundle: {
+      parsed: object; // OpenAPI document object as js object
+    };
+    problems: NormalizedProblem[]
+    fileDependencies
+    rootType
+    refTypes
+    visitorsData
+
+  }>;
+```
+
+### `bundleFromString`
+
+Bundle an OpenAPI document from a string.
+
+```ts
+async function bundleFromString(options: {
+  // OpenAPI document string
+  source: string;
+  // optional path to the OpenAPI document for resolving $refs and proper error locations
+  absoluteRef?: string;
+  // config object
+  config: Config;
+  // whether to fully dereference $refs, resulting document won't have any $ref
+  // warning: this can produce circular objects
+  dereference?: boolean;
+  // whether to remove unused components (schemas, parameters, responses, etc)
+  removeUnusedComponents?: boolean;
+  // whether to keep $ref pointers to the http URLs and resolve only local fs $refs
+  keepUrlRefs?: boolean;
+}): Promise<{
+    bundle: {
+      parsed: object; // OpenAPI document object as js object
+    };
+    problems: NormalizedProblem[]
+    fileDependencies
+    rootType
+    refTypes
+    visitorsData
+
+  }>;
+```
+
+### `stringifyYaml`
+
+Helper function to stringify a javascript object to YAML.
+
+```ts
+function stringifyYaml(obj: object): string;
+```

package/lib/benchmark/benches/lint-with-many-rules.bench.d.ts

@@ -0,0 +1,4 @@
+export declare const name = "Validate with 50 top-level rules";
+export declare const count = 10;
+export declare function setupAsync(): Promise<void>;
+export declare function measureAsync(): Promise<import("../..").NormalizedProblem[]>;

package/lib/benchmark/benches/lint-with-many-rules.bench.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.setupAsync = setupAsync;
+exports.measureAsync = measureAsync;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lint_1 = require("../../lint");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+exports.name = 'Validate with 50 top-level rules';
+exports.count = 10;
+const rebillyDefinitionRef = (0, path_1.resolve)((0, path_1.join)(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+const ruleset = {};
+for (let i = 0; i < 50; i++) {
+    ruleset['rule-' + i] = () => {
+        let count = 0;
+        return {
+            Schema() {
+                count++;
+                if (count === -1)
+                    throw new Error('Disable optimization');
+            },
+        };
+    };
+}
+let config;
+async function setupAsync() {
+    config = await (0, utils_1.makeConfigForRuleset)(ruleset);
+}
+function measureAsync() {
+    return (0, lint_1.lintDocument)({
+        externalRefResolver: new resolve_1.BaseResolver(),
+        document: rebillyDocument,
+        config,
+    });
+}

package/lib/benchmark/benches/lint-with-nested-rule.bench.d.ts

@@ -0,0 +1,4 @@
+export declare const name = "Validate with single nested rule";
+export declare const count = 10;
+export declare function setupAsync(): Promise<void>;
+export declare function measureAsync(): Promise<import("../..").NormalizedProblem[]>;

package/lib/benchmark/benches/lint-with-nested-rule.bench.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.setupAsync = setupAsync;
+exports.measureAsync = measureAsync;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lint_1 = require("../../lint");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+exports.name = 'Validate with single nested rule';
+exports.count = 10;
+const rebillyDefinitionRef = (0, path_1.resolve)((0, path_1.join)(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+const visitor = {
+    test: () => {
+        let count = 0;
+        return {
+            PathItem: {
+                Parameter() {
+                    count++;
+                },
+                Operation: {
+                    Parameter() {
+                        count++;
+                        if (count === -1)
+                            throw new Error('Disable optimization');
+                    },
+                },
+            },
+        };
+    },
+};
+let config;
+async function setupAsync() {
+    config = await (0, utils_1.makeConfigForRuleset)(visitor);
+}
+function measureAsync() {
+    return (0, lint_1.lintDocument)({
+        externalRefResolver: new resolve_1.BaseResolver(),
+        document: rebillyDocument,
+        config,
+    });
+}

package/lib/benchmark/benches/lint-with-no-rules.bench.d.ts

@@ -0,0 +1,4 @@
+export declare const name = "Validate with no rules";
+export declare const count = 10;
+export declare function setupAsync(): Promise<void>;
+export declare function measureAsync(): Promise<import("../..").NormalizedProblem[]>;

package/lib/benchmark/benches/lint-with-no-rules.bench.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.setupAsync = setupAsync;
+exports.measureAsync = measureAsync;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lint_1 = require("../../lint");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+exports.name = 'Validate with no rules';
+exports.count = 10;
+const rebillyDefinitionRef = (0, path_1.resolve)((0, path_1.join)(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+let config;
+async function setupAsync() {
+    config = await (0, utils_1.makeConfigForRuleset)({});
+}
+function measureAsync() {
+    return (0, lint_1.lintDocument)({
+        externalRefResolver: new resolve_1.BaseResolver(),
+        document: rebillyDocument,
+        config,
+    });
+}

package/lib/benchmark/benches/lint-with-top-level-rule-report.bench.d.ts

@@ -0,0 +1,4 @@
+export declare const name = "Validate with single top-level rule and report";
+export declare const count = 10;
+export declare function setupAsync(): Promise<void>;
+export declare function measureAsync(): Promise<import("../..").NormalizedProblem[]>;

package/lib/benchmark/benches/lint-with-top-level-rule-report.bench.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.setupAsync = setupAsync;
+exports.measureAsync = measureAsync;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lint_1 = require("../../lint");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+exports.name = 'Validate with single top-level rule and report';
+exports.count = 10;
+const rebillyDefinitionRef = (0, path_1.resolve)((0, path_1.join)(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+let config;
+async function setupAsync() {
+    config = await (0, utils_1.makeConfigForRuleset)({
+        test: () => {
+            return {
+                Schema(schema, ctx) {
+                    if (schema.type === 'number') {
+                        ctx.report({
+                            message: 'type number is not allowed',
+                        });
+                    }
+                },
+            };
+        },
+    });
+}
+function measureAsync() {
+    return (0, lint_1.lintDocument)({
+        externalRefResolver: new resolve_1.BaseResolver(),
+        document: rebillyDocument,
+        config,
+    });
+}

package/lib/benchmark/benches/lint-with-top-level-rule.bench.d.ts

@@ -0,0 +1,4 @@
+export declare const name = "Validate with single top-level rule";
+export declare const count = 10;
+export declare function setupAsync(): Promise<void>;
+export declare function measureAsync(): Promise<import("../..").NormalizedProblem[]>;

package/lib/benchmark/benches/lint-with-top-level-rule.bench.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.setupAsync = setupAsync;
+exports.measureAsync = measureAsync;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lint_1 = require("../../lint");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+exports.name = 'Validate with single top-level rule';
+exports.count = 10;
+const rebillyDefinitionRef = (0, path_1.resolve)((0, path_1.join)(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+let config;
+async function setupAsync() {
+    config = await (0, utils_1.makeConfigForRuleset)({
+        test: () => {
+            let count = 0;
+            return {
+                Schema() {
+                    count++;
+                    if (count === -1)
+                        throw new Error('Disable optimization');
+                },
+            };
+        },
+    });
+}
+function measureAsync() {
+    return (0, lint_1.lintDocument)({
+        externalRefResolver: new resolve_1.BaseResolver(),
+        document: rebillyDocument,
+        config,
+    });
+}

package/lib/benchmark/benches/recommended-oas3.bench.d.ts

@@ -0,0 +1,3 @@
+export declare const name = "Validate with recommended rules";
+export declare const count = 10;
+export declare function measureAsync(): Promise<import("../..").NormalizedProblem[]>;

package/lib/benchmark/benches/recommended-oas3.bench.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.measureAsync = measureAsync;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lint_1 = require("../../lint");
+const config_1 = require("../../config");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+exports.name = 'Validate with recommended rules';
+exports.count = 10;
+const rebillyDefinitionRef = (0, path_1.resolve)((0, path_1.join)(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+function measureAsync() {
+    return (0, lint_1.lintDocument)({
+        externalRefResolver: new resolve_1.BaseResolver(),
+        document: rebillyDocument,
+        config: new config_1.StyleguideConfig((0, config_1.resolvePreset)('recommended', [config_1.defaultPlugin])),
+    });
+}

package/lib/benchmark/benches/resolve-with-no-external.bench.d.ts

@@ -0,0 +1,3 @@
+export declare const name = "Resolve with no external refs";
+export declare const count = 10;
+export declare function measureAsync(): Promise<import("../../resolve").ResolvedRefMap>;

package/lib/benchmark/benches/resolve-with-no-external.bench.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = exports.name = void 0;
+exports.measureAsync = measureAsync;
+const path = require("path");
+const fs_1 = require("fs");
+const resolve_1 = require("../../resolve");
+const utils_1 = require("../utils");
+const oas3_1 = require("../../types/oas3");
+const types_1 = require("../../types");
+exports.name = 'Resolve with no external refs';
+exports.count = 10;
+const rebillyDefinitionRef = path.resolve(path.join(__dirname, 'rebilly.yaml'));
+const rebillyDocument = (0, utils_1.parseYamlToDocument)((0, fs_1.readFileSync)(rebillyDefinitionRef, 'utf-8'), rebillyDefinitionRef);
+const externalRefResolver = new resolve_1.BaseResolver();
+function measureAsync() {
+    return (0, resolve_1.resolveDocument)({
+        rootDocument: rebillyDocument,
+        externalRefResolver,
+        rootType: (0, types_1.normalizeTypes)(oas3_1.Oas3Types).Root,
+    });
+}

package/lib/benchmark/utils.d.ts

@@ -0,0 +1,6 @@
+import { StyleguideConfig } from '../config';
+import type { Document } from '../resolve';
+import type { Oas3RuleSet } from '../oas-types';
+import type { Plugin } from '../config/types';
+export declare function parseYamlToDocument(body: string, absoluteRef?: string): Document;
+export declare function makeConfigForRuleset(rules: Oas3RuleSet, plugin?: Partial<Plugin>): Promise<StyleguideConfig>;

package/lib/benchmark/utils.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseYamlToDocument = parseYamlToDocument;
+exports.makeConfigForRuleset = makeConfigForRuleset;
+const js_yaml_1 = require("../js-yaml");
+const resolve_1 = require("../resolve");
+const config_1 = require("../config");
+function parseYamlToDocument(body, absoluteRef = '') {
+    return {
+        source: new resolve_1.Source(absoluteRef, body),
+        parsed: (0, js_yaml_1.parseYaml)(body, { filename: absoluteRef }),
+    };
+}
+async function makeConfigForRuleset(rules, plugin) {
+    const rulesConf = {};
+    const ruleId = 'test';
+    Object.keys(rules).forEach((name) => {
+        rulesConf[`${ruleId}/${name}`] = 'error';
+    });
+    const extendConfigs = [
+        (await (0, config_1.resolvePlugins)([
+            {
+                ...plugin,
+                id: ruleId,
+                rules: { oas3: rules },
+            },
+        ])),
+    ];
+    if (rules) {
+        extendConfigs.push({ rules });
+    }
+    const styleguide = (0, config_1.mergeExtends)(extendConfigs);
+    return new config_1.StyleguideConfig(styleguide);
+}

package/lib/bundle.d.ts

@@ -0,0 +1,50 @@
+import { BaseResolver } from './resolve';
+import { SpecMajorVersion } from './oas-types';
+import type { NormalizedNodeType, NodeType } from './types';
+import type { NormalizedProblem } from './walk';
+import type { Config, StyleguideConfig } from './config';
+import type { Document, ResolvedRefMap } from './resolve';
+import type { CollectFn } from './utils';
+export declare enum OasVersion {
+    Version2 = "oas2",
+    Version3_0 = "oas3_0",
+    Version3_1 = "oas3_1"
+}
+export type BundleOptions = {
+    externalRefResolver?: BaseResolver;
+    config: Config;
+    dereference?: boolean;
+    base?: string | null;
+    skipRedoclyRegistryRefs?: boolean;
+    removeUnusedComponents?: boolean;
+    keepUrlRefs?: boolean;
+};
+export declare function bundleConfig(document: Document, resolvedRefMap: ResolvedRefMap): Promise<any>;
+export declare function bundle(opts: {
+    ref?: string;
+    doc?: Document;
+    collectSpecData?: CollectFn;
+} & BundleOptions): Promise<BundleResult>;
+export declare function bundleFromString(opts: {
+    source: string;
+    absoluteRef?: string;
+} & BundleOptions): Promise<BundleResult>;
+export type BundleResult = {
+    bundle: Document;
+    problems: NormalizedProblem[];
+    fileDependencies: Set<string>;
+    rootType: NormalizedNodeType;
+    refTypes?: Map<string, NormalizedNodeType>;
+    visitorsData: Record<string, Record<string, unknown>>;
+};
+export declare function bundleDocument(opts: {
+    document: Document;
+    config: StyleguideConfig;
+    customTypes?: Record<string, NodeType>;
+    externalRefResolver: BaseResolver;
+    dereference?: boolean;
+    skipRedoclyRegistryRefs?: boolean;
+    removeUnusedComponents?: boolean;
+    keepUrlRefs?: boolean;
+}): Promise<BundleResult>;
+export declare function mapTypeToComponent(typeName: string, version: SpecMajorVersion): "definitions" | "links" | "responses" | "parameters" | "examples" | "headers" | "schemas" | "requestBodies" | "securitySchemes" | "callbacks" | null;