@redocly/openapi-core 1.31.2 → 1.32.0

package/src/config/utils.ts

@@ -62,6 +62,7 @@ function extractFlatConfig<
   async2Rules,
   async3Rules,
   arazzo1Rules,
+  overlay1Rules,
 
   preprocessors,
   oas2Preprocessors,
@@ -70,6 +71,7 @@ function extractFlatConfig<
   async2Preprocessors,
   async3Preprocessors,
   arazzo1Preprocessors,
+  overlay1Preprocessors,
 
   decorators,
   oas2Decorators,
@@ -78,6 +80,7 @@ function extractFlatConfig<
   async2Decorators,
   async3Decorators,
   arazzo1Decorators,
+  overlay1Decorators,
 
   ...rawConfigRest
 }: T): {
@@ -95,6 +98,7 @@ function extractFlatConfig<
     async2Rules,
     async3Rules,
     arazzo1Rules,
+    overlay1Rules,
 
     preprocessors,
     oas2Preprocessors,
@@ -103,6 +107,7 @@ function extractFlatConfig<
     async2Preprocessors,
     async3Preprocessors,
     arazzo1Preprocessors,
+    overlay1Preprocessors,
 
     decorators,
     oas2Decorators,
@@ -111,6 +116,7 @@ function extractFlatConfig<
     async2Decorators,
     async3Decorators,
     arazzo1Decorators,
+    overlay1Decorators,
 
     doNotResolveExamples: rawConfigRest.resolve?.doNotResolveExamples,
   };
@@ -170,6 +176,7 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     async2Rules: {},
     async3Rules: {},
     arazzo1Rules: {},
+    overlay1Rules: {},
 
     preprocessors: {},
     oas2Preprocessors: {},
@@ -178,6 +185,7 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     async2Preprocessors: {},
     async3Preprocessors: {},
     arazzo1Preprocessors: {},
+    overlay1Preprocessors: {},
 
     decorators: {},
     oas2Decorators: {},
@@ -186,6 +194,7 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     async2Decorators: {},
     async3Decorators: {},
     arazzo1Decorators: {},
+    overlay1Decorators: {},
 
     plugins: [],
     pluginPaths: [],
@@ -212,6 +221,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignOnlyExistingConfig(result.async3Rules, rulesConf.rules);
     assignConfig(result.arazzo1Rules, rulesConf.arazzo1Rules);
     assignOnlyExistingConfig(result.arazzo1Rules, rulesConf.rules);
+    assignConfig(result.overlay1Rules, rulesConf.overlay1Rules);
+    assignOnlyExistingConfig(result.overlay1Rules, rulesConf.rules);
 
     assignConfig(result.preprocessors, rulesConf.preprocessors);
     assignConfig(result.oas2Preprocessors, rulesConf.oas2Preprocessors);
@@ -226,6 +237,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignOnlyExistingConfig(result.async3Preprocessors, rulesConf.preprocessors);
     assignConfig(result.arazzo1Preprocessors, rulesConf.arazzo1Preprocessors);
     assignOnlyExistingConfig(result.arazzo1Preprocessors, rulesConf.preprocessors);
+    assignConfig(result.overlay1Preprocessors, rulesConf.overlay1Preprocessors);
+    assignOnlyExistingConfig(result.overlay1Preprocessors, rulesConf.preprocessors);
 
     assignConfig(result.decorators, rulesConf.decorators);
     assignConfig(result.oas2Decorators, rulesConf.oas2Decorators);
@@ -240,6 +253,8 @@ export function mergeExtends(rulesConfList: ResolvedStyleguideConfig[]) {
     assignOnlyExistingConfig(result.async3Decorators, rulesConf.decorators);
     assignConfig(result.arazzo1Decorators, rulesConf.arazzo1Decorators);
     assignOnlyExistingConfig(result.arazzo1Decorators, rulesConf.decorators);
+    assignConfig(result.overlay1Decorators, rulesConf.overlay1Decorators);
+    assignOnlyExistingConfig(result.overlay1Decorators, rulesConf.decorators);
 
     result.plugins!.push(...(rulesConf.plugins || []));
     result.pluginPaths!.push(...(rulesConf.pluginPaths || []));

package/src/decorators/overlay1/index.ts

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

package/src/lint.ts

@@ -21,6 +21,7 @@ import type {
   NestedVisitObject,
   Oas2Visitor,
   Oas3Visitor,
+  Overlay1Visitor,
   RuleInstanceConfig,
 } from './visitors';
 import type { CollectFn } from './utils';
@@ -154,6 +155,8 @@ export async function lintConfig(opts: {
       | Async3Visitor[]
       | Arazzo1Visitor
       | Arazzo1Visitor[]
+      | Overlay1Visitor
+      | Overlay1Visitor[]
     >;
   })[] = [
     {

package/src/oas-types.ts

@@ -4,6 +4,7 @@ import { Oas3_1Types } from './types/oas3_1';
 import { AsyncApi2Types } from './types/asyncapi2';
 import { AsyncApi3Types } from './types/asyncapi3';
 import { Arazzo1Types } from './types/arazzo';
+import { Overlay1Types } from './types/overlay';
 import { isPlainObject } from './utils';
 import { VERSION_PATTERN } from './typings/arazzo';
 
@@ -13,6 +14,7 @@ import type {
   BuiltInArazzo1RuleId,
   BuiltInOAS2RuleId,
   BuiltInOAS3RuleId,
+  BuiltInOverlay1RuleId,
 } from './types/redocly-yaml';
 import type {
   Oas3Rule,
@@ -25,6 +27,8 @@ import type {
   Async3Rule,
   Arazzo1Preprocessor,
   Arazzo1Rule,
+  Overlay1Preprocessor,
+  Overlay1Rule,
 } from './visitors';
 
 export enum SpecVersion {
@@ -34,6 +38,7 @@ export enum SpecVersion {
   Async2 = 'async2',
   Async3 = 'async3',
   Arazzo1 = 'arazzo1',
+  Overlay1 = 'overlay1',
 }
 
 export enum SpecMajorVersion {
@@ -42,6 +47,7 @@ export enum SpecMajorVersion {
   Async2 = 'async2',
   Async3 = 'async3',
   Arazzo1 = 'arazzo1',
+  Overlay1 = 'overlay1',
 }
 
 const typesMap = {
@@ -51,6 +57,7 @@ const typesMap = {
   [SpecVersion.Async2]: AsyncApi2Types,
   [SpecVersion.Async3]: AsyncApi3Types,
   [SpecVersion.Arazzo1]: Arazzo1Types,
+  [SpecVersion.Overlay1]: Overlay1Types,
 };
 
 export type RuleMap<Key extends string, RuleConfig, T> = Record<
@@ -83,17 +90,24 @@ export type Arazzo1RuleSet<T = undefined> = RuleMap<
   T
 >;
 
+export type Overlay1RuleSet<T = undefined> = RuleMap<
+  BuiltInOverlay1RuleId | 'struct' | 'assertions',
+  Overlay1Rule,
+  T
+>;
 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 Arazzo1PreprocessorsSet = Record<string, Arazzo1Preprocessor>;
+export type Overlay1PreprocessorsSet = Record<string, Overlay1Preprocessor>;
 
 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 Arazzo1DecoratorsSet = Record<string, Arazzo1Preprocessor>;
+export type Overlay1DecoratorsSet = Record<string, Overlay1Preprocessor>;
 
 export function detectSpec(root: unknown): SpecVersion {
   if (!isPlainObject(root)) {
@@ -136,6 +150,10 @@ export function detectSpec(root: unknown): SpecVersion {
     return SpecVersion.Arazzo1;
   }
 
+  if (typeof root.overlay === 'string' && VERSION_PATTERN.test(root.overlay)) {
+    return SpecVersion.Overlay1;
+  }
+
   throw new Error(`Unsupported specification`);
 }
 
@@ -148,6 +166,8 @@ export function getMajorSpecVersion(version: SpecVersion): SpecMajorVersion {
     return SpecMajorVersion.Async3;
   } else if (version === SpecVersion.Arazzo1) {
     return SpecMajorVersion.Arazzo1;
+  } else if (version === SpecVersion.Overlay1) {
+    return SpecMajorVersion.Overlay1;
   } else {
     return SpecMajorVersion.OAS3;
   }

package/src/rules/arazzo/__tests__/respect-supported-versions.test.ts

@@ -81,7 +81,7 @@ describe('Arazzo respect-supported-versions', () => {
               "source": "arazzo.yaml",
             },
           ],
-          "message": "Only 1.0.1 Arazzo version is supported by Respect.",
+          "message": "Only 1.0.1 Arazzo version is fully supported by Respect.",
           "ruleId": "respect-supported-versions",
           "severity": "error",
           "suggest": [],

package/src/rules/common/assertions/index.ts

@@ -8,6 +8,7 @@ import type {
   Async3Visitor,
   Oas2Visitor,
   Oas3Visitor,
+  Overlay1Visitor,
 } from '../../../visitors';
 import type { RuleSeverity } from '../../../config';
 
@@ -35,8 +36,14 @@ export type RawAssertion = AssertionDefinition & {
 export type Assertion = RawAssertion & { assertionId: string };
 
 export const Assertions = (opts: Record<string, Assertion>) => {
-  const visitors: (Oas2Visitor | Oas3Visitor | Async2Visitor | Async3Visitor | Arazzo1Visitor)[] =
-    [];
+  const visitors: (
+    | Oas2Visitor
+    | Oas3Visitor
+    | Async2Visitor
+    | Async3Visitor
+    | Arazzo1Visitor
+    | Overlay1Visitor
+  )[] = [];
 
   // As 'Assertions' has an array of asserts,
   // that array spreads into an 'opts' object on init rules phase here

package/src/rules/common/struct.ts

@@ -4,9 +4,22 @@ import { isRef } from '../../ref-utils';
 import { isPlainObject } from '../../utils';
 
 import type { UserContext } from '../../walk';
-import type { Oas3Rule, Oas2Rule, Async2Rule, Async3Rule, Arazzo1Rule } from '../../visitors';
-
-export const Struct: Oas3Rule | Oas2Rule | Async2Rule | Async3Rule | Arazzo1Rule = () => {
+import type {
+  Oas3Rule,
+  Oas2Rule,
+  Async2Rule,
+  Async3Rule,
+  Arazzo1Rule,
+  Overlay1Rule,
+} from '../../visitors';
+
+export const Struct:
+  | Oas3Rule
+  | Oas2Rule
+  | Async2Rule
+  | Async3Rule
+  | Arazzo1Rule
+  | Overlay1Rule = () => {
   return {
     any(
       node: any,

package/src/rules/overlay1/__tests__/info-contact.test.ts

@@ -0,0 +1,112 @@
+import { outdent } from 'outdent';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { lintDocument } from '../../../lint';
+import { BaseResolver } from '../../../resolve';
+
+describe('Overlay 1.0 Description', () => {
+  it('should not report if the Contact Object is valid', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        overlay: 1.0.0
+        info:
+          title: Example Overlay 1 definition. Valid.
+          version: '1.0'
+          contact:
+            name: API Support
+            url: http://www.example.com/support
+            email: support@example.com
+        extends: 'openapi.yaml'
+        actions: []
+            `,
+      'overlay.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        rules: {
+          'info-contact': { severity: 'error' },
+        },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should report if the Contact Object is not defined', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        overlay: 1.0.0
+        info:
+          title: Example Overlay 1 definition. Invalid.
+          version: '1.0'
+        extends: 'openapi.yaml'
+        actions: []
+            `,
+      'overlay.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        rules: {
+          'info-contact': { severity: 'error' },
+        },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/info/contact",
+              "reportOnKey": true,
+              "source": "overlay.yaml",
+            },
+          ],
+          "message": "Info object should contain \`contact\` field.",
+          "ruleId": "info-contact",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+  it('should report if the Overlay Document is invalid', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        overlay: 1.0.0
+        info:
+          title: Example Overlay 1 definition. Invalid.
+          version: '1.0'
+            `,
+      'overlay.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        rules: {
+          struct: { severity: 'error' },
+        },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "from": undefined,
+          "location": [
+            {
+              "pointer": "#/",
+              "reportOnKey": true,
+              "source": "overlay.yaml",
+            },
+          ],
+          "message": "The field \`actions\` must be present on this level.",
+          "ruleId": "struct",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+});

package/src/rules/overlay1/index.ts

@@ -0,0 +1,14 @@
+import { Assertions } from '../common/assertions';
+import { InfoContact } from '../common/info-contact';
+import { Struct } from '../common/struct';
+
+import type { Overlay1RuleSet } from '../../oas-types';
+import type { Overlay1Rule } from '../../visitors';
+
+export const rules: Overlay1RuleSet<'built-in'> = {
+  'info-contact': InfoContact as Overlay1Rule,
+  struct: Struct as Overlay1Rule,
+  assertions: Assertions as Overlay1Rule,
+};
+
+export const preprocessors = {};

package/src/rules/respect/respect-supported-versions.ts

@@ -14,7 +14,7 @@ export const RespectSupportedVersions: Arazzo1Rule = () => {
             message: `Only ${supportedVersions} Arazzo ${pluralize(
               'version is',
               ARAZZO_VERSIONS_SUPPORTED_BY_RESPECT.length
-            )} supported by Respect.`,
+            )} fully supported by Respect.`,
             location: location.child('arazzo'),
           });
         }

package/src/types/oas3.ts

@@ -332,7 +332,7 @@ const Schema: NodeType = {
     required: { type: 'array', items: { type: 'string' } },
     enum: { type: 'array' },
     type: {
-      enum: ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'],
+      enum: ['object', 'array', 'string', 'number', 'integer', 'boolean'],
     },
     allOf: listOf('Schema'),
     anyOf: listOf('Schema'),

package/src/types/redocly-yaml.ts

@@ -160,12 +160,17 @@ const builtInArazzo1Rules = [
 
 export type BuiltInArazzo1RuleId = typeof builtInArazzo1Rules[number];
 
+const builtInOverlay1Rules = ['info-contact'] as const;
+
+export type BuiltInOverlay1RuleId = typeof builtInOverlay1Rules[number];
+
 const builtInRules = [
   ...builtInOAS2Rules,
   ...builtInOAS3Rules,
   ...builtInAsync2Rules,
   ...builtInAsync3Rules,
   ...builtInArazzo1Rules,
+  ...builtInOverlay1Rules,
   'spec', // TODO: depricated in favor of struct
   'struct',
 ] as const;

package/src/visitors.ts

@@ -70,6 +70,7 @@ import type {
   Step,
   Workflow,
 } from './typings/arazzo';
+import type { Overlay1Definition } from './typings/overlay';
 
 export type SkipFunctionContext = Pick<
   UserContext,
@@ -259,6 +260,10 @@ type ArazzoFlatVisitor = {
   Workflows?: VisitFunctionOrObject<Workflow[]>;
 };
 
+type Overlay1FlatVisitor = {
+  Root?: VisitFunctionOrObject<Overlay1Definition>;
+};
+
 const legacyTypesMap = {
   Root: 'DefinitionRoot',
   ServerVariablesMap: 'ServerVariableMap',
@@ -308,6 +313,13 @@ type ArazzoNestedVisitor = {
     : ArazzoFlatVisitor[T] & NestedVisitor<ArazzoNestedVisitor>;
 };
 
+type Overlay1NestedVisitor = {
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  [T in keyof Overlay1FlatVisitor]: Overlay1FlatVisitor[T] extends Function
+    ? Overlay1FlatVisitor[T]
+    : Overlay1FlatVisitor[T] & NestedVisitor<Overlay1NestedVisitor>;
+};
+
 export type Oas3Visitor = BaseVisitor &
   Oas3NestedVisitor &
   Record<string, VisitFunction<any> | NestedVisitObject<any, Oas3NestedVisitor>>;
@@ -328,6 +340,10 @@ export type Arazzo1Visitor = BaseVisitor &
   ArazzoNestedVisitor &
   Record<string, VisitFunction<any> | NestedVisitObject<any, ArazzoNestedVisitor>>;
 
+export type Overlay1Visitor = BaseVisitor &
+  Overlay1NestedVisitor &
+  Record<string, VisitFunction<any> | NestedVisitObject<any, Overlay1NestedVisitor>>;
+
 export type NestedVisitor<T> = Exclude<T, 'any' | 'ref' | 'Root'>;
 
 export type NormalizedOasVisitors<T extends BaseVisitor> = {
@@ -352,16 +368,19 @@ export type Oas2Rule = (options: Record<string, any>) => Oas2Visitor | Oas2Visit
 export type Async2Rule = (options: Record<string, any>) => Async2Visitor | Async2Visitor[];
 export type Async3Rule = (options: Record<string, any>) => Async3Visitor | Async3Visitor[];
 export type Arazzo1Rule = (options: Record<string, any>) => Arazzo1Visitor | Arazzo1Visitor[];
+export type Overlay1Rule = (options: Record<string, any>) => Overlay1Visitor | Overlay1Visitor[];
 export type Oas3Preprocessor = (options: Record<string, any>) => Oas3Visitor;
 export type Oas2Preprocessor = (options: Record<string, any>) => Oas2Visitor;
 export type Async2Preprocessor = (options: Record<string, any>) => Async2Visitor;
 export type Async3Preprocessor = (options: Record<string, any>) => Async3Visitor;
 export type Arazzo1Preprocessor = (options: Record<string, any>) => Arazzo1Visitor;
+export type Overlay1Preprocessor = (options: Record<string, any>) => Overlay1Visitor;
 export type Oas3Decorator = (options: Record<string, any>) => Oas3Visitor;
 export type Oas2Decorator = (options: Record<string, any>) => Oas2Visitor;
 export type Async2Decorator = (options: Record<string, any>) => Async2Visitor;
 export type Async3Decorator = (options: Record<string, any>) => Async3Visitor;
 export type Arazzo1Decorator = (options: Record<string, any>) => Arazzo1Visitor;
+export type Overlay1Decorator = (options: Record<string, any>) => Overlay1Visitor;
 
 // alias for the latest version supported
 // every time we update it - consider semver