@redocly/openapi-core 1.19.0 → 1.20.1

package/src/config/builtIn.ts

@@ -2,16 +2,11 @@ import recommended from './recommended';
 import recommendedStrict from './recommended-strict';
 import all from './all';
 import minimal from './minimal';
-import { rules as oas3Rules } from '../rules/oas3';
-import { rules as oas2Rules } from '../rules/oas2';
-import { rules as async2Rules } from '../rules/async2';
-import { rules as async3Rules } from '../rules/async3';
-import { rules as arazzoRules } from '../rules/arazzo';
-import { preprocessors as oas3Preprocessors } from '../rules/oas3';
-import { preprocessors as oas2Preprocessors } from '../rules/oas2';
-import { preprocessors as async2Preprocessors } from '../rules/async2';
-import { preprocessors as async3Preprocessors } from '../rules/async3';
-import { preprocessors as arazzoPreprocessors } from '../rules/arazzo';
+import { rules as oas3Rules, preprocessors as oas3Preprocessors } from '../rules/oas3';
+import { rules as oas2Rules, preprocessors as oas2Preprocessors } from '../rules/oas2';
+import { rules as async2Rules, preprocessors as async2Preprocessors } from '../rules/async2';
+import { rules as async3Rules, preprocessors as async3Preprocessors } from '../rules/async3';
+import { rules as arazzoRules, preprocessors as arazzoPreprocessors } from '../rules/arazzo';
 import { decorators as oas3Decorators } from '../decorators/oas3';
 import { decorators as oas2Decorators } from '../decorators/oas2';
 import { decorators as async2Decorators } from '../decorators/async2';

package/src/config/config-resolvers.ts

@@ -1,18 +1,20 @@
 import * as path from 'path';
+import { existsSync } from 'fs';
 import { isAbsoluteUrl } from '../ref-utils';
-import { pickDefined } from '../utils';
+import { pickDefined, isNotString, isString, isDefined, keysOf } from '../utils';
 import { resolveDocument, BaseResolver } from '../resolve';
 import { defaultPlugin } from './builtIn';
 import {
   getResolveConfig,
   getUniquePlugins,
+  isCommonJsPlugin,
+  isDeprecatedPluginFormat,
   mergeExtends,
   parsePresetName,
   prefixRules,
   transformConfig,
 } from './utils';
 import { isBrowser } from '../env';
-import { isNotString, isString, isDefined, keysOf } from '../utils';
 import { Config } from './config';
 import { colorize, logger } from '../logger';
 import { asserts, buildAssertCustomFunction } from '../rules/common/assertions/asserts';
@@ -28,12 +30,18 @@ import type {
   ResolvedStyleguideConfig,
   RuleConfig,
   DeprecatedInRawConfig,
+  ImportedPlugin,
 } from './types';
 import type { Assertion, AssertionDefinition, RawAssertion } from '../rules/common/assertions';
 import type { Asserts, AssertionFn } from '../rules/common/assertions/asserts';
 import type { BundleOptions } from '../bundle';
 import type { Document, ResolvedRefMap } from '../resolve';
 
+const DEFAULT_PROJECT_PLUGIN_PATHS = ['@theme/plugin.js', '@theme/plugin.cjs', '@theme/plugin.mjs'];
+
+// Workaround for dynamic imports being transpiled to require by Typescript: https://github.com/microsoft/TypeScript/issues/43329#issuecomment-811606238
+const _importDynamic = new Function('modulePath', 'return import(modulePath)');
+
 export async function resolveConfigFileAndRefs({
   configPath,
   externalRefResolver = new BaseResolver(),
@@ -102,14 +110,24 @@ export async function resolveConfig({
   );
 }
 
-export function resolvePlugins(
+function getDefaultPluginPath(configPath: string): string | undefined {
+  for (const pluginPath of DEFAULT_PROJECT_PLUGIN_PATHS) {
+    const absolutePluginPath = path.resolve(path.dirname(configPath), pluginPath);
+    if (existsSync(absolutePluginPath)) {
+      return pluginPath;
+    }
+  }
+  return undefined;
+}
+
+export async function resolvePlugins(
   plugins: (string | Plugin)[] | null,
   configPath: string = ''
-): Plugin[] {
+): Promise<Plugin[]> {
   if (!plugins) return [];
 
   // TODO: implement or reuse Resolver approach so it will work in node and browser envs
-  const requireFunc = (plugin: string | Plugin): Plugin | undefined => {
+  const requireFunc = async (plugin: string | Plugin): Promise<ImportedPlugin | undefined> => {
     if (isBrowser && isString(plugin)) {
       logger.error(`Cannot load ${plugin}. Plugins aren't supported in browser yet.`);
 
@@ -118,19 +136,26 @@ export function resolvePlugins(
 
     if (isString(plugin)) {
       try {
-        const absoltePluginPath = path.resolve(path.dirname(configPath), plugin);
+        const maybeAbsolutePluginPath = path.resolve(path.dirname(configPath), plugin);
+
+        const absolutePluginPath = existsSync(maybeAbsolutePluginPath)
+          ? maybeAbsolutePluginPath
+          : // For plugins imported from packages specifically
+            require.resolve(plugin);
+
         // eslint-disable-next-line @typescript-eslint/ban-ts-comment
         // @ts-ignore
-        return typeof __webpack_require__ === 'function'
-          ? // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            // @ts-ignore
-            __non_webpack_require__(absoltePluginPath)
-          : require(absoltePluginPath);
-      } catch (e) {
-        if (e instanceof SyntaxError) {
-          throw e;
+        if (typeof __webpack_require__ === 'function') {
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore
+          return __non_webpack_require__(absolutePluginPath);
+        } else {
+          // you can import both cjs and mjs
+          const mod = await _importDynamic(absolutePluginPath);
+          return mod.default || mod;
         }
-        throw new Error(`Failed to load plugin "${plugin}". Please provide a valid path`);
+      } catch (e) {
+        throw new Error(`Failed to load plugin "${plugin}": ${e.message}\n\n${e.stack}`);
       }
     }
 
@@ -139,19 +164,47 @@ export function resolvePlugins(
 
   const seenPluginIds = new Map<string, string>();
 
-  return plugins
-    .map((p) => {
-      if (isString(p) && isAbsoluteUrl(p)) {
-        throw new Error(colorize.red(`We don't support remote plugins yet.`));
+  /**
+   * Include the default plugin automatically if it's not in configuration
+   */
+  const defaultPluginPath = getDefaultPluginPath(configPath);
+  if (defaultPluginPath) {
+    plugins.push(defaultPluginPath);
+  }
+
+  const resolvedPlugins: Set<string> = new Set();
+
+  const instances = await Promise.all(
+    plugins.map(async (p) => {
+      if (isString(p)) {
+        if (isAbsoluteUrl(p)) {
+          throw new Error(colorize.red(`We don't support remote plugins yet.`));
+        }
+        if (resolvedPlugins.has(p)) {
+          return;
+        }
+
+        resolvedPlugins.add(p);
       }
 
-      // TODO: resolve npm packages similar to eslint
-      const pluginModule = requireFunc(p);
+      const requiredPlugin: ImportedPlugin | undefined = await requireFunc(p);
+
+      const pluginCreatorOptions = { contentDir: path.dirname(configPath) };
+
+      const pluginModule = isDeprecatedPluginFormat(requiredPlugin)
+        ? requiredPlugin
+        : isCommonJsPlugin(requiredPlugin)
+        ? await requiredPlugin(pluginCreatorOptions)
+        : await requiredPlugin?.default?.(pluginCreatorOptions);
 
       if (!pluginModule) {
         return;
       }
 
+      if (isString(p) && pluginModule.id && isDeprecatedPluginFormat(requiredPlugin)) {
+        logger.info(`Deprecated plugin format detected: ${pluginModule.id}\n`);
+      }
+
       const id = pluginModule.id;
       if (typeof id !== 'string') {
         throw new Error(
@@ -267,7 +320,9 @@ export function resolvePlugins(
 
       return plugin;
     })
-    .filter(isDefined);
+  );
+
+  return instances.filter(isDefined);
 }
 
 export async function resolveApis({
@@ -318,7 +373,7 @@ async function resolveAndMergeNestedStyleguideConfig(
     throw new Error(`Circular dependency in config file: "${configPath}"`);
   }
   const plugins = getUniquePlugins(
-    resolvePlugins([...(styleguideConfig?.plugins || []), defaultPlugin], configPath)
+    await resolvePlugins([...(styleguideConfig?.plugins || []), defaultPlugin], configPath)
   );
   const pluginPaths = styleguideConfig?.plugins
     ?.filter(isString)

package/src/config/config.ts

@@ -2,18 +2,19 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { parseYaml, stringifyYaml } from '../js-yaml';
 import { slash, doesYamlFileExist } from '../utils';
-import { NormalizedProblem } from '../walk';
-import {
-  SpecVersion,
-  SpecMajorVersion,
+import { SpecVersion, SpecMajorVersion } from '../oas-types';
+import { isBrowser } from '../env';
+import { getResolveConfig } from './utils';
+import { isAbsoluteUrl } from '../ref-utils';
+
+import type { NormalizedProblem } from '../walk';
+import type {
   Oas2RuleSet,
   Oas3RuleSet,
   Async2RuleSet,
   Async3RuleSet,
   ArazzoRuleSet,
 } from '../oas-types';
-import { isBrowser } from '../env';
-
 import type { NodeType } from '../types';
 import type {
   DecoratorConfig,
@@ -29,8 +30,6 @@ import type {
   Telemetry,
   ThemeRawConfig,
 } from './types';
-import { getResolveConfig } from './utils';
-import { isAbsoluteUrl } from '../ref-utils';
 
 export const IGNORE_FILE = '.redocly.lint-ignore.yaml';
 const IGNORE_BANNER =

package/src/config/load.ts

@@ -3,17 +3,17 @@ import * as path from 'path';
 import { RedoclyClient } from '../redocly';
 import { isEmptyObject } from '../utils';
 import { parseYaml } from '../js-yaml';
-import { Config } from './config';
 import { ConfigValidationError, transformConfig, deepCloneMapWithJSON } from './utils';
 import { resolveConfig, resolveConfigFileAndRefs } from './config-resolvers';
 import { bundleConfig } from '../bundle';
 import { BaseResolver } from '../resolve';
 import { isBrowser } from '../env';
+import { DOMAINS } from '../redocly/domains';
 
+import type { Config } from './config';
 import type { Document, ResolvedRefMap } from '../resolve';
 import type { RegionalToken, RegionalTokenWithValidity } from '../redocly/redocly-client-types';
 import type { RawConfig, RawUniversalConfig, Region } from './types';
-import { DOMAINS } from '../redocly/domains';
 
 async function addConfigMetadata({
   rawConfig,

package/src/config/minimal.ts

@@ -5,6 +5,7 @@ const minimal: PluginStyleguideConfig<'built-in'> = {
     'info-contact': 'off',
     'info-license': 'off',
     'info-license-url': 'off',
+    'info-license-strict': 'off',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
     'parameter-description': 'off',
@@ -90,6 +91,7 @@ const minimal: PluginStyleguideConfig<'built-in'> = {
   async2Rules: {
     spec: 'error',
     'info-contact': 'off',
+    'info-license-strict': 'off',
     'operation-operationId': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
@@ -99,6 +101,7 @@ const minimal: PluginStyleguideConfig<'built-in'> = {
   async3Rules: {
     spec: 'error',
     'info-contact': 'off',
+    'info-license-strict': 'off',
     'operation-operationId': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
@@ -107,6 +110,7 @@ const minimal: PluginStyleguideConfig<'built-in'> = {
   },
   arazzoRules: {
     spec: 'error',
+    'parameters-no-body-inside-in': 'off',
   },
 };
 

package/src/config/recommended-strict.ts

@@ -4,7 +4,8 @@ const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
   rules: {
     'info-contact': 'off',
     'info-license': 'error',
-    'info-license-url': 'error',
+    'info-license-url': 'off',
+    'info-license-strict': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'off',
     'parameter-description': 'off',
@@ -90,6 +91,7 @@ const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
   async2Rules: {
     spec: 'error',
     'info-contact': 'off',
+    'info-license-strict': 'error',
     'operation-operationId': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'off',
@@ -99,6 +101,7 @@ const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
   async3Rules: {
     spec: 'error',
     'info-contact': 'off',
+    'info-license-strict': 'error',
     'operation-operationId': 'error',
     'tag-description': 'error',
     'tags-alphabetical': 'off',
@@ -107,6 +110,7 @@ const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
   },
   arazzoRules: {
     spec: 'error',
+    'parameters-no-body-inside-in': 'off',
   },
 };
 

package/src/config/recommended.ts

@@ -4,7 +4,8 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
   rules: {
     'info-contact': 'off',
     'info-license': 'warn',
-    'info-license-url': 'warn',
+    'info-license-url': 'off',
+    'info-license-strict': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
     'parameter-description': 'off',
@@ -90,6 +91,7 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
   async2Rules: {
     spec: 'error',
     'info-contact': 'off',
+    'info-license-strict': 'warn',
     'operation-operationId': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
@@ -99,6 +101,7 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
   async3Rules: {
     spec: 'error',
     'info-contact': 'off',
+    'info-license-strict': 'warn',
     'operation-operationId': 'warn',
     'tag-description': 'warn',
     'tags-alphabetical': 'off',
@@ -107,6 +110,7 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
   },
   arazzoRules: {
     spec: 'error',
+    'parameters-no-body-inside-in': 'off',
   },
 };
 

package/src/config/types.ts

@@ -1,3 +1,4 @@
+import type { Location } from '../ref-utils';
 import type { ProblemSeverity, UserContext } from '../walk';
 import type {
   Oas3PreprocessorsSet,
@@ -19,11 +20,9 @@ import type {
   ArazzoDecoratorsSet,
   RuleMap,
 } from '../oas-types';
-
 import type { NodeType } from '../types';
-import { Location } from '../ref-utils';
 import type { SkipFunctionContext } from '../visitors';
-import {
+import type {
   BuiltInAsync2RuleId,
   BuiltInAsync3RuleId,
   BuiltInCommonOASRuleId,
@@ -145,6 +144,22 @@ export type Plugin = {
   assertions?: AssertionsConfig;
 };
 
+type PluginCreatorOptions = {
+  contentDir: string;
+};
+
+export type PluginCreator = (options: PluginCreatorOptions) => Plugin | Promise<Plugin>;
+
+export type ImportedPlugin =
+  // ES Modules
+  | {
+      default?: PluginCreator;
+    }
+  // CommonJS
+  | PluginCreator
+  // Deprecated format
+  | Plugin;
+
 export type PluginStyleguideConfig<T = undefined> = Omit<
   StyleguideRawConfig<T>,
   'plugins' | 'extends'
@@ -171,6 +186,7 @@ export type RawResolveConfig = {
 
 export type HttpResolveConfig = {
   headers: ResolveHeader[];
+  // eslint-disable-next-line @typescript-eslint/ban-types
   customFetch?: Function;
 };
 

package/src/config/utils.ts

@@ -6,13 +6,15 @@ import {
   showWarningForDeprecatedField,
 } from '../utils';
 import { Config } from './config';
+import { logger, colorize } from '../logger';
+
 import type {
   Api,
   DeprecatedInApi,
   DeprecatedInRawConfig,
+  ImportedPlugin,
   FlatApi,
   FlatRawConfig,
-  Plugin,
   RawConfig,
   RawResolveConfig,
   ResolveConfig,
@@ -20,8 +22,9 @@ import type {
   RulesFields,
   StyleguideRawConfig,
   ThemeConfig,
+  Plugin,
+  PluginCreator,
 } from './types';
-import { logger, colorize } from '../logger';
 
 export function parsePresetName(presetName: string): { pluginId: string; configName: string } {
   if (presetName.indexOf('/') > -1) {
@@ -398,3 +401,11 @@ export class ConfigValidationError extends Error {}
 export function deepCloneMapWithJSON<K, V>(originalMap: Map<K, V>): Map<K, V> {
   return new Map(JSON.parse(JSON.stringify([...originalMap])));
 }
+
+export function isDeprecatedPluginFormat(plugin: ImportedPlugin | undefined): plugin is Plugin {
+  return plugin !== undefined && typeof plugin === 'object' && 'id' in plugin;
+}
+
+export function isCommonJsPlugin(plugin: ImportedPlugin | undefined): plugin is PluginCreator {
+  return typeof plugin === 'function';
+}

package/src/decorators/__tests__/filter-in.test.ts

@@ -56,7 +56,10 @@ describe('oas3 filter-in', () => {
     const { bundle: res } = await bundleDocument({
       document: testDocument,
       externalRefResolver: new BaseResolver(),
-      config: await makeConfig({}, { 'filter-in': { value: 'public', property: 'x-access' } }),
+      config: await makeConfig({
+        rules: {},
+        decorators: { 'filter-in': { value: 'public', property: 'x-access' } },
+      }),
     });
     expect(res.parsed).toMatchInlineSnapshot(`
       openapi: 3.0.0
@@ -76,16 +79,16 @@ describe('oas3 filter-in', () => {
     const { bundle: res } = await bundleDocument({
       document: inputDoc,
       externalRefResolver: new BaseResolver(),
-      config: await makeConfig(
-        {},
-        {
+      config: await makeConfig({
+        rules: {},
+        decorators: {
           'filter-in': {
             property: 'x-audience',
             value: ['Public', 'Protected'],
             matchStrategy: 'all',
           },
-        }
-      ),
+        },
+      }),
     });
     expect(res.parsed).toMatchInlineSnapshot(`
       openapi: 3.0.0
@@ -130,16 +133,16 @@ describe('oas3 filter-in', () => {
     const { bundle: res } = await bundleDocument({
       document: testDoc,
       externalRefResolver: new BaseResolver(),
-      config: await makeConfig(
-        {},
-        {
+      config: await makeConfig({
+        rules: {},
+        decorators: {
           'filter-in': {
             property: 'x-audience',
             value: ['Public', 'Global'],
             matchStrategy: 'any',
           },
-        }
-      ),
+        },
+      }),
     });
     expect(res.parsed).toMatchInlineSnapshot(`
       openapi: 3.0.0
@@ -171,16 +174,16 @@ describe('oas3 filter-in', () => {
     const { bundle: res } = await bundleDocument({
       document: inputDoc,
       externalRefResolver: new BaseResolver(),
-      config: await makeConfig(
-        {},
-        {
+      config: await makeConfig({
+        rules: {},
+        decorators: {
           'filter-in': {
             property: 'x-audience',
             value: 'non-existing-audience',
             matchStrategy: 'any',
           },
-        }
-      ),
+        },
+      }),
     });
     expect(res.parsed).toMatchInlineSnapshot(`
       openapi: 3.0.0
@@ -220,16 +223,16 @@ describe('oas3 filter-in', () => {
     const { bundle: res } = await bundleDocument({
       document: testDoc,
       externalRefResolver: new BaseResolver(),
-      config: await makeConfig(
-        {},
-        {
+      config: await makeConfig({
+        rules: {},
+        decorators: {
           'filter-in': {
             property: 'x-audience',
             value: ['Public', 'Global'],
             matchStrategy: 'any',
           },
-        }
-      ),
+        },
+      }),
     });
     expect(res.parsed).toMatchInlineSnapshot(`
       openapi: 3.0.0
@@ -279,16 +282,16 @@ describe('oas2 filter-in', () => {
     const { bundle: res } = await bundleDocument({
       document: testDoc,
       externalRefResolver: new BaseResolver(),
-      config: await makeConfig(
-        {},
-        {
+      config: await makeConfig({
+        rules: {},
+        decorators: {
           'filter-in': {
             property: 'x-access',
             value: ['public', 'global'],
             matchStrategy: 'any',
           },
-        }
-      ),
+        },
+      }),
     });
     expect(res.parsed).toMatchInlineSnapshot(`
       swagger: '2.0'