@redocly/openapi-core 1.2.0 → 1.3.0

package/src/__tests__/bundle.test.ts

@@ -1,11 +1,32 @@
 import outdent from 'outdent';
 import * as path from 'path';
 
-import { bundleDocument, bundle } from '../bundle';
+import { bundleDocument, bundle, bundleFromString } from '../bundle';
 import { parseYamlToDocument, yamlSerializer, makeConfig } from '../../__tests__/utils';
-import { StyleguideConfig, Config, ResolvedConfig } from '../config';
+import { StyleguideConfig, Config, ResolvedConfig, createConfig, loadConfig } from '../config';
 import { BaseResolver } from '../resolve';
 
+const stringDocument = outdent`
+  openapi: 3.0.0
+  paths:
+    /pet:
+      get:
+        operationId: get
+        parameters:
+          - $ref: '#/components/parameters/shared_a'
+          - name: get_b
+      post:
+        operationId: post
+        parameters:
+          - $ref: '#/components/parameters/shared_a'
+  components:
+    parameters:
+      shared_a:
+        name: shared-a
+`;
+
+const testDocument = parseYamlToDocument(stringDocument, '');
+
 describe('bundle', () => {
   const fetchMock = jest.fn(() =>
     Promise.resolve({
@@ -19,28 +40,6 @@ describe('bundle', () => {
 
   expect.addSnapshotSerializer(yamlSerializer);
 
-  const testDocument = parseYamlToDocument(
-    outdent`
-      openapi: 3.0.0
-      paths:
-        /pet:
-          get:
-            operationId: get
-            parameters:
-              - $ref: '#/components/parameters/shared_a'
-              - name: get_b
-          post:
-            operationId: post
-            parameters:
-              - $ref: '#/components/parameters/shared_a'
-      components:
-        parameters:
-          shared_a:
-            name: shared-a
-    `,
-    ''
-  );
-
   it('change nothing with only internal refs', async () => {
     const { bundle, problems } = await bundleDocument({
       document: testDocument,
@@ -97,7 +96,7 @@ describe('bundle', () => {
     expect(res.parsed).toMatchSnapshot();
   });
 
-  it('should not place referened schema inline when component in question is not of type "schemas"', async () => {
+  it('should not place referenced schema inline when component in question is not of type "schemas"', async () => {
     const { bundle: res, problems } = await bundle({
       config: new Config({} as ResolvedConfig),
       ref: path.join(__dirname, 'fixtures/refs/external-request-body.yaml'),
@@ -233,4 +232,45 @@ describe('bundle', () => {
 
     `);
   });
+
+  it('should throw an error when there is no document to bundle', () => {
+    const wrapper = () =>
+      bundle({
+        config: new Config({} as ResolvedConfig),
+      });
+
+    expect(wrapper()).rejects.toThrowError('Document or reference is required.\n');
+  });
+
+  it('should bundle with a doc provided', async () => {
+    const {
+      bundle: { parsed },
+      problems,
+    } = await bundle({
+      config: await loadConfig({ configPath: path.join(__dirname, 'fixtures/redocly.yaml') }),
+      doc: testDocument,
+    });
+
+    const origCopy = JSON.parse(JSON.stringify(testDocument.parsed));
+
+    expect(problems).toHaveLength(0);
+    expect(parsed).toEqual(origCopy);
+  });
+});
+
+describe('bundleFromString', () => {
+  it('should bundle from string using bundleFromString', async () => {
+    const {
+      bundle: { parsed, ...rest },
+      problems,
+    } = await bundleFromString({
+      config: await createConfig(`
+        extends:
+        - recommended
+      `),
+      source: testDocument.source.body,
+    });
+    expect(problems).toHaveLength(0);
+    expect(rest.source.body).toEqual(stringDocument);
+  });
 });

package/src/__tests__/fixtures/lint/openapi.yaml

@@ -0,0 +1,10 @@
+openapi: 3.0.0
+info:
+  title: Test API
+  version: '1.0'
+  description: Test
+  license: Fail
+
+servers:
+  - url: http://redocly-example.com
+paths: {}

package/src/__tests__/fixtures/redocly.yaml

@@ -0,0 +1,2 @@
+extends:
+  - recommended

package/src/__tests__/lint.test.ts

@@ -1,7 +1,7 @@
 import * as path from 'path';
 import { outdent } from 'outdent';
 
-import { lintFromString, lintConfig, lintDocument } from '../lint';
+import { lintFromString, lintConfig, lintDocument, lint } from '../lint';
 import { BaseResolver } from '../resolve';
 import { loadConfig } from '../config/load';
 import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../__tests__/utils';
@@ -20,7 +20,7 @@ describe('lint', () => {
           license: Fail
 
         servers:
-          - url: http://example.com
+          - url: http://redocly-example.com
         paths: {}
     `,
       config: await loadConfig(),
@@ -46,6 +46,35 @@ describe('lint', () => {
     `);
   });
 
+  it('lint should work', async () => {
+    const results = await lint({
+      ref: path.join(__dirname, 'fixtures/lint/openapi.yaml'),
+      config: await loadConfig({
+        configPath: path.join(__dirname, 'fixtures/redocly.yaml'),
+      }),
+    });
+
+    expect(replaceSourceWithRef(results, path.join(__dirname, 'fixtures/lint/')))
+      .toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "from": undefined,
+          "location": Array [
+            Object {
+              "pointer": "#/info/license",
+              "reportOnKey": false,
+              "source": "openapi.yaml",
+            },
+          ],
+          "message": "Expected type \`License\` (object) but got \`string\`",
+          "ruleId": "spec",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
   it('lintConfig should work', async () => {
     const document = parseYamlToDocument(
       outdent`

package/src/bundle.ts

@@ -1,5 +1,12 @@
 import isEqual = require('lodash.isequal');
-import { BaseResolver, resolveDocument, Document, ResolvedRefMap, makeRefId } from './resolve';
+import {
+  BaseResolver,
+  resolveDocument,
+  Document,
+  ResolvedRefMap,
+  makeRefId,
+  makeDocumentFromString,
+} from './resolve';
 import { Oas3Rule, normalizeVisitors, Oas3Visitor, Oas2Visitor } from './visitors';
 import { NormalizedNodeType, normalizeTypes, NodeType } from './types';
 import { WalkContext, walkDocument, UserContext, ResolveResult, NormalizedProblem } from './walk';
@@ -22,10 +29,7 @@ export enum OasVersion {
   Version3_0 = 'oas3_0',
   Version3_1 = 'oas3_1',
 }
-
-export async function bundle(opts: {
-  ref?: string;
-  doc?: Document;
+export type BundleOptions = {
   externalRefResolver?: BaseResolver;
   config: Config;
   dereference?: boolean;
@@ -33,7 +37,14 @@ export async function bundle(opts: {
   skipRedoclyRegistryRefs?: boolean;
   removeUnusedComponents?: boolean;
   keepUrlRefs?: boolean;
-}) {
+};
+
+export async function bundle(
+  opts: {
+    ref?: string;
+    doc?: Document;
+  } & BundleOptions
+) {
   const {
     ref,
     doc,
@@ -45,7 +56,7 @@ export async function bundle(opts: {
   }
 
   const document =
-    doc !== undefined ? doc : await externalRefResolver.resolveDocument(base, ref!, true);
+    doc === undefined ? await externalRefResolver.resolveDocument(base, ref!, true) : doc;
 
   if (document instanceof Error) {
     throw document;
@@ -59,6 +70,23 @@ export async function bundle(opts: {
   });
 }
 
+export async function bundleFromString(
+  opts: {
+    source: string;
+    absoluteRef?: string;
+  } & BundleOptions
+) {
+  const { source, absoluteRef, externalRefResolver = new BaseResolver(opts.config.resolve) } = opts;
+  const document = makeDocumentFromString(source, absoluteRef || '/');
+
+  return bundleDocument({
+    document,
+    ...opts,
+    externalRefResolver,
+    config: opts.config.styleguide,
+  });
+}
+
 type BundleContext = WalkContext;
 
 export type BundleResult = {

package/src/config/__tests__/load.test.ts

@@ -73,8 +73,8 @@ describe('findConfig', () => {
       .spyOn(fs, 'existsSync')
       .mockImplementation((name) => name === 'redocly.yaml' || name === '.redocly.yaml');
     expect(findConfig).toThrow(`
-      Multiple configuration files are not allowed. 
-      Found the following files: redocly.yaml, .redocly.yaml. 
+      Multiple configuration files are not allowed.
+      Found the following files: redocly.yaml, .redocly.yaml.
       Please use 'redocly.yaml' instead.
     `);
   });
@@ -124,6 +124,39 @@ describe('createConfig', () => {
       overridesRules: rawConfig.rules as Record<string, RuleConfig>,
     });
   });
+
+  it('should create config from object with a custom plugin', async () => {
+    const testCustomRule = jest.fn();
+    const rawConfig: FlatRawConfig = {
+      extends: [],
+      plugins: [
+        {
+          id: 'my-plugin',
+          rules: {
+            oas3: {
+              'test-rule': testCustomRule,
+            },
+          },
+        },
+      ],
+      rules: {
+        'my-plugin/test-rule': 'error',
+      },
+    };
+    const config = await createConfig(rawConfig);
+
+    expect(config.styleguide.plugins[0]).toEqual({
+      id: 'my-plugin',
+      rules: {
+        oas3: {
+          'my-plugin/test-rule': testCustomRule,
+        },
+      },
+    });
+    expect(config.styleguide.rules.oas3_0).toEqual({
+      'my-plugin/test-rule': 'error',
+    });
+  });
 });
 
 function verifyExtendedConfig(

package/src/config/load.ts

@@ -4,10 +4,16 @@ 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 { DeprecatedInRawConfig, FlatRawConfig, RawConfig, Region } from './types';
+import type {
+  DeprecatedInRawConfig,
+  FlatRawConfig,
+  RawConfig,
+  RawUniversalConfig,
+  Region,
+} from './types';
 import { RegionalTokenWithValidity } from '../redocly/redocly-client-types';
 
 async function addConfigMetadata({
@@ -101,8 +107,8 @@ export function findConfig(dir?: string): string | undefined {
   ).filter(fs.existsSync);
   if (existingConfigFiles.length > 1) {
     throw new Error(`
-      Multiple configuration files are not allowed. 
-      Found the following files: ${existingConfigFiles.join(', ')}. 
+      Multiple configuration files are not allowed.
+      Found the following files: ${existingConfigFiles.join(', ')}.
       Please use 'redocly.yaml' instead.
     `);
   }
@@ -122,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}`);
   }
 }
@@ -129,10 +138,11 @@ export async function getConfig(
 type CreateConfigOptions = {
   extends?: string[];
   tokens?: RegionalTokenWithValidity[];
+  configPath?: string;
 };
 
 export async function createConfig(
-  config: string | RawConfig,
+  config: string | RawUniversalConfig,
   options?: CreateConfigOptions
 ): Promise<Config> {
   return addConfigMetadata({

package/src/config/types.ts

@@ -185,6 +185,9 @@ export type RawConfig = {
   telemetry?: Telemetry;
 } & ThemeConfig;
 
+// RawConfig is legacy, use RawUniversalConfig in public APIs
+export type RawUniversalConfig = Omit<RawConfig, 'styleguide'> & StyleguideRawConfig;
+
 export type FlatApi = Omit<Api, 'styleguide'> &
   Omit<ApiStyleguideRawConfig, 'doNotResolveExamples'>;
 

package/src/config/utils.ts

@@ -347,3 +347,5 @@ export function getUniquePlugins(plugins: Plugin[]): Plugin[] {
   }
   return results;
 }
+
+export class ConfigValidationError extends Error {}

package/src/index.ts

@@ -2,6 +2,7 @@ export { BundleOutputFormat, readFileFromUrl, slash, doesYamlFileExist, isTruthy
 export { Oas3_1Types } from './types/oas3_1';
 export { Oas3Types } from './types/oas3';
 export { Oas2Types } from './types/oas2';
+export { AsyncApi2Types } from './types/asyncapi';
 export { ConfigTypes } from './types/redocly-yaml';
 export type {
   Oas3Definition,
@@ -26,6 +27,7 @@ export {
   Config,
   StyleguideConfig,
   RawConfig,
+  RawUniversalConfig,
   IGNORE_FILE,
   Region,
   getMergedConfig,
@@ -74,4 +76,4 @@ export {
 export { getAstNodeByPointer, getLineColLocation } from './format/codeframes';
 export { formatProblems, OutputFormat, getTotals, Totals } from './format/format';
 export { lint, lint as validate, lintDocument, lintFromString, lintConfig } from './lint';
-export { bundle, bundleDocument, mapTypeToComponent } from './bundle';
+export { bundle, bundleDocument, mapTypeToComponent, bundleFromString } from './bundle';

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/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/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']),
         });
       }

package/src/types/asyncapi.ts

@@ -390,7 +390,13 @@ const Schema: NodeType = {
     maxContains: { type: 'integer', minimum: 0 },
     patternProperties: { type: 'object' },
     propertyNames: 'Schema',
-    unevaluatedItems: 'Schema',
+    unevaluatedItems: (value: unknown) => {
+      if (typeof value === 'boolean') {
+        return { type: 'boolean' };
+      } else {
+        return 'Schema';
+      }
+    },
     unevaluatedProperties: (value: unknown) => {
       if (typeof value === 'boolean') {
         return { type: 'boolean' };

package/src/types/oas3_1.ts

@@ -137,7 +137,13 @@ const Schema: NodeType = {
     maxContains: { type: 'integer', minimum: 0 },
     patternProperties: { type: 'object' },
     propertyNames: 'Schema',
-    unevaluatedItems: 'Schema',
+    unevaluatedItems: (value: unknown) => {
+      if (typeof value === 'boolean') {
+        return { type: 'boolean' };
+      } else {
+        return 'Schema';
+      }
+    },
     unevaluatedProperties: (value: unknown) => {
       if (typeof value === 'boolean') {
         return { type: 'boolean' };