@redocly/openapi-core 1.0.2 → 1.2.0

package/src/lint.ts

@@ -1,16 +1,13 @@
 import { BaseResolver, resolveDocument, Document, makeDocumentFromString } from './resolve';
 import { normalizeVisitors } from './visitors';
-import { Oas3_1Types } from './types/oas3_1';
-import { Oas3Types } from './types/oas3';
-import { Oas2Types } from './types/oas2';
 import { NodeType } from './types';
 import { ProblemSeverity, WalkContext, walkDocument } from './walk';
 import { StyleguideConfig, Config, initRules, defaultPlugin, resolvePlugins } from './config';
 import { normalizeTypes } from './types';
 import { releaseAjvInstance } from './rules/ajv';
-import { detectOpenAPI, Oas3RuleSet, OasMajorVersion, OasVersion, openAPIMajor } from './oas-types';
+import { Oas3RuleSet, SpecVersion, getMajorSpecVersion, detectSpec, getTypes } from './oas-types';
 import { ConfigTypes } from './types/redocly-yaml';
-import { OasSpec } from './rules/common/spec';
+import { Spec } from './rules/common/spec';
 
 export async function lint(opts: {
   ref: string;
@@ -54,29 +51,22 @@ export async function lintDocument(opts: {
   releaseAjvInstance(); // FIXME: preprocessors can modify nodes which are then cached to ajv-instance by absolute path
 
   const { document, customTypes, externalRefResolver, config } = opts;
-  const oasVersion = detectOpenAPI(document.parsed);
-  const oasMajorVersion = openAPIMajor(oasVersion);
-  const rules = config.getRulesForOasVersion(oasMajorVersion);
+  const specVersion = detectSpec(document.parsed);
+  const specMajorVersion = getMajorSpecVersion(specVersion);
+  const rules = config.getRulesForOasVersion(specMajorVersion);
   const types = normalizeTypes(
-    config.extendTypes(
-      customTypes ?? oasMajorVersion === OasMajorVersion.Version3
-        ? oasVersion === OasVersion.Version3_1
-          ? Oas3_1Types
-          : Oas3Types
-        : Oas2Types,
-      oasVersion
-    ),
+    config.extendTypes(customTypes ?? getTypes(specVersion), specVersion),
     config
   );
 
   const ctx: WalkContext = {
     problems: [],
-    oasVersion: oasVersion,
+    oasVersion: specVersion,
     visitorsData: {},
   };
 
-  const preprocessors = initRules(rules as any, config, 'preprocessors', oasVersion);
-  const regularRules = initRules(rules as Oas3RuleSet[], config, 'rules', oasVersion);
+  const preprocessors = initRules(rules as any, config, 'preprocessors', specVersion);
+  const regularRules = initRules(rules as Oas3RuleSet[], config, 'rules', specVersion);
 
   let resolvedRefMap = await resolveDocument({
     rootDocument: document,
@@ -117,7 +107,7 @@ export async function lintConfig(opts: { document: Document; severity?: ProblemS
 
   const ctx: WalkContext = {
     problems: [],
-    oasVersion: OasVersion.Version3_0,
+    oasVersion: SpecVersion.OAS3_0,
     visitorsData: {},
   };
   const plugins = resolvePlugins([defaultPlugin]);
@@ -131,10 +121,11 @@ export async function lintConfig(opts: { document: Document; severity?: ProblemS
     {
       severity: severity || 'error',
       ruleId: 'configuration spec',
-      visitor: OasSpec({ severity: 'error' }),
+      visitor: Spec({ severity: 'error' }),
     },
   ];
-  const normalizedVisitors = normalizeVisitors(rules, types);
+  // TODO: check why any is needed
+  const normalizedVisitors = normalizeVisitors(rules as any, types);
 
   walkDocument({
     document,

package/src/oas-types.ts

@@ -1,57 +1,95 @@
-import { Oas3Rule, Oas3Preprocessor, Oas2Rule, Oas2Preprocessor } from './visitors';
+import {
+  Oas3Rule,
+  Oas3Preprocessor,
+  Oas2Rule,
+  Oas2Preprocessor,
+  Async2Preprocessor,
+  Async2Rule,
+} from './visitors';
+import { Oas2Types } from './types/oas2';
+import { Oas3Types } from './types/oas3';
+import { Oas3_1Types } from './types/oas3_1';
+import { AsyncApi2Types } from './types/asyncapi';
 
 export type RuleSet<T> = Record<string, T>;
 
-export enum OasVersion {
-  Version2 = 'oas2',
-  Version3_0 = 'oas3_0',
-  Version3_1 = 'oas3_1',
+export enum SpecVersion {
+  OAS2 = 'oas2',
+  OAS3_0 = 'oas3_0',
+  OAS3_1 = 'oas3_1',
+  Async2 = 'async2', // todo split into 2.x maybe?
 }
 
-export enum OasMajorVersion {
-  Version2 = 'oas2',
-  Version3 = 'oas3',
+export enum SpecMajorVersion {
+  OAS2 = 'oas2',
+  OAS3 = 'oas3',
+  Async2 = 'async2',
 }
 
+const typesMap = {
+  [SpecVersion.OAS2]: Oas2Types,
+  [SpecVersion.OAS3_0]: Oas3Types,
+  [SpecVersion.OAS3_1]: Oas3_1Types,
+  [SpecVersion.Async2]: AsyncApi2Types,
+};
+
 export type Oas3RuleSet = Record<string, Oas3Rule>;
 export type Oas2RuleSet = Record<string, Oas2Rule>;
+export type Async2RuleSet = Record<string, Async2Rule>;
 export type Oas3PreprocessorsSet = Record<string, Oas3Preprocessor>;
 export type Oas2PreprocessorsSet = Record<string, Oas2Preprocessor>;
+export type Async2PreprocessorsSet = Record<string, Async2Preprocessor>;
 export type Oas3DecoratorsSet = Record<string, Oas3Preprocessor>;
 export type Oas2DecoratorsSet = Record<string, Oas2Preprocessor>;
+export type Async2DecoratorsSet = Record<string, Async2Preprocessor>;
 
-export function detectOpenAPI(root: any): OasVersion {
+export function detectSpec(root: any): SpecVersion {
   if (typeof root !== 'object') {
     throw new Error(`Document must be JSON object, got ${typeof root}`);
   }
 
-  if (!(root.openapi || root.swagger)) {
-    throw new Error('This doesn’t look like an OpenAPI document.\n');
-  }
-
   if (root.openapi && typeof root.openapi !== 'string') {
     throw new Error(`Invalid OpenAPI version: should be a string but got "${typeof root.openapi}"`);
   }
 
   if (root.openapi && root.openapi.startsWith('3.0')) {
-    return OasVersion.Version3_0;
+    return SpecVersion.OAS3_0;
   }
 
   if (root.openapi && root.openapi.startsWith('3.1')) {
-    return OasVersion.Version3_1;
+    return SpecVersion.OAS3_1;
   }
 
   if (root.swagger && root.swagger === '2.0') {
-    return OasVersion.Version2;
+    return SpecVersion.OAS2;
   }
 
-  throw new Error(`Unsupported OpenAPI Version: ${root.openapi || root.swagger}`);
+  // 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.')) {
+    return SpecVersion.Async2;
+  }
+
+  if (root.asyncapi) {
+    throw new Error(`Unsupported AsyncAPI version: ${root.asyncapi}`);
+  }
+
+  throw new Error(`Unsupported specification`);
 }
 
-export function openAPIMajor(version: OasVersion): OasMajorVersion {
-  if (version === OasVersion.Version2) {
-    return OasMajorVersion.Version2;
+export function getMajorSpecVersion(version: SpecVersion): SpecMajorVersion {
+  if (version === SpecVersion.OAS2) {
+    return SpecMajorVersion.OAS2;
+  } else if (version === SpecVersion.Async2) {
+    return SpecMajorVersion.Async2;
   } else {
-    return OasMajorVersion.Version3;
+    return SpecMajorVersion.OAS3;
   }
 }
+
+export function getTypes(spec: SpecVersion) {
+  return typesMap[spec];
+}

package/src/rules/async2/__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: '2.6.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          NOT_A_KEBAB:
+            subscribe:
+              message:
+                messageId: Message1
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'channels-kebab-case': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/channels/NOT_A_KEBAB",
+              "reportOnKey": true,
+              "source": "asyncapi.yaml",
+            },
+          ],
+          "message": "\`NOT_A_KEBAB\` does not use kebab-case.",
+          "ruleId": "channels-kebab-case",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should report on snake_case in channel path', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '2.6.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          snake_kebab:
+            subscribe:
+              message:
+                messageId: Message1
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'channels-kebab-case': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/channels/snake_kebab",
+              "reportOnKey": true,
+              "source": "asyncapi.yaml",
+            },
+          ],
+          "message": "\`snake_kebab\` does not use kebab-case.",
+          "ruleId": "channels-kebab-case",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should allow trailing slash in channel path with "channels-kebab-case" rule', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '2.6.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          kebab/:
+            subscribe:
+              message:
+                messageId: Message1
+        `,
+      '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(`Array []`);
+  });
+
+  it('words with hyphens are allowed with "channels-kebab-case" rule', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        asyncapi: '2.6.0'
+        info:
+          title: Cool API
+          version: 1.0.0
+        channels:
+          kebab-with-longer-channel-path:
+            subscribe:
+              message:
+                messageId: Message1
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'paths-kebab-case': 'error',
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/async2/__tests__/no-channel-trailing-slash.test.ts

@@ -0,0 +1,97 @@
+import { outdent } from 'outdent';
+import { lintDocument } from '../../../lint';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { BaseResolver } from '../../../resolve';
+
+describe('no-channel-trailing-slash', () => {
+  it('should report on trailing slash in a channel path', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          asyncapi: '2.6.0'
+          info:
+            title: Excellent API
+            version: 1.0.0
+          channels:
+            /trailing/:
+              subscribe:
+                message:
+                  messageId: Message1
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-channel-trailing-slash': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/channels/~1trailing~1",
+              "reportOnKey": true,
+              "source": "asyncapi.yaml",
+            },
+          ],
+          "message": "\`/trailing/\` should not have a trailing slash.",
+          "ruleId": "no-channel-trailing-slash",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on if no trailing slash in path', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          asyncapi: '2.6.0'
+          info:
+            title: Excellent API
+            version: 1.0.0
+          channels:
+            /expected:
+              subscribe:
+                message:
+                  messageId: Message1
+        `,
+      'asyncapi.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-channel-trailing-slash': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on trailing slash in path if the path is root', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          asyncapi: '2.6.0'
+          info:
+            title: Excellent API
+            version: 1.0.0
+          channels:
+            /:
+              subscribe:
+                message:
+                  messageId: Message1
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-channel-trailing-slash': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+});

package/src/rules/async2/channels-kebab-case.ts

@@ -0,0 +1,18 @@
+import { Async2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const ChannelsKebabCase: Async2Rule = () => {
+  return {
+    Channel(_channel: object, { report, key }: UserContext) {
+      const segments = (key as string)
+        .split(/[/.:]/) // split on / or : as likely channel namespacers
+        .filter((s) => s !== ''); // filter out empty segments
+      if (!segments.every((segment) => /^{.+}$/.test(segment) || /^[a-z0-9-.]+$/.test(segment))) {
+        report({
+          message: `\`${key}\` does not use kebab-case.`,
+          location: { reportOnKey: true },
+        });
+      }
+    },
+  };
+};

package/src/rules/async2/index.ts

@@ -0,0 +1,22 @@
+import { Async2Rule } from '../../visitors';
+import { Assertions } from '../common/assertions';
+import { Spec } from '../common/spec';
+import { InfoContact } from '../common/info-contact';
+import { OperationOperationId } from '../common/operation-operationId';
+import { TagDescription } from '../common/tag-description';
+import { TagsAlphabetical } from '../common/tags-alphabetical';
+import { ChannelsKebabCase } from './channels-kebab-case';
+import { NoChannelTrailingSlash } from './no-channel-trailing-slash';
+
+export const rules = {
+  spec: Spec as Async2Rule,
+  assertions: Assertions,
+  'info-contact': InfoContact,
+  'operation-operationId': OperationOperationId,
+  'channels-kebab-case': ChannelsKebabCase,
+  'no-channel-trailing-slash': NoChannelTrailingSlash,
+  'tag-description': TagDescription,
+  'tags-alphabetical': TagsAlphabetical,
+};
+
+export const preprocessors = {};

package/src/rules/async2/no-channel-trailing-slash.ts

@@ -0,0 +1,15 @@
+import { Async2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const NoChannelTrailingSlash: Async2Rule = () => {
+  return {
+    Channel(_channel: any, { report, key, location }: UserContext) {
+      if ((key as string).endsWith('/') && key !== '/') {
+        report({
+          message: `\`${key}\` should not have a trailing slash.`,
+          location: location.key(),
+        });
+      }
+    },
+  };
+};

package/src/rules/common/__tests__/no-path-trailing-slash.test.ts

@@ -41,6 +41,47 @@ describe('no-path-trailing-slash', () => {
     `);
   });
 
+  it('should report on trailing slash in path on key when referencing', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/bad/':
+            $ref: '#/components/pathItems/MyItem'
+        components:
+          pathItems:
+            MyItem:
+              get:
+                summary: List all pets
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-path-trailing-slash': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/paths/~1bad~1",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "\`/bad/\` should not have a trailing slash.",
+          "ruleId": "no-path-trailing-slash",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
   it('should not report on if no trailing slash in path', async () => {
     const document = parseYamlToDocument(
       outdent`

package/src/rules/common/__tests__/tags-alphabetical.test.ts

@@ -61,4 +61,62 @@ describe('Oas3 tags-alphabetical', () => {
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
   });
+
+  it('should report on tags object if not sorted alphabetically not ignoring case', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          paths: {}
+          tags:
+            - name: a
+            - name: B
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'tags-alphabetical': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/tags/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "The \`tags\` array should be in alphabetical order.",
+          "ruleId": "tags-alphabetical",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on tags object if sorted alphabetically ignoring case', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+      openapi: 3.0.0
+      paths: {}
+      tags:
+        - name: a
+        - name: B
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'tags-alphabetical': { severity: 'error', ignoreCase: true } }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
 });

package/src/rules/common/no-path-trailing-slash.ts

@@ -3,11 +3,11 @@ import { UserContext } from '../../walk';
 
 export const NoPathTrailingSlash: Oas3Rule | Oas2Rule = () => {
   return {
-    PathItem(_path: any, { report, key, location }: UserContext) {
+    PathItem(_path: any, { report, key, rawLocation }: UserContext) {
       if ((key as string).endsWith('/') && key !== '/') {
         report({
           message: `\`${key}\` should not have a trailing slash.`,
-          location: location.key(),
+          location: rawLocation.key(),
         });
       }
     },

package/src/rules/common/scalar-property-missing-example.ts

@@ -2,7 +2,7 @@ import type { Oas2Rule, Oas3Rule } from '../../visitors';
 import type { UserContext } from '../../walk';
 import type { Oas2Schema } from '../../typings/swagger';
 import type { Oas3Schema, Oas3_1Schema } from '../../typings/openapi';
-import { OasVersion } from '../../oas-types';
+import { SpecVersion } from '../../oas-types';
 
 const SCALAR_TYPES = ['string', 'integer', 'number', 'boolean', 'null'];
 
@@ -25,7 +25,7 @@ export const ScalarPropertyMissingExample: Oas3Rule | Oas2Rule = () => {
         ) {
           report({
             message: `Scalar property should have "example"${
-              oasVersion === OasVersion.Version3_1 ? ' or "examples"' : ''
+              oasVersion === SpecVersion.OAS3_1 ? ' or "examples"' : ''
             } defined.`,
             location: location.child(propName).key(),
           });

package/src/rules/common/spec.ts

@@ -1,11 +1,11 @@
-import type { Oas3Rule, Oas2Rule } from '../../visitors';
+import type { Oas3Rule, Oas2Rule, Async2Rule } from '../../visitors';
 import { isNamedType, SpecExtension } from '../../types';
 import { oasTypeOf, matchesJsonSchemaType, getSuggest, validateSchemaEnumType } from '../utils';
 import { isRef } from '../../ref-utils';
 import { isPlainObject } from '../../utils';
 import { UserContext } from '../../walk';
 
-export const OasSpec: Oas3Rule | Oas2Rule = () => {
+export const Spec: Oas3Rule | Oas2Rule | Async2Rule = () => {
   return {
     any(
       node: any,

package/src/rules/common/tags-alphabetical.ts

@@ -1,14 +1,14 @@
 import { Oas3Rule, Oas2Rule } from '../../visitors';
-import { Oas2Definition } from '../../typings/swagger';
-import { Oas3Definition } from '../../typings/openapi';
+import { Oas2Definition, Oas2Tag } from '../../typings/swagger';
+import { Oas3Definition, Oas3Tag } from '../../typings/openapi';
 import { UserContext } from '../../walk';
 
-export const TagsAlphabetical: Oas3Rule | Oas2Rule = () => {
+export const TagsAlphabetical: Oas3Rule | Oas2Rule = ({ ignoreCase = false }) => {
   return {
     Root(root: Oas2Definition | Oas3Definition, { report, location }: UserContext) {
       if (!root.tags) return;
       for (let i = 0; i < root.tags.length - 1; i++) {
-        if (root.tags[i].name > root.tags[i + 1].name) {
+        if (getTagName(root.tags[i], ignoreCase) > getTagName(root.tags[i + 1], ignoreCase)) {
           report({
             message: 'The `tags` array should be in alphabetical order.',
             location: location.child(['tags', i]),
@@ -18,3 +18,7 @@ export const TagsAlphabetical: Oas3Rule | Oas2Rule = () => {
     },
   };
 };
+
+function getTagName(tag: Oas2Tag | Oas3Tag, ignoreCase: boolean): string {
+  return ignoreCase ? tag.name.toLowerCase() : tag.name;
+}