@redocly/openapi-core 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @redocly/openapi-core
 
+## 1.6.0
+
+### Minor Changes
+
+- Added the ability to use `$ref` in the Redocly config file. This ability allows users to split up big config files and maintain their constituent parts independently.
+
 ## 1.5.0
 
 ### Minor Changes

package/lib/bundle.d.ts

@@ -1,9 +1,10 @@
-import { BaseResolver, Document } from './resolve';
-import { Oas3Rule } from './visitors';
-import { NormalizedNodeType, NodeType } from './types';
-import { NormalizedProblem } from './walk';
+import { BaseResolver } from './resolve';
 import { SpecMajorVersion } from './oas-types';
+import type { Oas3Rule } from './visitors';
+import type { NormalizedNodeType, NodeType } from './types';
+import type { NormalizedProblem } from './walk';
 import type { Config, StyleguideConfig } from './config';
+import type { Document, ResolvedRefMap } from './resolve';
 export type Oas3RuleSet = Record<string, Oas3Rule>;
 export declare enum OasVersion {
     Version2 = "oas2",
@@ -14,11 +15,12 @@ export type BundleOptions = {
     externalRefResolver?: BaseResolver;
     config: Config;
     dereference?: boolean;
-    base?: string;
+    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;
@@ -45,4 +47,4 @@ export declare function bundleDocument(opts: {
     removeUnusedComponents?: boolean;
     keepUrlRefs?: boolean;
 }): Promise<BundleResult>;
-export declare function mapTypeToComponent(typeName: string, version: SpecMajorVersion): "responses" | "links" | "parameters" | "examples" | "headers" | "schemas" | "requestBodies" | "securitySchemes" | "callbacks" | "definitions" | null;
+export declare function mapTypeToComponent(typeName: string, version: SpecMajorVersion): "responses" | "parameters" | "examples" | "headers" | "schemas" | "requestBodies" | "securitySchemes" | "links" | "callbacks" | "definitions" | null;

package/lib/bundle.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mapTypeToComponent = exports.bundleDocument = exports.bundleFromString = exports.bundle = exports.OasVersion = void 0;
+exports.mapTypeToComponent = exports.bundleDocument = exports.bundleFromString = exports.bundle = exports.bundleConfig = exports.OasVersion = void 0;
 const isEqual = require("lodash.isequal");
 const resolve_1 = require("./resolve");
 const visitors_1 = require("./visitors");
@@ -23,12 +23,47 @@ const utils_1 = require("./utils");
 const redocly_1 = require("./redocly");
 const remove_unused_components_1 = require("./decorators/oas2/remove-unused-components");
 const remove_unused_components_2 = require("./decorators/oas3/remove-unused-components");
+const redocly_yaml_1 = require("./types/redocly-yaml");
 var OasVersion;
 (function (OasVersion) {
     OasVersion["Version2"] = "oas2";
     OasVersion["Version3_0"] = "oas3_0";
     OasVersion["Version3_1"] = "oas3_1";
 })(OasVersion || (exports.OasVersion = OasVersion = {}));
+function bundleConfig(document, resolvedRefMap) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const types = (0, types_1.normalizeTypes)(redocly_yaml_1.ConfigTypes);
+        const ctx = {
+            problems: [],
+            oasVersion: oas_types_1.SpecVersion.OAS3_0,
+            refTypes: new Map(),
+            visitorsData: {},
+        };
+        const bundleVisitor = (0, visitors_1.normalizeVisitors)([
+            {
+                severity: 'error',
+                ruleId: 'configBundler',
+                visitor: {
+                    ref: {
+                        leave(node, ctx, resolved) {
+                            replaceRef(node, resolved, ctx);
+                        },
+                    },
+                },
+            },
+        ], types);
+        (0, walk_1.walkDocument)({
+            document,
+            rootType: types.ConfigRoot,
+            normalizedVisitors: bundleVisitor,
+            resolvedRefMap,
+            ctx,
+        });
+        return (_a = document.parsed) !== null && _a !== void 0 ? _a : {};
+    });
+}
+exports.bundleConfig = bundleConfig;
 function bundle(opts) {
     return __awaiter(this, void 0, void 0, function* () {
         const { ref, doc, externalRefResolver = new resolve_1.BaseResolver(opts.config.resolve), base = null, } = opts;
@@ -169,6 +204,18 @@ function mapTypeToComponent(typeName, version) {
     }
 }
 exports.mapTypeToComponent = mapTypeToComponent;
+function replaceRef(ref, resolved, ctx) {
+    if (!(0, utils_1.isPlainObject)(resolved.node)) {
+        ctx.parent[ctx.key] = resolved.node;
+    }
+    else {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        delete ref.$ref;
+        const obj = Object.assign({}, resolved.node, ref);
+        Object.assign(ref, obj); // assign ref itself again so ref fields take precedence
+    }
+}
 // function oas3Move
 function makeBundleVisitor(version, dereference, skipRedoclyRegistryRefs, rootDocument, resolvedRefMap, keepUrlRefs) {
     let components;
@@ -252,19 +299,6 @@ function makeBundleVisitor(version, dereference, skipRedoclyRegistryRefs, rootDo
             resolved: true,
         });
     }
-    function replaceRef(ref, resolved, ctx) {
-        if (!(0, utils_1.isPlainObject)(resolved.node)) {
-            ctx.parent[ctx.key] = resolved.node;
-        }
-        else {
-            // TODO: why $ref isn't optional in OasRef?
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            // @ts-ignore
-            delete ref.$ref;
-            const obj = Object.assign({}, resolved.node, ref);
-            Object.assign(ref, obj); // assign ref itself again so ref fields take precedence
-        }
-    }
     function saveComponent(componentType, target, ctx) {
         components[componentType] = components[componentType] || {};
         const name = getComponentName(target, componentType, ctx);

package/lib/config/config-resolvers.d.ts

@@ -1,6 +1,14 @@
 import { BaseResolver } from '../resolve';
-import type { StyleguideRawConfig, Plugin, RawConfig, ResolvedApi, ResolvedStyleguideConfig } from './types';
 import { Config } from './config';
+import type { StyleguideRawConfig, Plugin, RawConfig, ResolvedApi, ResolvedStyleguideConfig } from './types';
+import type { BundleOptions } from '../bundle';
+import type { Document, ResolvedRefMap } from '../resolve';
+export declare function resolveConfigFileAndRefs({ configPath, externalRefResolver, base, }: Omit<BundleOptions, 'config'> & {
+    configPath?: string;
+}): Promise<{
+    document: Document;
+    resolvedRefMap: ResolvedRefMap;
+}>;
 export declare function resolveConfig(rawConfig: RawConfig, configPath?: string): Promise<Config>;
 export declare function resolvePlugins(plugins: (string | Plugin)[] | null, configPath?: string): Plugin[];
 export declare function resolveApis({ rawConfig, configPath, resolver, }: {

package/lib/config/config-resolvers.js

@@ -20,7 +20,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolvePreset = exports.resolveStyleguideConfig = exports.resolveApis = exports.resolvePlugins = exports.resolveConfig = void 0;
+exports.resolvePreset = exports.resolveStyleguideConfig = exports.resolveApis = exports.resolvePlugins = exports.resolveConfig = exports.resolveConfigFileAndRefs = void 0;
 const path = require("path");
 const ref_utils_1 = require("../ref-utils");
 const utils_1 = require("../utils");
@@ -32,6 +32,27 @@ const utils_3 = require("../utils");
 const config_1 = require("./config");
 const logger_1 = require("../logger");
 const asserts_1 = require("../rules/common/assertions/asserts");
+const types_1 = require("../types");
+const redocly_yaml_1 = require("../types/redocly-yaml");
+function resolveConfigFileAndRefs({ configPath, externalRefResolver = new resolve_1.BaseResolver(), base = null, }) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!configPath) {
+            throw new Error('Reference to a config is required.\n');
+        }
+        const document = yield externalRefResolver.resolveDocument(base, configPath, true);
+        if (document instanceof Error) {
+            throw document;
+        }
+        const types = (0, types_1.normalizeTypes)(redocly_yaml_1.ConfigTypes);
+        const resolvedRefMap = yield (0, resolve_1.resolveDocument)({
+            rootDocument: document,
+            rootType: types.ConfigRoot,
+            externalRefResolver,
+        });
+        return { document, resolvedRefMap };
+    });
+}
+exports.resolveConfigFileAndRefs = resolveConfigFileAndRefs;
 function resolveConfig(rawConfig, configPath) {
     var _a, _b;
     return __awaiter(this, void 0, void 0, function* () {

package/lib/config/load.d.ts

@@ -1,16 +1,24 @@
 import { Config } from './config';
+import type { Document } from '../resolve';
+import type { RegionalTokenWithValidity } from '../redocly/redocly-client-types';
 import type { RawConfig, RawUniversalConfig, Region } from './types';
-import { RegionalTokenWithValidity } from '../redocly/redocly-client-types';
+import type { BaseResolver, ResolvedRefMap } from '../resolve';
+export type RawConfigProcessor = (rawConfig: Document, resolvedRefMap: ResolvedRefMap) => void | Promise<void>;
 export declare function loadConfig(options?: {
     configPath?: string;
     customExtends?: string[];
-    processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>;
+    processRawConfig?: RawConfigProcessor;
+    externalRefResolver?: BaseResolver;
     files?: string[];
     region?: Region;
 }): Promise<Config>;
 export declare const CONFIG_FILE_NAMES: string[];
 export declare function findConfig(dir?: string): string | undefined;
-export declare function getConfig(configPath?: string | undefined, processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>): Promise<RawConfig>;
+export declare function getConfig(options?: {
+    configPath?: string;
+    processRawConfig?: RawConfigProcessor;
+    externalRefResolver?: BaseResolver;
+}): Promise<RawConfig>;
 type CreateConfigOptions = {
     extends?: string[];
     tokens?: RegionalTokenWithValidity[];

package/lib/config/load.js

@@ -18,6 +18,7 @@ const js_yaml_1 = require("../js-yaml");
 const config_1 = require("./config");
 const utils_2 = require("./utils");
 const config_resolvers_1 = require("./config-resolvers");
+const bundle_1 = require("../bundle");
 function addConfigMetadata({ rawConfig, customExtends, configPath, tokens, files, region, }) {
     var _a;
     return __awaiter(this, void 0, void 0, function* () {
@@ -60,8 +61,8 @@ function addConfigMetadata({ rawConfig, customExtends, configPath, tokens, files
 }
 function loadConfig(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
-        const { configPath = findConfig(), customExtends, processRawConfig, files, region } = options;
-        const rawConfig = yield getConfig(configPath, processRawConfig);
+        const { configPath = findConfig(), customExtends, processRawConfig, files, region, externalRefResolver, } = options;
+        const rawConfig = yield getConfig({ configPath, processRawConfig, externalRefResolver });
         const redoclyClient = new redocly_1.RedoclyClient();
         const tokens = yield redoclyClient.getTokens();
         return addConfigMetadata({
@@ -90,16 +91,21 @@ function findConfig(dir) {
     return existingConfigFiles[0];
 }
 exports.findConfig = findConfig;
-function getConfig(configPath = findConfig(), processRawConfig) {
+function getConfig(options = {}) {
     return __awaiter(this, void 0, void 0, function* () {
+        const { configPath = findConfig(), processRawConfig, externalRefResolver } = options;
         if (!configPath || !(0, utils_1.doesYamlFileExist)(configPath))
             return {};
         try {
-            const rawConfig = (yield (0, utils_1.loadYaml)(configPath)) || {};
+            const { document, resolvedRefMap } = yield (0, config_resolvers_1.resolveConfigFileAndRefs)({
+                configPath,
+                externalRefResolver,
+            });
             if (typeof processRawConfig === 'function') {
-                yield processRawConfig(rawConfig);
+                yield processRawConfig(document, resolvedRefMap);
             }
-            return (0, utils_2.transformConfig)(rawConfig);
+            const bundledConfig = yield (0, bundle_1.bundleConfig)(document, resolvedRefMap);
+            return (0, utils_2.transformConfig)(bundledConfig);
         }
         catch (e) {
             if (e instanceof utils_2.ConfigValidationError) {

package/lib/lint.d.ts

@@ -1,7 +1,8 @@
-import { BaseResolver, Document } from './resolve';
-import { NodeType } from './types';
-import { ProblemSeverity } from './walk';
+import { BaseResolver } from './resolve';
 import { StyleguideConfig, Config } from './config';
+import type { Document, ResolvedRefMap } from './resolve';
+import type { ProblemSeverity } from './walk';
+import type { NodeType } from './types';
 export declare function lint(opts: {
     ref: string;
     config: Config;
@@ -21,5 +22,7 @@ export declare function lintDocument(opts: {
 }): Promise<import("./walk").NormalizedProblem[]>;
 export declare function lintConfig(opts: {
     document: Document;
+    resolvedRefMap?: ResolvedRefMap;
     severity?: ProblemSeverity;
+    externalRefResolver?: BaseResolver;
 }): Promise<import("./walk").NormalizedProblem[]>;

package/lib/lint.js

@@ -19,6 +19,7 @@ const ajv_1 = require("./rules/ajv");
 const oas_types_1 = require("./oas-types");
 const redocly_yaml_1 = require("./types/redocly-yaml");
 const spec_1 = require("./rules/common/spec");
+const no_unresolved_refs_1 = require("./rules/no-unresolved-refs");
 function lint(opts) {
     return __awaiter(this, void 0, void 0, function* () {
         const { ref, externalRefResolver = new resolve_1.BaseResolver(opts.config.resolve) } = opts;
@@ -84,7 +85,7 @@ function lintDocument(opts) {
 exports.lintDocument = lintDocument;
 function lintConfig(opts) {
     return __awaiter(this, void 0, void 0, function* () {
-        const { document, severity } = opts;
+        const { document, severity, externalRefResolver = new resolve_1.BaseResolver() } = opts;
         const ctx = {
             problems: [],
             oasVersion: oas_types_1.SpecVersion.OAS3_0,
@@ -102,14 +103,24 @@ function lintConfig(opts) {
                 ruleId: 'configuration spec',
                 visitor: (0, spec_1.Spec)({ severity: 'error' }),
             },
+            {
+                severity: severity || 'error',
+                ruleId: 'configuration no-unresolved-refs',
+                visitor: (0, no_unresolved_refs_1.NoUnresolvedRefs)({ severity: 'error' }),
+            },
         ];
-        // TODO: check why any is needed
         const normalizedVisitors = (0, visitors_1.normalizeVisitors)(rules, types);
+        const resolvedRefMap = opts.resolvedRefMap ||
+            (yield (0, resolve_1.resolveDocument)({
+                rootDocument: document,
+                rootType: types.ConfigRoot,
+                externalRefResolver,
+            }));
         (0, walk_1.walkDocument)({
             document,
             rootType: types.ConfigRoot,
             normalizedVisitors,
-            resolvedRefMap: new Map(),
+            resolvedRefMap,
             ctx,
         });
         return ctx.problems;