@redocly/openapi-core 1.18.0 → 1.19.0

package/src/config/recommended.ts

@@ -96,6 +96,15 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
     'channels-kebab-case': 'off',
     'no-channel-trailing-slash': 'off',
   },
+  async3Rules: {
+    spec: 'error',
+    'info-contact': 'off',
+    'operation-operationId': 'warn',
+    'tag-description': 'warn',
+    'tags-alphabetical': 'off',
+    'channels-kebab-case': 'off',
+    'no-channel-trailing-slash': 'off',
+  },
   arazzoRules: {
     spec: 'error',
   },

package/src/config/rules.ts

@@ -1,6 +1,14 @@
-import { RuleSet, SpecVersion } from '../oas-types';
-import { StyleguideConfig } from './config';
 import { isDefined } from '../utils';
+
+import type {
+  ArazzoRuleSet,
+  Async2RuleSet,
+  Async3RuleSet,
+  Oas2RuleSet,
+  Oas3RuleSet,
+  SpecVersion,
+} from '../oas-types';
+import type { StyleguideConfig } from './config';
 import type { ProblemSeverity } from '../walk';
 
 type InitializedRule = {
@@ -9,8 +17,8 @@ type InitializedRule = {
   visitor: any;
 };
 
-export function initRules<T extends Function, P extends RuleSet<T>>(
-  rules: P[],
+export function initRules(
+  rules: (Oas3RuleSet | Oas2RuleSet | Async2RuleSet | Async3RuleSet | ArazzoRuleSet)[],
   config: StyleguideConfig,
   type: 'rules' | 'preprocessors' | 'decorators',
   oasVersion: SpecVersion

package/src/config/types.ts

@@ -11,6 +11,9 @@ import type {
   Async2PreprocessorsSet,
   Async2DecoratorsSet,
   Async2RuleSet,
+  Async3PreprocessorsSet,
+  Async3DecoratorsSet,
+  Async3RuleSet,
   ArazzoRuleSet,
   ArazzoPreprocessorsSet,
   ArazzoDecoratorsSet,
@@ -22,6 +25,7 @@ import { Location } from '../ref-utils';
 import type { SkipFunctionContext } from '../visitors';
 import {
   BuiltInAsync2RuleId,
+  BuiltInAsync3RuleId,
   BuiltInCommonOASRuleId,
   BuiltInOAS2RuleId,
   BuiltInOAS3RuleId,
@@ -59,6 +63,7 @@ export type StyleguideRawConfig<T = undefined> = {
   oas3_0Rules?: RuleMap<BuiltInOAS3RuleId, RuleConfig, T>;
   oas3_1Rules?: RuleMap<BuiltInOAS3RuleId, RuleConfig, T>;
   async2Rules?: RuleMap<BuiltInAsync2RuleId, RuleConfig, T>;
+  async3Rules?: RuleMap<BuiltInAsync3RuleId, RuleConfig, T>;
   arazzoRules?: RuleMap<BuiltInArazzoRuleId, RuleConfig, T>;
 
   preprocessors?: Record<string, PreprocessorConfig>;
@@ -66,6 +71,7 @@ export type StyleguideRawConfig<T = undefined> = {
   oas3_0Preprocessors?: Record<string, PreprocessorConfig>;
   oas3_1Preprocessors?: Record<string, PreprocessorConfig>;
   async2Preprocessors?: Record<string, PreprocessorConfig>;
+  async3Preprocessors?: Record<string, PreprocessorConfig>;
   arazzoPreprocessors?: Record<string, PreprocessorConfig>;
 
   decorators?: Record<string, DecoratorConfig>;
@@ -73,6 +79,7 @@ export type StyleguideRawConfig<T = undefined> = {
   oas3_0Decorators?: Record<string, DecoratorConfig>;
   oas3_1Decorators?: Record<string, DecoratorConfig>;
   async2Decorators?: Record<string, DecoratorConfig>;
+  async3Decorators?: Record<string, DecoratorConfig>;
   arazzoDecorators?: Record<string, DecoratorConfig>;
 };
 
@@ -90,6 +97,7 @@ export type PreprocessorsConfig = {
   oas3?: Oas3PreprocessorsSet;
   oas2?: Oas2PreprocessorsSet;
   async2?: Async2PreprocessorsSet;
+  async3?: Async3PreprocessorsSet;
   arazzo?: ArazzoPreprocessorsSet;
 };
 
@@ -97,6 +105,7 @@ export type DecoratorsConfig = {
   oas3?: Oas3DecoratorsSet;
   oas2?: Oas2DecoratorsSet;
   async2?: Async2DecoratorsSet;
+  async3?: Async3DecoratorsSet;
   arazzo?: ArazzoDecoratorsSet;
 };
 
@@ -111,6 +120,7 @@ export type CustomRulesConfig = {
   oas3?: Oas3RuleSet;
   oas2?: Oas2RuleSet;
   async2?: Async2RuleSet;
+  async3?: Async3RuleSet;
   arazzo?: ArazzoRuleSet;
 };
 
@@ -243,16 +253,19 @@ export type RulesFields =
   | 'oas3_0Rules'
   | 'oas3_1Rules'
   | 'async2Rules'
+  | 'async3Rules'
   | 'arazzoRules'
   | 'preprocessors'
   | 'oas2Preprocessors'
   | 'oas3_0Preprocessors'
   | 'oas3_1Preprocessors'
   | 'async2Preprocessors'
+  | 'async3Preprocessors'
   | 'arazzoPreprocessors'
   | 'decorators'
   | 'oas2Decorators'
   | 'oas3_0Decorators'
   | 'oas3_1Decorators'
-  | 'arazzoDecorators'
-  | 'async2Decorators';
+  | 'async2Decorators'
+  | 'async3Decorators'
+  | 'arazzoDecorators';

package/src/config/utils.ts

@@ -56,6 +56,7 @@ function extractFlatConfig<
   oas3_0Rules,
   oas3_1Rules,
   async2Rules,
+  async3Rules,
   arazzoRules,
 
   preprocessors,
@@ -63,6 +64,7 @@ function extractFlatConfig<
   oas3_0Preprocessors,
   oas3_1Preprocessors,
   async2Preprocessors,
+  async3Preprocessors,
   arazzoPreprocessors,
 
   decorators,
@@ -70,6 +72,7 @@ function extractFlatConfig<
   oas3_0Decorators,
   oas3_1Decorators,
   async2Decorators,
+  async3Decorators,
   arazzoDecorators,
 
   ...rawConfigRest
@@ -86,6 +89,7 @@ function extractFlatConfig<
     oas3_0Rules,
     oas3_1Rules,
     async2Rules,
+    async3Rules,
     arazzoRules,
 
     preprocessors,
@@ -93,6 +97,7 @@ function extractFlatConfig<
     oas3_0Preprocessors,
     oas3_1Preprocessors,
     async2Preprocessors,
+    async3Preprocessors,
     arazzoPreprocessors,
 
     decorators,
@@ -100,6 +105,7 @@ function extractFlatConfig<
     oas3_0Decorators,
     oas3_1Decorators,
     async2Decorators,
+    async3Decorators,
     arazzoDecorators,
 
     doNotResolveExamples: rawConfigRest.resolve?.doNotResolveExamples,
@@ -158,6 +164,7 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     oas3_0Rules: {},
     oas3_1Rules: {},
     async2Rules: {},
+    async3Rules: {},
     arazzoRules: {},
 
     preprocessors: {},
@@ -165,6 +172,7 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     oas3_0Preprocessors: {},
     oas3_1Preprocessors: {},
     async2Preprocessors: {},
+    async3Preprocessors: {},
     arazzoPreprocessors: {},
 
     decorators: {},
@@ -172,6 +180,7 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     oas3_0Decorators: {},
     oas3_1Decorators: {},
     async2Decorators: {},
+    async3Decorators: {},
     arazzoDecorators: {},
 
     plugins: [],
@@ -195,6 +204,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignExisting(result.oas3_1Rules, rulesConf.rules || {});
     Object.assign(result.async2Rules, rulesConf.async2Rules);
     assignExisting(result.async2Rules, rulesConf.rules || {});
+    Object.assign(result.async3Rules, rulesConf.async3Rules);
+    assignExisting(result.async3Rules, rulesConf.rules || {});
     Object.assign(result.arazzoRules, rulesConf.arazzoRules);
     assignExisting(result.arazzoRules, rulesConf.rules || {});
 
@@ -207,6 +218,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignExisting(result.oas3_1Preprocessors, rulesConf.preprocessors || {});
     Object.assign(result.async2Preprocessors, rulesConf.async2Preprocessors);
     assignExisting(result.async2Preprocessors, rulesConf.preprocessors || {});
+    Object.assign(result.async3Preprocessors, rulesConf.async3Preprocessors);
+    assignExisting(result.async3Preprocessors, rulesConf.preprocessors || {});
     Object.assign(result.arazzoPreprocessors, rulesConf.arazzoPreprocessors);
     assignExisting(result.arazzoPreprocessors, rulesConf.preprocessors || {});
 
@@ -219,6 +232,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignExisting(result.oas3_1Decorators, rulesConf.decorators || {});
     Object.assign(result.async2Decorators, rulesConf.async2Decorators);
     assignExisting(result.async2Decorators, rulesConf.decorators || {});
+    Object.assign(result.async3Decorators, rulesConf.async3Decorators);
+    assignExisting(result.async3Decorators, rulesConf.decorators || {});
     Object.assign(result.arazzoDecorators, rulesConf.arazzoDecorators);
     assignExisting(result.arazzoDecorators, rulesConf.decorators || {});
 

package/src/decorators/async3/index.ts

@@ -0,0 +1 @@
+export const decorators = {};

package/src/decorators/common/remove-x-internal.ts

@@ -6,7 +6,7 @@ import { isRef } from '../../ref-utils';
 const DEFAULT_INTERNAL_PROPERTY_NAME = 'x-internal';
 
 export const RemoveXInternal: Oas3Decorator | Oas2Decorator = ({ internalFlagProperty }) => {
-  const hiddenTag = internalFlagProperty || DEFAULT_INTERNAL_PROPERTY_NAME;
+  const hiddenTag: string = internalFlagProperty || DEFAULT_INTERNAL_PROPERTY_NAME;
 
   function removeInternal(node: any, ctx: UserContext) {
     const { parent, key } = ctx;
@@ -31,7 +31,7 @@ export const RemoveXInternal: Oas3Decorator | Oas2Decorator = ({ internalFlagPro
       for (const key of Object.keys(node)) {
         node = node as any;
         if (isRef(node[key])) {
-          const resolved = ctx.resolve(node[key]);
+          const resolved = ctx.resolve<any>(node[key]);
           if (resolved.node?.[hiddenTag]) {
             delete node[key];
             didDelete = true;

package/src/index.ts

@@ -11,7 +11,8 @@ export { Oas3_1Types } from './types/oas3_1';
 export { ArazzoTypes } from './types/arazzo';
 export { Oas3Types } from './types/oas3';
 export { Oas2Types } from './types/oas2';
-export { AsyncApi2Types } from './types/asyncapi';
+export { AsyncApi2Types } from './types/asyncapi2';
+export { AsyncApi3Types } from './types/asyncapi3';
 export { ConfigTypes } from './types/redocly-yaml';
 export type {
   Oas3Definition,

package/src/lint.ts

@@ -1,3 +1,4 @@
+import { rootRedoclyConfigSchema } from '@redocly/config';
 import { BaseResolver, resolveDocument, makeDocumentFromString } from './resolve';
 import { normalizeVisitors } from './visitors';
 import { walkDocument } from './walk';
@@ -12,16 +13,26 @@ import { NoUnresolvedRefs } from './rules/no-unresolved-refs';
 import type { Document, ResolvedRefMap } from './resolve';
 import type { ProblemSeverity, WalkContext } from './walk';
 import type { NodeType } from './types';
-import type { NestedVisitObject, Oas3Visitor, RuleInstanceConfig } from './visitors';
-import { rootRedoclyConfigSchema } from '@redocly/config';
+import type {
+  ArazzoVisitor,
+  Async2Visitor,
+  Async3Visitor,
+  NestedVisitObject,
+  Oas2Visitor,
+  Oas3Visitor,
+  RuleInstanceConfig,
+} from './visitors';
+import type { CollectFn } from './utils';
 
 export async function lint(opts: {
   ref: string;
   config: Config;
   externalRefResolver?: BaseResolver;
+  collectSpecData?: CollectFn;
 }) {
   const { ref, externalRefResolver = new BaseResolver(opts.config.resolve) } = opts;
   const document = (await externalRefResolver.resolveDocument(null, ref, true)) as Document;
+  opts.collectSpecData?.(document.parsed);
 
   return lintDocument({
     document,
@@ -130,7 +141,19 @@ export async function lintConfig(opts: {
   );
 
   const rules: (RuleInstanceConfig & {
-    visitor: NestedVisitObject<unknown, Oas3Visitor | Oas3Visitor[]>;
+    visitor: NestedVisitObject<
+      unknown,
+      | Oas3Visitor
+      | Oas3Visitor[]
+      | Oas2Visitor
+      | Oas2Visitor[]
+      | Async2Visitor
+      | Async2Visitor[]
+      | Async3Visitor
+      | Async3Visitor[]
+      | ArazzoVisitor
+      | ArazzoVisitor[]
+    >;
   })[] = [
     {
       severity: severity || 'error',

package/src/oas-types.ts

@@ -1,33 +1,37 @@
-import {
+import type {
   Oas3Rule,
   Oas3Preprocessor,
   Oas2Rule,
   Oas2Preprocessor,
   Async2Preprocessor,
   Async2Rule,
+  Async3Preprocessor,
+  Async3Rule,
   ArazzoPreprocessor,
   ArazzoRule,
 } from './visitors';
 import { Oas2Types } from './types/oas2';
 import { Oas3Types } from './types/oas3';
 import { Oas3_1Types } from './types/oas3_1';
-import { AsyncApi2Types } from './types/asyncapi';
+import { AsyncApi2Types } from './types/asyncapi2';
+import { AsyncApi3Types } from './types/asyncapi3';
 import { ArazzoTypes } from './types/arazzo';
-import {
+import type {
   BuiltInAsync2RuleId,
+  BuiltInAsync3RuleId,
   BuiltInCommonOASRuleId,
   BuiltInArazzoRuleId,
   BuiltInOAS2RuleId,
   BuiltInOAS3RuleId,
 } from './types/redocly-yaml';
-
-export type RuleSet<T> = Record<string, T>;
+import { isPlainObject } from './utils';
 
 export enum SpecVersion {
   OAS2 = 'oas2',
   OAS3_0 = 'oas3_0',
   OAS3_1 = 'oas3_1',
-  Async2 = 'async2', // todo split into 2.x maybe?
+  Async2 = 'async2',
+  Async3 = 'async3',
   Arazzo = 'arazzo',
 }
 
@@ -35,6 +39,7 @@ export enum SpecMajorVersion {
   OAS2 = 'oas2',
   OAS3 = 'oas3',
   Async2 = 'async2',
+  Async3 = 'async3',
   Arazzo = 'arazzo',
 }
 
@@ -43,6 +48,7 @@ const typesMap = {
   [SpecVersion.OAS3_0]: Oas3Types,
   [SpecVersion.OAS3_1]: Oas3_1Types,
   [SpecVersion.Async2]: AsyncApi2Types,
+  [SpecVersion.Async3]: AsyncApi3Types,
   [SpecVersion.Arazzo]: ArazzoTypes,
 };
 
@@ -65,6 +71,11 @@ export type Async2RuleSet<T = undefined> = RuleMap<
   Async2Rule,
   T
 >;
+export type Async3RuleSet<T = undefined> = RuleMap<
+  BuiltInAsync3RuleId | 'assertions',
+  Async3Rule,
+  T
+>;
 export type ArazzoRuleSet<T = undefined> = RuleMap<
   BuiltInArazzoRuleId | 'assertions',
   ArazzoRule,
@@ -74,15 +85,17 @@ export type ArazzoRuleSet<T = undefined> = RuleMap<
 export type Oas3PreprocessorsSet = Record<string, Oas3Preprocessor>;
 export type Oas2PreprocessorsSet = Record<string, Oas2Preprocessor>;
 export type Async2PreprocessorsSet = Record<string, Async2Preprocessor>;
+export type Async3PreprocessorsSet = Record<string, Async3Preprocessor>;
 export type ArazzoPreprocessorsSet = Record<string, ArazzoPreprocessor>;
 
 export type Oas3DecoratorsSet = Record<string, Oas3Preprocessor>;
 export type Oas2DecoratorsSet = Record<string, Oas2Preprocessor>;
 export type Async2DecoratorsSet = Record<string, Async2Preprocessor>;
+export type Async3DecoratorsSet = Record<string, Async3Preprocessor>;
 export type ArazzoDecoratorsSet = Record<string, ArazzoPreprocessor>;
 
-export function detectSpec(root: any): SpecVersion {
-  if (typeof root !== 'object') {
+export function detectSpec(root: unknown): SpecVersion {
+  if (!isPlainObject(root)) {
     throw new Error(`Document must be JSON object, got ${typeof root}`);
   }
 
@@ -90,11 +103,11 @@ export function detectSpec(root: any): SpecVersion {
     throw new Error(`Invalid OpenAPI version: should be a string but got "${typeof root.openapi}"`);
   }
 
-  if (root.openapi && root.openapi.startsWith('3.0')) {
+  if (typeof root.openapi === 'string' && root.openapi.startsWith('3.0')) {
     return SpecVersion.OAS3_0;
   }
 
-  if (root.openapi && root.openapi.startsWith('3.1')) {
+  if (typeof root.openapi === 'string' && root.openapi.startsWith('3.1')) {
     return SpecVersion.OAS3_1;
   }
 
@@ -102,20 +115,23 @@ export function detectSpec(root: any): SpecVersion {
     return SpecVersion.OAS2;
   }
 
-  // if not detected yet
   if (root.openapi || root.swagger) {
     throw new Error(`Unsupported OpenAPI version: ${root.openapi || root.swagger}`);
   }
 
-  if (root.asyncapi && root.asyncapi.startsWith('2.')) {
+  if (typeof root.asyncapi === 'string' && root.asyncapi.startsWith('2.')) {
     return SpecVersion.Async2;
   }
 
+  if (typeof root.asyncapi === 'string' && root.asyncapi.startsWith('3.')) {
+    return SpecVersion.Async3;
+  }
+
   if (root.asyncapi) {
     throw new Error(`Unsupported AsyncAPI version: ${root.asyncapi}`);
   }
 
-  if (root.arazzo && root.arazzo.startsWith('1.')) {
+  if (typeof root.arazzo === 'string' && root.arazzo.startsWith('1.')) {
     return SpecVersion.Arazzo;
   }
 
@@ -127,6 +143,8 @@ export function getMajorSpecVersion(version: SpecVersion): SpecMajorVersion {
     return SpecMajorVersion.OAS2;
   } else if (version === SpecVersion.Async2) {
     return SpecMajorVersion.Async2;
+  } else if (version === SpecVersion.Async3) {
+    return SpecMajorVersion.Async3;
   } else if (version === SpecVersion.Arazzo) {
     return SpecMajorVersion.Arazzo;
   } else {

package/src/rules/arazzo/index.ts

@@ -5,7 +5,7 @@ import { Assertions } from '../common/assertions';
 
 export const rules: ArazzoRuleSet<'built-in'> = {
   spec: Spec as ArazzoRule,
-  assertions: Assertions,
+  assertions: Assertions as ArazzoRule,
 };
 
 export const preprocessors = {};

package/src/rules/async2/index.ts

@@ -11,13 +11,13 @@ import type { Async2RuleSet } from '../../oas-types';
 
 export const rules: Async2RuleSet<'built-in'> = {
   spec: Spec as Async2Rule,
-  assertions: Assertions,
-  'info-contact': InfoContact,
-  'operation-operationId': OperationOperationId,
+  assertions: Assertions as Async2Rule,
+  'info-contact': InfoContact as Async2Rule,
+  'operation-operationId': OperationOperationId as Async2Rule,
   'channels-kebab-case': ChannelsKebabCase,
   'no-channel-trailing-slash': NoChannelTrailingSlash,
-  'tag-description': TagDescription,
-  'tags-alphabetical': TagsAlphabetical,
+  'tag-description': TagDescription as Async2Rule,
+  'tags-alphabetical': TagsAlphabetical as Async2Rule,
 };
 
 export const preprocessors = {};

package/src/rules/async3/__tests__/channels-kebab-case.test.ts

@@ -0,0 +1,141 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('Async2 channels-kebab-case', () => {
+  it('should report on no kebab-case channel path', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '3.0.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          channel1:
+            address: /NOT_A_KEBAB/
+            payload:
+              type: object
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'channels-kebab-case': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/channels/channel1",
+              "reportOnKey": true,
+              "source": "asyncapi.yaml",
+            },
+          ],
+          "message": "\`/NOT_A_KEBAB/\` does not use kebab-case.",
+          "ruleId": "channels-kebab-case",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report on snake_case in channel path', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '3.0.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          channel1:
+            address: snake_kebab
+            payload:
+              type: object
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'channels-kebab-case': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/channels/channel1",
+              "reportOnKey": true,
+              "source": "asyncapi.yaml",
+            },
+          ],
+          "message": "\`snake_kebab\` does not use kebab-case.",
+          "ruleId": "channels-kebab-case",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should allow trailing slash in channel path with "channels-kebab-case" rule', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '3.0.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          channel1:
+            address: kebab/
+            payload:
+              type: object
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'paths-kebab-case': 'error',
+        'no-path-trailing-slash': 'off',
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('words with hyphens are allowed with "channels-kebab-case" rule', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '3.0.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          channel1:
+            address: kebab-with-longer-channel-path:/
+            payload:
+              type: object
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'paths-kebab-case': 'error',
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+});