@redocly/openapi-core 1.2.1 → 1.4.0

package/src/config/all.ts

@@ -1,6 +1,6 @@
 import type { PluginStyleguideConfig } from './types';
 
-export default {
+const all: PluginStyleguideConfig<'built-in'> = {
   rules: {
     'info-contact': 'error',
     'info-license': 'error',
@@ -28,13 +28,24 @@ export default {
     'operation-singular-tag': 'error',
     'no-unresolved-refs': 'error',
     'no-enum-type-mismatch': 'error',
-    'boolean-parameter-prefixes': 'error',
     'paths-kebab-case': 'error',
     'no-http-verbs-in-paths': 'error',
     'path-excludes-patterns': {
       severity: 'error',
       patterns: [],
     },
+    spec: 'error',
+    'no-invalid-schema-examples': 'error',
+    'no-invalid-parameter-examples': 'error',
+    'scalar-property-missing-example': 'error',
+    'spec-strict-refs': 'error',
+    'path-http-verbs-order': 'error',
+    'path-params-defined': 'error',
+    'required-string-property-missing-min-length': 'error',
+    'response-contains-header': 'error',
+  },
+  oas2Rules: {
+    'boolean-parameter-prefixes': 'error',
     'request-mime-type': {
       severity: 'error',
       allowedValues: ['application/json'],
@@ -43,12 +54,7 @@ export default {
       severity: 'error',
       allowedValues: ['application/json'],
     },
-    spec: 'error',
-    'no-invalid-schema-examples': 'error',
-    'no-invalid-parameter-examples': 'error',
-    'scalar-property-missing-example': 'error',
-    'spec-strict-refs': 'error',
-    'component-name-unique': 'error',
+    'response-contains-property': 'error',
   },
   oas3_0Rules: {
     'no-invalid-media-type-examples': 'error',
@@ -60,8 +66,21 @@ export default {
     'no-undefined-server-variable': 'error',
     'no-server-variables-empty-enum': 'error',
     'operation-4xx-problem-details-rfc7807': 'error',
+    'boolean-parameter-prefixes': 'error',
+    'request-mime-type': {
+      severity: 'error',
+      allowedValues: ['application/json'],
+    },
+    'response-mime-type': {
+      severity: 'error',
+      allowedValues: ['application/json'],
+    },
+    'component-name-unique': 'error',
+    'response-contains-property': 'error',
+    'spec-components-invalid-map-name': 'error',
   },
   oas3_1Rules: {
+    'no-invalid-media-type-examples': 'error',
     'no-server-example.com': 'error',
     'no-server-trailing-slash': 'error',
     'no-empty-servers': 'error',
@@ -70,5 +89,23 @@ export default {
     'no-undefined-server-variable': 'error',
     'no-server-variables-empty-enum': 'error',
     'operation-4xx-problem-details-rfc7807': 'error',
+    'boolean-parameter-prefixes': 'error',
+    'request-mime-type': {
+      severity: 'error',
+      allowedValues: ['application/json'],
+    },
+    'response-mime-type': {
+      severity: 'error',
+      allowedValues: ['application/json'],
+    },
+    'component-name-unique': 'error',
+    'response-contains-property': 'error',
+    'spec-components-invalid-map-name': 'error',
   },
-} as PluginStyleguideConfig;
+  async2Rules: {
+    'channels-kebab-case': 'error',
+    'no-channel-trailing-slash': 'error',
+  },
+};
+
+export default all;

package/src/config/builtIn.ts

@@ -1,4 +1,5 @@
 import recommended from './recommended';
+import recommendedStrict from './recommended-strict';
 import all from './all';
 import minimal from './minimal';
 import { rules as oas3Rules } from '../rules/oas3';
@@ -13,6 +14,7 @@ import type { CustomRulesConfig, StyleguideRawConfig, Plugin } from './types';
 
 export const builtInConfigs: Record<string, StyleguideRawConfig> = {
   recommended,
+  'recommended-strict': recommendedStrict,
   minimal,
   all,
   'redocly-registry': {

package/src/config/load.ts

@@ -4,7 +4,7 @@ import { RedoclyClient } from '../redocly';
 import { isEmptyObject, loadYaml, doesYamlFileExist } from '../utils';
 import { parseYaml } from '../js-yaml';
 import { Config, DOMAINS } from './config';
-import { transformConfig } from './utils';
+import { ConfigValidationError, transformConfig } from './utils';
 import { resolveConfig } from './config-resolvers';
 
 import type {
@@ -128,6 +128,9 @@ export async function getConfig(
     }
     return transformConfig(rawConfig);
   } catch (e) {
+    if (e instanceof ConfigValidationError) {
+      throw e;
+    }
     throw new Error(`Error parsing config file at '${configPath}': ${e.message}`);
   }
 }

package/src/config/minimal.ts

@@ -1,6 +1,6 @@
 import type { PluginStyleguideConfig } from './types';
 
-export default {
+const minimal: PluginStyleguideConfig<'built-in'> = {
   rules: {
     'info-contact': 'off',
     'info-license': 'off',
@@ -27,11 +27,25 @@ export default {
     'operation-singular-tag': 'off',
     'no-unresolved-refs': 'error',
     'no-enum-type-mismatch': 'warn',
-    'boolean-parameter-prefixes': 'off',
     'paths-kebab-case': 'off',
     spec: 'error',
     'spec-strict-refs': 'off',
-    'component-name-unique': 'off',
+    'no-http-verbs-in-paths': 'off',
+    'no-invalid-parameter-examples': 'off',
+    'no-invalid-schema-examples': 'off',
+    'path-excludes-patterns': 'off',
+    'path-http-verbs-order': 'off',
+    'path-params-defined': 'off',
+    'required-string-property-missing-min-length': 'off',
+    'response-contains-header': 'off',
+    'path-segment-plural': 'off',
+    'scalar-property-missing-example': 'off',
+  },
+  oas2Rules: {
+    'boolean-parameter-prefixes': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
   },
   oas3_0Rules: {
     'no-invalid-media-type-examples': {
@@ -46,6 +60,12 @@ export default {
     'no-undefined-server-variable': 'warn',
     'no-server-variables-empty-enum': 'error',
     'spec-components-invalid-map-name': 'warn',
+    'boolean-parameter-prefixes': 'off',
+    'component-name-unique': 'off',
+    'operation-4xx-problem-details-rfc7807': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
   },
   oas3_1Rules: {
     'no-invalid-media-type-examples': 'warn',
@@ -57,5 +77,17 @@ export default {
     'no-undefined-server-variable': 'warn',
     'no-server-variables-empty-enum': 'error',
     'spec-components-invalid-map-name': 'warn',
+    'boolean-parameter-prefixes': 'off',
+    'component-name-unique': 'off',
+    'operation-4xx-problem-details-rfc7807': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
   },
-} as PluginStyleguideConfig;
+  async2Rules: {
+    'channels-kebab-case': 'off',
+    'no-channel-trailing-slash': 'off',
+  },
+};
+
+export default minimal;

package/src/config/recommended-strict.ts

@@ -0,0 +1,93 @@
+import type { PluginStyleguideConfig } from './types';
+
+const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
+  rules: {
+    'info-contact': 'off',
+    'info-license': 'error',
+    'info-license-url': 'error',
+    'tag-description': 'error',
+    'tags-alphabetical': 'off',
+    'parameter-description': 'off',
+    'no-path-trailing-slash': 'error',
+    'no-identical-paths': 'error',
+    'no-ambiguous-paths': 'error',
+    'path-declaration-must-exist': 'error',
+    'path-not-include-query': 'error',
+    'path-parameters-defined': 'error',
+    'operation-description': 'off',
+    'operation-2xx-response': 'error',
+    'operation-4xx-response': 'error',
+    'operation-operationId': 'error',
+    'operation-summary': 'error',
+    'operation-operationId-unique': 'error',
+    'operation-operationId-url-safe': 'error',
+    'operation-parameters-unique': 'error',
+    'operation-tag-defined': 'off',
+    'security-defined': 'error',
+    'operation-singular-tag': 'off',
+    'no-unresolved-refs': 'error',
+    'no-enum-type-mismatch': 'error',
+    'paths-kebab-case': 'off',
+    spec: 'error',
+    'spec-strict-refs': 'off',
+    'no-http-verbs-in-paths': 'off',
+    'no-invalid-parameter-examples': 'off',
+    'no-invalid-schema-examples': 'off',
+    'path-excludes-patterns': 'off',
+    'path-http-verbs-order': 'off',
+    'path-params-defined': 'off',
+    'path-segment-plural': 'off',
+    'required-string-property-missing-min-length': 'off',
+    'response-contains-header': 'off',
+    'scalar-property-missing-example': 'off',
+  },
+  oas2Rules: {
+    'boolean-parameter-prefixes': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
+  },
+  oas3_0Rules: {
+    'no-invalid-media-type-examples': {
+      severity: 'error',
+      allowAdditionalProperties: false,
+    },
+    'no-server-example.com': 'error',
+    'no-server-trailing-slash': 'error',
+    'no-empty-servers': 'error',
+    'no-example-value-and-externalValue': 'error',
+    'no-unused-components': 'error',
+    'no-undefined-server-variable': 'error',
+    'no-server-variables-empty-enum': 'error',
+    'spec-components-invalid-map-name': 'error',
+    'boolean-parameter-prefixes': 'off',
+    'component-name-unique': 'off',
+    'operation-4xx-problem-details-rfc7807': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
+  },
+  oas3_1Rules: {
+    'no-invalid-media-type-examples': 'error',
+    'no-server-example.com': 'error',
+    'no-server-trailing-slash': 'error',
+    'no-empty-servers': 'error',
+    'no-example-value-and-externalValue': 'error',
+    'no-unused-components': 'error',
+    'no-undefined-server-variable': 'error',
+    'no-server-variables-empty-enum': 'error',
+    'spec-components-invalid-map-name': 'error',
+    'boolean-parameter-prefixes': 'off',
+    'component-name-unique': 'off',
+    'operation-4xx-problem-details-rfc7807': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
+  },
+  async2Rules: {
+    'channels-kebab-case': 'off',
+    'no-channel-trailing-slash': 'off',
+  },
+};
+
+export default recommendedStrict;

package/src/config/recommended.ts

@@ -1,6 +1,6 @@
 import type { PluginStyleguideConfig } from './types';
 
-export default {
+const recommended: PluginStyleguideConfig<'built-in'> = {
   rules: {
     'info-contact': 'off',
     'info-license': 'warn',
@@ -27,11 +27,25 @@ export default {
     'operation-singular-tag': 'off',
     'no-unresolved-refs': 'error',
     'no-enum-type-mismatch': 'error',
-    'boolean-parameter-prefixes': 'off',
     'paths-kebab-case': 'off',
     spec: 'error',
     'spec-strict-refs': 'off',
-    'component-name-unique': 'off',
+    'no-http-verbs-in-paths': 'off',
+    'no-invalid-parameter-examples': 'off',
+    'no-invalid-schema-examples': 'off',
+    'path-excludes-patterns': 'off',
+    'path-http-verbs-order': 'off',
+    'path-params-defined': 'off',
+    'path-segment-plural': 'off',
+    'required-string-property-missing-min-length': 'off',
+    'response-contains-header': 'off',
+    'scalar-property-missing-example': 'off',
+  },
+  oas2Rules: {
+    'boolean-parameter-prefixes': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
   },
   oas3_0Rules: {
     'no-invalid-media-type-examples': {
@@ -46,6 +60,12 @@ export default {
     'no-undefined-server-variable': 'error',
     'no-server-variables-empty-enum': 'error',
     'spec-components-invalid-map-name': 'error',
+    'boolean-parameter-prefixes': 'off',
+    'component-name-unique': 'off',
+    'operation-4xx-problem-details-rfc7807': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
   },
   oas3_1Rules: {
     'no-invalid-media-type-examples': 'warn',
@@ -57,5 +77,17 @@ export default {
     'no-undefined-server-variable': 'error',
     'no-server-variables-empty-enum': 'error',
     'spec-components-invalid-map-name': 'error',
+    'boolean-parameter-prefixes': 'off',
+    'component-name-unique': 'off',
+    'operation-4xx-problem-details-rfc7807': 'off',
+    'request-mime-type': 'off',
+    'response-contains-property': 'off',
+    'response-mime-type': 'off',
   },
-} as PluginStyleguideConfig;
+  async2Rules: {
+    'channels-kebab-case': 'off',
+    'no-channel-trailing-slash': 'off',
+  },
+};
+
+export default recommended;

package/src/config/types.ts

@@ -11,11 +11,19 @@ import type {
   Async2PreprocessorsSet,
   Async2DecoratorsSet,
   Async2RuleSet,
+  RuleMap,
 } from '../oas-types';
 
 import type { NodeType } from '../types';
 import { Location } from '../ref-utils';
 import type { SkipFunctionContext } from '../visitors';
+import {
+  BuiltInAsync2RuleId,
+  BuiltInCommonOASRuleId,
+  BuiltInCommonRuleId,
+  BuiltInOAS2RuleId,
+  BuiltInOAS3RuleId,
+} from '../types/redocly-yaml';
 
 export type RuleSeverity = ProblemSeverity | 'off';
 
@@ -37,17 +45,17 @@ export type PreprocessorConfig =
 
 export type DecoratorConfig = PreprocessorConfig;
 
-export type StyleguideRawConfig = {
+export type StyleguideRawConfig<T = undefined> = {
   plugins?: (string | Plugin)[];
   extends?: string[];
   doNotResolveExamples?: boolean;
   recommendedFallback?: boolean;
 
-  rules?: Record<string, RuleConfig>;
-  oas2Rules?: Record<string, RuleConfig>;
-  oas3_0Rules?: Record<string, RuleConfig>;
-  oas3_1Rules?: Record<string, RuleConfig>;
-  async2Rules?: Record<string, RuleConfig>;
+  rules?: RuleMap<BuiltInCommonRuleId | BuiltInCommonOASRuleId, RuleConfig, T>;
+  oas2Rules?: RuleMap<BuiltInOAS2RuleId, RuleConfig, T>;
+  oas3_0Rules?: RuleMap<BuiltInOAS3RuleId, RuleConfig, T>;
+  oas3_1Rules?: RuleMap<BuiltInOAS3RuleId, RuleConfig, T>;
+  async2Rules?: RuleMap<BuiltInAsync2RuleId, RuleConfig, T>;
 
   preprocessors?: Record<string, PreprocessorConfig>;
   oas2Preprocessors?: Record<string, PreprocessorConfig>;
@@ -118,7 +126,10 @@ export type Plugin = {
   assertions?: AssertionsConfig;
 };
 
-export type PluginStyleguideConfig = Omit<StyleguideRawConfig, 'plugins' | 'extends'>;
+export type PluginStyleguideConfig<T = undefined> = Omit<
+  StyleguideRawConfig<T>,
+  'plugins' | 'extends'
+>;
 
 export type ResolveHeader =
   | {
@@ -221,14 +232,17 @@ export type RulesFields =
   | 'oas2Rules'
   | 'oas3_0Rules'
   | 'oas3_1Rules'
+  | 'async2Rules'
   | 'preprocessors'
   | 'oas2Preprocessors'
   | 'oas3_0Preprocessors'
   | 'oas3_1Preprocessors'
+  | 'async2Preprocessors'
   | 'decorators'
   | 'oas2Decorators'
   | 'oas3_0Decorators'
-  | 'oas3_1Decorators';
+  | 'oas3_1Decorators'
+  | 'async2Decorators';
 
 export enum AuthProviderType {
   OIDC = 'OIDC',

package/src/config/utils.ts

@@ -55,16 +55,19 @@ function extractFlatConfig<
   oas2Rules,
   oas3_0Rules,
   oas3_1Rules,
+  async2Rules,
 
   preprocessors,
   oas2Preprocessors,
   oas3_0Preprocessors,
   oas3_1Preprocessors,
+  async2Preprocessors,
 
   decorators,
   oas2Decorators,
   oas3_0Decorators,
   oas3_1Decorators,
+  async2Decorators,
 
   ...rawConfigRest
 }: T): {
@@ -79,16 +82,19 @@ function extractFlatConfig<
     oas2Rules,
     oas3_0Rules,
     oas3_1Rules,
+    async2Rules,
 
     preprocessors,
     oas2Preprocessors,
     oas3_0Preprocessors,
     oas3_1Preprocessors,
+    async2Preprocessors,
 
     decorators,
     oas2Decorators,
     oas3_0Decorators,
     oas3_1Decorators,
+    async2Decorators,
 
     doNotResolveExamples: rawConfigRest.resolve?.doNotResolveExamples,
   };
@@ -145,16 +151,19 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     oas2Rules: {},
     oas3_0Rules: {},
     oas3_1Rules: {},
+    async2Rules: {},
 
     preprocessors: {},
     oas2Preprocessors: {},
     oas3_0Preprocessors: {},
     oas3_1Preprocessors: {},
+    async2Preprocessors: {},
 
     decorators: {},
     oas2Decorators: {},
     oas3_0Decorators: {},
     oas3_1Decorators: {},
+    async2Decorators: {},
 
     plugins: [],
     pluginPaths: [],
@@ -175,6 +184,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignExisting(result.oas3_0Rules, rulesConf.rules || {});
     Object.assign(result.oas3_1Rules, rulesConf.oas3_1Rules);
     assignExisting(result.oas3_1Rules, rulesConf.rules || {});
+    Object.assign(result.async2Rules, rulesConf.async2Rules);
+    assignExisting(result.async2Rules, rulesConf.rules || {});
 
     Object.assign(result.preprocessors, rulesConf.preprocessors);
     Object.assign(result.oas2Preprocessors, rulesConf.oas2Preprocessors);
@@ -183,6 +194,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignExisting(result.oas3_0Preprocessors, rulesConf.preprocessors || {});
     Object.assign(result.oas3_1Preprocessors, rulesConf.oas3_1Preprocessors);
     assignExisting(result.oas3_1Preprocessors, rulesConf.preprocessors || {});
+    Object.assign(result.async2Preprocessors, rulesConf.async2Preprocessors);
+    assignExisting(result.async2Preprocessors, rulesConf.preprocessors || {});
 
     Object.assign(result.decorators, rulesConf.decorators);
     Object.assign(result.oas2Decorators, rulesConf.oas2Decorators);
@@ -191,6 +204,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignExisting(result.oas3_0Decorators, rulesConf.decorators || {});
     Object.assign(result.oas3_1Decorators, rulesConf.oas3_1Decorators);
     assignExisting(result.oas3_1Decorators, rulesConf.decorators || {});
+    Object.assign(result.async2Decorators, rulesConf.async2Decorators);
+    assignExisting(result.async2Decorators, rulesConf.decorators || {});
 
     result.plugins!.push(...(rulesConf.plugins || []));
     result.pluginPaths!.push(...(rulesConf.pluginPaths || []));
@@ -347,3 +362,5 @@ export function getUniquePlugins(plugins: Plugin[]): Plugin[] {
   }
   return results;
 }
+
+export class ConfigValidationError extends Error {}

package/src/decorators/common/media-type-examples-override.ts

@@ -2,7 +2,7 @@ import { Oas3Decorator } from '../../visitors';
 import { Oas3Operation, Oas3RequestBody, Oas3Response } from '../../typings/openapi';
 import { yamlAndJsonSyncReader } from '../../utils';
 import { isRef } from '../../ref-utils';
-import { ResolveFn, UserContext } from '../../walk';
+import { NonUndefined, ResolveFn, UserContext } from '../../walk';
 
 export const MediaTypeExamplesOverride: Oas3Decorator = ({ operationIds }) => {
   return {
@@ -69,7 +69,7 @@ export const MediaTypeExamplesOverride: Oas3Decorator = ({ operationIds }) => {
   };
 };
 
-function checkAndResolveRef<T>(node: any, resolver: ResolveFn): T | undefined {
+function checkAndResolveRef<T extends NonUndefined>(node: any, resolver: ResolveFn): T | undefined {
   if (!isRef(node)) {
     return node;
   }

package/src/lint.ts

@@ -5,7 +5,7 @@ import { ProblemSeverity, WalkContext, walkDocument } from './walk';
 import { StyleguideConfig, Config, initRules, defaultPlugin, resolvePlugins } from './config';
 import { normalizeTypes } from './types';
 import { releaseAjvInstance } from './rules/ajv';
-import { Oas3RuleSet, SpecVersion, getMajorSpecVersion, detectSpec, getTypes } from './oas-types';
+import { SpecVersion, getMajorSpecVersion, detectSpec, getTypes } from './oas-types';
 import { ConfigTypes } from './types/redocly-yaml';
 import { Spec } from './rules/common/spec';
 
@@ -65,8 +65,8 @@ export async function lintDocument(opts: {
     visitorsData: {},
   };
 
-  const preprocessors = initRules(rules as any, config, 'preprocessors', specVersion);
-  const regularRules = initRules(rules as Oas3RuleSet[], config, 'rules', specVersion);
+  const preprocessors = initRules(rules, config, 'preprocessors', specVersion);
+  const regularRules = initRules(rules, config, 'rules', specVersion);
 
   let resolvedRefMap = await resolveDocument({
     rootDocument: document,

package/src/oas-types.ts

@@ -10,6 +10,13 @@ import { Oas2Types } from './types/oas2';
 import { Oas3Types } from './types/oas3';
 import { Oas3_1Types } from './types/oas3_1';
 import { AsyncApi2Types } from './types/asyncapi';
+import {
+  BuiltInAsync2RuleId,
+  BuiltInCommonOASRuleId,
+  BuiltInCommonRuleId,
+  BuiltInOAS2RuleId,
+  BuiltInOAS3RuleId,
+} from './types/redocly-yaml';
 
 export type RuleSet<T> = Record<string, T>;
 
@@ -33,9 +40,25 @@ const typesMap = {
   [SpecVersion.Async2]: AsyncApi2Types,
 };
 
-export type Oas3RuleSet = Record<string, Oas3Rule>;
-export type Oas2RuleSet = Record<string, Oas2Rule>;
-export type Async2RuleSet = Record<string, Async2Rule>;
+export type RuleMap<Key extends string, RuleConfig, T> = Record<
+  T extends 'built-in' ? Key : string,
+  RuleConfig
+>;
+export type Oas3RuleSet<T = undefined> = RuleMap<
+  BuiltInCommonRuleId | BuiltInCommonOASRuleId | BuiltInOAS3RuleId | 'assertions',
+  Oas3Rule,
+  T
+>;
+export type Oas2RuleSet<T = undefined> = RuleMap<
+  BuiltInCommonRuleId | BuiltInCommonOASRuleId | BuiltInOAS2RuleId | 'assertions',
+  Oas2Rule,
+  T
+>;
+export type Async2RuleSet<T = undefined> = RuleMap<
+  BuiltInCommonRuleId | BuiltInAsync2RuleId | 'assertions',
+  Async2Rule,
+  T
+>;
 export type Oas3PreprocessorsSet = Record<string, Oas3Preprocessor>;
 export type Oas2PreprocessorsSet = Record<string, Oas2Preprocessor>;
 export type Async2PreprocessorsSet = Record<string, Async2Preprocessor>;