@redocly/openapi-core 1.31.3 → 1.32.0

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/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/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