@redocly/openapi-core 1.1.0 → 1.2.1

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/assertions/asserts.ts

@@ -66,7 +66,11 @@ export const runOnValuesSet = new Set<keyof Asserts>([
 ]);
 
 export const asserts: Asserts = {
-  pattern: (value: string | string[], condition: string, { baseLocation }: AssertionFnContext) => {
+  pattern: (
+    value: string | string[],
+    condition: string,
+    { baseLocation, rawValue }: AssertionFnContext
+  ) => {
     if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
     const values = Array.isArray(value) ? value : [value];
     const regex = regexFromString(condition);
@@ -76,7 +80,11 @@ export const asserts: Asserts = {
         (_val) =>
           !regex?.test(_val) && {
             message: `"${_val}" should match a regex ${condition}`,
-            location: runOnValue(value) ? baseLocation : baseLocation.key(),
+            location: runOnValue(value)
+              ? baseLocation
+              : isPlainObject(rawValue)
+              ? baseLocation.child(_val).key()
+              : baseLocation.key(),
           }
       )
       .filter(isTruthy);
@@ -84,7 +92,7 @@ export const asserts: Asserts = {
   notPattern: (
     value: string | string[],
     condition: string,
-    { baseLocation }: AssertionFnContext
+    { baseLocation, rawValue }: AssertionFnContext
   ) => {
     if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
     const values = Array.isArray(value) ? value : [value];
@@ -95,7 +103,11 @@ export const asserts: Asserts = {
         (_val) =>
           regex?.test(_val) && {
             message: `"${_val}" should not match a regex ${condition}`,
-            location: runOnValue(value) ? baseLocation : baseLocation.key(),
+            location: runOnValue(value)
+              ? baseLocation
+              : isPlainObject(rawValue)
+              ? baseLocation.child(_val).key()
+              : baseLocation.key(),
           }
       )
       .filter(isTruthy);

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/oas2/index.ts

@@ -1,5 +1,5 @@
 import { Oas2Rule } from '../../visitors';
-import { OasSpec } from '../common/spec';
+import { Spec } from '../common/spec';
 import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
 import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
 import { InfoContact } from '../common/info-contact';
@@ -43,7 +43,7 @@ import { RequiredStringPropertyMissingMinLength } from '../common/required-strin
 import { SpecStrictRefs } from '../common/spec-strict-refs';
 
 export const rules = {
-  spec: OasSpec as Oas2Rule,
+  spec: Spec as Oas2Rule,
   'no-invalid-schema-examples': NoInvalidSchemaExamples,
   'no-invalid-parameter-examples': NoInvalidParameterExamples,
   'info-contact': InfoContact as Oas2Rule,

package/src/rules/oas3/__tests__/no-server-example.com.test.ts

@@ -30,7 +30,7 @@ describe('Oas3 oas3-no-server-example.com', () => {
               "source": "foobar.yaml",
             },
           ],
-          "message": "Server \`url\` should not point at example.com.",
+          "message": "Server \`url\` should not point to example.com or localhost.",
           "ruleId": "no-server-example.com",
           "severity": "error",
           "suggest": Array [],
@@ -57,4 +57,39 @@ describe('Oas3 oas3-no-server-example.com', () => {
 
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
   });
+
+  it('oas3-no-server-example.com: should report on server object with "foo.example.com" url', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          servers:
+            - url: foo.example.com
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-server-example.com': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/servers/0/url",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Server \`url\` should not point to example.com or localhost.",
+          "ruleId": "no-server-example.com",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
 });

package/src/rules/oas3/__tests__/spec/spec.test.ts

@@ -17,7 +17,7 @@ describe('Oas3 Structural visitor basic', () => {
             - 25.3
             - test
           servers:
-          - url: 'http://example.com'
+          - url: 'http://redocly-example.com'
             variables:
               a:
                 default: test

package/src/rules/oas3/index.ts

@@ -1,5 +1,5 @@
 import { Oas3RuleSet } from '../../oas-types';
-import { OasSpec } from '../common/spec';
+import { Spec } from '../common/spec';
 import { Operation2xxResponse } from '../common/operation-2xx-response';
 import { Operation4xxResponse } from '../common/operation-4xx-response';
 import { Assertions } from '../common/assertions';
@@ -54,7 +54,7 @@ import { SpecStrictRefs } from '../common/spec-strict-refs';
 import { ComponentNameUnique } from './component-name-unique';
 
 export const rules = {
-  spec: OasSpec,
+  spec: Spec,
   'info-contact': InfoContact,
   'info-license': InfoLicense,
   'info-license-url': InfoLicenseUrl,

package/src/rules/oas3/no-server-example.com.ts

@@ -3,9 +3,10 @@ import { Oas3Rule } from '../../visitors';
 export const NoServerExample: Oas3Rule = () => {
   return {
     Server(server, { report, location }) {
-      if (['example.com', 'localhost'].indexOf(server.url) !== -1) {
+      const pattern = /^(.*[\/.])?(example\.com|localhost)([\/:?].*|$)/;
+      if (server.url && pattern.test(server.url)) {
         report({
-          message: 'Server `url` should not point at example.com.',
+          message: 'Server `url` should not point to example.com or localhost.',
           location: location.child(['url']),
         });
       }