@redocly/openapi-core 1.0.0-beta.106 → 1.0.0-beta.109

package/src/types/oas3.ts

@@ -2,7 +2,7 @@ import { NodeType, listOf, mapOf } from '.';
 import { isMappingRef } from '../ref-utils';
 const responseCodeRegexp = /^[0-9][0-9Xx]{2}$/;
 
-const DefinitionRoot: NodeType = {
+const Root: NodeType = {
   properties: {
     openapi: null,
     info: 'Info',
@@ -10,7 +10,7 @@ const DefinitionRoot: NodeType = {
     security: listOf('SecurityRequirement'),
     tags: listOf('Tag'),
     externalDocs: 'ExternalDocs',
-    paths: 'PathMap',
+    paths: 'PathsMap',
     components: 'Components',
     'x-webhooks': 'WebhooksMap',
   },
@@ -38,7 +38,7 @@ const Server: NodeType = {
   properties: {
     url: { type: 'string' },
     description: { type: 'string' },
-    variables: mapOf('ServerVariable'),
+    variables: 'ServerVariablesMap',
   },
   required: ['url'],
 };
@@ -88,7 +88,7 @@ const License: NodeType = {
   required: ['name'],
 };
 
-const PathMap: NodeType = {
+const PathsMap: NodeType = {
   properties: {},
   additionalProperties: (_value: any, key: string) =>
     key.startsWith('/') ? 'PathItem' : undefined,
@@ -132,8 +132,8 @@ const Parameter: NodeType = {
     allowReserved: { type: 'boolean' },
     schema: 'Schema',
     example: { isExample: true },
-    examples: mapOf('Example'),
-    content: 'MediaTypeMap',
+    examples: 'ExamplesMap',
+    content: 'MediaTypesMap',
   },
   required: ['name', 'in'],
   requiredOneOf: ['schema', 'content'],
@@ -155,7 +155,7 @@ const Operation: NodeType = {
     requestBody: 'RequestBody',
     responses: 'ResponsesMap',
     deprecated: { type: 'boolean' },
-    callbacks: mapOf('Callback'),
+    callbacks: 'CallbacksMap',
     'x-codeSamples': listOf('XCodeSample'),
     'x-code-samples': listOf('XCodeSample'), // deprecated
     'x-hideTryItPanel': { type: 'boolean' },
@@ -175,12 +175,12 @@ const RequestBody: NodeType = {
   properties: {
     description: { type: 'string' },
     required: { type: 'boolean' },
-    content: 'MediaTypeMap',
+    content: 'MediaTypesMap',
   },
   required: ['content'],
 };
 
-const MediaTypeMap: NodeType = {
+const MediaTypesMap: NodeType = {
   properties: {},
   additionalProperties: 'MediaType',
 };
@@ -189,8 +189,8 @@ const MediaType: NodeType = {
   properties: {
     schema: 'Schema',
     example: { isExample: true },
-    examples: mapOf('Example'),
-    encoding: mapOf('Encoding'),
+    examples: 'ExamplesMap',
+    encoding: 'EncodingsMap',
   },
 };
 
@@ -206,7 +206,7 @@ const Example: NodeType = {
 const Encoding: NodeType = {
   properties: {
     contentType: { type: 'string' },
-    headers: mapOf('Header'),
+    headers: 'HeadersMap',
     style: {
       enum: ['form', 'simple', 'label', 'matrix', 'spaceDelimited', 'pipeDelimited', 'deepObject'],
     },
@@ -228,9 +228,10 @@ const Header: NodeType = {
     allowReserved: { type: 'boolean' },
     schema: 'Schema',
     example: { isExample: true },
-    examples: mapOf('Example'),
-    content: 'MediaTypeMap',
+    examples: 'ExamplesMap',
+    content: 'MediaTypesMap',
   },
+  requiredOneOf: ['schema', 'content'],
 };
 
 const ResponsesMap: NodeType = {
@@ -242,9 +243,9 @@ const ResponsesMap: NodeType = {
 const Response: NodeType = {
   properties: {
     description: { type: 'string' },
-    headers: mapOf('Header'),
-    content: 'MediaTypeMap',
-    links: mapOf('Link'),
+    headers: 'HeadersMap',
+    content: 'MediaTypesMap',
+    links: 'LinksMap',
   },
   required: ['description'],
 };
@@ -459,26 +460,31 @@ const SecurityScheme: NodeType = {
 };
 
 export const Oas3Types: Record<string, NodeType> = {
-  DefinitionRoot,
+  Root,
   Tag,
   ExternalDocs,
   Server,
   ServerVariable,
+  ServerVariablesMap: mapOf('ServerVariable'),
   SecurityRequirement,
   Info,
   Contact,
   License,
-  PathMap,
+  PathsMap,
   PathItem,
   Parameter,
   Operation,
   Callback: mapOf('PathItem'),
+  CallbacksMap: mapOf('Callback'),
   RequestBody,
-  MediaTypeMap,
+  MediaTypesMap,
   MediaType,
   Example,
+  ExamplesMap: mapOf('Example'),
   Encoding,
+  EncodingsMap: mapOf('Encoding'),
   Header,
+  HeadersMap: mapOf('Header'),
   ResponsesMap,
   Response,
   Link,
@@ -488,6 +494,7 @@ export const Oas3Types: Record<string, NodeType> = {
   DiscriminatorMapping,
   Discriminator,
   Components,
+  LinksMap: mapOf('Link'),
   NamedSchemas: mapOf('Schema'),
   NamedResponses: mapOf('Response'),
   NamedParameters: mapOf('Parameter'),

package/src/types/oas3_1.ts

@@ -1,7 +1,7 @@
 import { NodeType, listOf, mapOf } from '.';
 import { Oas3Types } from './oas3';
 
-const DefinitionRoot: NodeType = {
+const Root: NodeType = {
   properties: {
     openapi: null,
     info: 'Info',
@@ -9,7 +9,7 @@ const DefinitionRoot: NodeType = {
     security: listOf('SecurityRequirement'),
     tags: listOf('Tag'),
     externalDocs: 'ExternalDocs',
-    paths: 'PathMap',
+    paths: 'PathsMap',
     webhooks: 'WebhooksMap',
     components: 'Components',
     jsonSchemaDialect: { type: 'string' },
@@ -241,7 +241,7 @@ const SecurityScheme: NodeType = {
 export const Oas3_1Types: Record<string, NodeType> = {
   ...Oas3Types,
   Info,
-  DefinitionRoot,
+  Root,
   Schema,
   License,
   Components,

package/src/types/redocly-yaml.ts

@@ -1,5 +1,6 @@
 import { NodeType, listOf } from '.';
 import { omitObjectProps, pickObjectProps, isCustomRuleId } from '../utils';
+
 const builtInRulesList = [
   'spec',
   'info-description',
@@ -8,6 +9,7 @@ const builtInRulesList = [
   'info-license-url',
   'operation-2xx-response',
   'operation-4xx-response',
+  'operation-4xx-problem-details-rfc7807',
   'assertions',
   'operation-operationId-unique',
   'operation-parameters-unique',
@@ -31,7 +33,7 @@ const builtInRulesList = [
   'path-params-defined',
   'parameter-description',
   'operation-singular-tag',
-  'operation-security-defined',
+  'security-defined',
   'no-unresolved-refs',
   'paths-kebab-case',
   'boolean-parameter-prefixes',
@@ -40,7 +42,7 @@ const builtInRulesList = [
   'no-identical-paths',
   'no-ambiguous-paths',
   'no-undefined-server-variable',
-  'no-servers-empty-enum',
+  'no-server-variables-empty-enum',
   'no-http-verbs-in-paths',
   'path-excludes-patterns',
   'request-mime-type',
@@ -51,31 +53,38 @@ const builtInRulesList = [
   'response-contains-header',
   'response-contains-property',
   'scalar-property-missing-example',
+  'spec-components-invalid-map-name',
 ];
 const nodeTypesList = [
-  'DefinitionRoot',
+  'Root',
   'Tag',
   'ExternalDocs',
   'Server',
   'ServerVariable',
+  'ServerVariablesMap',
   'SecurityRequirement',
   'Info',
   'Contact',
   'License',
-  'PathMap',
+  'PathsMap',
   'PathItem',
   'Parameter',
   'Operation',
   'Callback',
+  'CallbacksMap',
   'RequestBody',
-  'MediaTypeMap',
+  'MediaTypesMap',
   'MediaType',
   'Example',
+  'ExamplesMap',
   'Encoding',
+  'EncodingsMap',
   'Header',
+  'HeadersMap',
   'ResponsesMap',
   'Response',
   'Link',
+  'LinksMap',
   'Schema',
   'Xml',
   'SchemaProperties',
@@ -101,6 +110,39 @@ const nodeTypesList = [
   'WebhooksMap',
 ];
 
+const ConfigStyleguide: NodeType = {
+  properties: {
+    extends: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+    },
+    rules: 'Rules',
+    oas2Rules: 'Rules',
+    oas3_0Rules: 'Rules',
+    oas3_1Rules: 'Rules',
+    preprocessors: { type: 'object' },
+    oas2Preprocessors: { type: 'object' },
+    oas3_0Preprocessors: { type: 'object' },
+    oas3_1Preprocessors: { type: 'object' },
+    decorators: { type: 'object' },
+    oas2Decorators: { type: 'object' },
+    oas3_0Decorators: { type: 'object' },
+    oas3_1Decorators: { type: 'object' },
+  },
+};
+
+const RootConfigStyleguide: NodeType = {
+  properties: {
+    plugins: {
+      type: 'array',
+      items: { type: 'string' },
+    },
+    ...ConfigStyleguide.properties,
+  },
+};
+
 const ConfigRoot: NodeType = {
   properties: {
     organization: { type: 'string' },
@@ -110,7 +152,8 @@ const ConfigRoot: NodeType = {
       properties: {},
       additionalProperties: { properties: { type: 'string' } },
     }, // deprecated
-    styleguide: 'RootConfigStyleguide',
+    ...RootConfigStyleguide.properties,
+    styleguide: 'RootConfigStyleguide', // deprecated
     lint: 'RootConfigStyleguide', // deprecated
     'features.openapi': 'ConfigReferenceDocs',
     referenceDocs: 'ConfigReferenceDocs', // deprecated
@@ -119,6 +162,7 @@ const ConfigRoot: NodeType = {
     resolve: {
       properties: {
         http: 'ConfigHTTP',
+        doNotResolveExamples: { type: 'boolean' },
       },
     },
   },
@@ -138,7 +182,9 @@ const ConfigApisProperties: NodeType = {
         type: 'string',
       },
     },
-    styleguide: 'ConfigStyleguide',
+    lint: 'ConfigStyleguide', // deprecated
+    styleguide: 'ConfigStyleguide', // deprecated
+    ...ConfigStyleguide.properties,
     'features.openapi': 'ConfigReferenceDocs',
     'features.mockServer': 'ConfigMockServer',
   },
@@ -156,40 +202,6 @@ const ConfigHTTP: NodeType = {
   },
 };
 
-const ConfigStyleguide: NodeType = {
-  properties: {
-    extends: {
-      type: 'array',
-      items: {
-        type: 'string',
-      },
-    },
-    doNotResolveExamples: { type: 'boolean' },
-    rules: 'Rules',
-    oas2Rules: 'Rules',
-    oas3_0Rules: 'Rules',
-    oas3_1Rules: 'Rules',
-    preprocessors: { type: 'object' },
-    oas2Preprocessors: { type: 'object' },
-    oas3_0Preprocessors: { type: 'object' },
-    oas3_1Preprocessors: { type: 'object' },
-    decorators: { type: 'object' },
-    oas2Decorators: { type: 'object' },
-    oas3_0Decorators: { type: 'object' },
-    oas3_1Decorators: { type: 'object' },
-  },
-};
-
-const RootConfigStyleguide: NodeType = {
-  properties: {
-    plugins: {
-      type: 'array',
-      items: { type: 'string' },
-    },
-    ...ConfigStyleguide.properties,
-  },
-};
-
 const Rules: NodeType = {
   properties: {},
   additionalProperties: (value: unknown, key: string) => {

package/src/utils.ts

@@ -6,7 +6,8 @@ import * as pluralize from 'pluralize';
 import { parseYaml } from './js-yaml';
 import { UserContext } from './walk';
 import { HttpResolveConfig } from './config';
-import { env } from './config';
+import { env } from './env';
+import { logger, colorize } from './logger';
 
 export { parseYaml, stringifyYaml } from './js-yaml';
 
@@ -32,7 +33,7 @@ export async function loadYaml<T>(filename: string): Promise<T> {
   return parseYaml(contents) as T;
 }
 
-export function notUndefined<T>(x: T | undefined): x is T {
+export function isDefined<T>(x: T | undefined): x is T {
   return x !== undefined;
 }
 
@@ -95,7 +96,7 @@ export function omitObjectProps<T extends Record<string, unknown>>(
 export function splitCamelCaseIntoWords(str: string) {
   const camel = str
     .split(/(?:[-._])|([A-Z][a-z]+)/)
-    .filter(Boolean)
+    .filter(isTruthy)
     .map((item) => item.toLocaleLowerCase());
   const caps = str
     .split(/([A-Z]{2,})/)
@@ -182,7 +183,7 @@ export function isNotString<T>(value: string | T): value is T {
 }
 
 export function assignExisting<T>(target: Record<string, T>, obj: Record<string, T>) {
-  for (let k of Object.keys(obj)) {
+  for (const k of Object.keys(obj)) {
     if (target.hasOwnProperty(k)) {
       target[k] = obj[k];
     }
@@ -204,3 +205,29 @@ export function doesYamlFileExist(filePath: string): boolean {
     fs.existsSync(filePath)
   );
 }
+
+export function showWarningForDeprecatedField(deprecatedField: string, updatedField?: string) {
+  logger.warn(
+    `The '${colorize.red(deprecatedField)}' field is deprecated. ${
+      updatedField ? `Use ${colorize.green(updatedField)} instead. ` : ''
+    }Read more about this change: https://redocly.com/docs/api-registry/guides/migration-guide-config-file/#changed-properties\n`
+  );
+}
+
+export function showErrorForDeprecatedField(deprecatedField: string, updatedField?: string) {
+  throw new Error(
+    `Do not use '${deprecatedField}' field. ${
+      updatedField ? `Use '${updatedField}' instead. ` : ''
+    }\n`
+  );
+}
+
+export type Falsy = undefined | null | false | '' | 0;
+
+export function isTruthy<Truthy>(value: Truthy | Falsy): value is Truthy {
+  return !!value;
+}
+
+export function identity<T>(value: T): T {
+  return value;
+}

package/src/visitors.ts

@@ -27,7 +27,7 @@ import type {
   Oas3Callback,
 } from './typings/openapi';
 
-import {
+import type {
   Oas2Definition,
   Oas2Tag,
   Oas2ExternalDocs,
@@ -45,10 +45,11 @@ import {
   Oas2SecurityScheme,
 } from './typings/swagger';
 
-import { NormalizedNodeType } from './types';
-import { Stack } from './utils';
-import { UserContext, ResolveResult, ProblemSeverity } from './walk';
-import { Location } from './ref-utils';
+import type { NormalizedNodeType } from './types';
+import type { Stack } from './utils';
+import type { UserContext, ResolveResult, ProblemSeverity } from './walk';
+import type { Location } from './ref-utils';
+
 export type VisitFunction<T> = (
   node: T,
   ctx: UserContext & { ignoreNextVisitorsOnNode: () => void },
@@ -70,7 +71,7 @@ type NestedVisitObject<T, P> = VisitObject<T> & NestedVisitor<P>;
 
 type VisitFunctionOrObject<T> = VisitFunction<T> | VisitObject<T>;
 
-type VisitorNode<T extends any> = {
+type VisitorNode<T> = {
   ruleId: string;
   severity: ProblemSeverity;
   context: VisitorLevelContext | VisitorSkippedLevelContext;
@@ -126,7 +127,7 @@ export type BaseVisitor = {
 };
 
 type Oas3FlatVisitor = {
-  DefinitionRoot?: VisitFunctionOrObject<Oas3Definition>;
+  Root?: VisitFunctionOrObject<Oas3Definition>;
   Tag?: VisitFunctionOrObject<Oas3Tag>;
   ExternalDocs?: VisitFunctionOrObject<Oas3ExternalDocs>;
   Server?: VisitFunctionOrObject<Oas3Server>;
@@ -135,13 +136,13 @@ type Oas3FlatVisitor = {
   Info?: VisitFunctionOrObject<Oas3Info>;
   Contact?: VisitFunctionOrObject<Oas3Contact>;
   License?: VisitFunctionOrObject<Oas3License>;
-  PathMap?: VisitFunctionOrObject<Record<string, Oas3PathItem>>;
+  PathsMap?: VisitFunctionOrObject<Record<string, Oas3PathItem>>;
   PathItem?: VisitFunctionOrObject<Oas3PathItem>;
   Callback?: VisitFunctionOrObject<Record<string, Oas3PathItem>>;
   Parameter?: VisitFunctionOrObject<Oas3Parameter>;
   Operation?: VisitFunctionOrObject<Oas3Operation>;
   RequestBody?: VisitFunctionOrObject<Oas3RequestBody>;
-  MediaTypeMap?: VisitFunctionOrObject<Record<string, Oas3MediaType>>;
+  MediaTypesMap?: VisitFunctionOrObject<Record<string, Oas3MediaType>>;
   MediaType?: VisitFunctionOrObject<Oas3MediaType>;
   Example?: VisitFunctionOrObject<Oas3Example>;
   Encoding?: VisitFunctionOrObject<Oas3Encoding>;
@@ -173,14 +174,14 @@ type Oas3FlatVisitor = {
 };
 
 type Oas2FlatVisitor = {
-  DefinitionRoot?: VisitFunctionOrObject<Oas2Definition>;
+  Root?: VisitFunctionOrObject<Oas2Definition>;
   Tag?: VisitFunctionOrObject<Oas2Tag>;
   ExternalDocs?: VisitFunctionOrObject<Oas2ExternalDocs>;
   SecurityRequirement?: VisitFunctionOrObject<Oas2SecurityRequirement>;
   Info?: VisitFunctionOrObject<Oas2Info>;
   Contact?: VisitFunctionOrObject<Oas2Contact>;
   License?: VisitFunctionOrObject<Oas2License>;
-  PathMap?: VisitFunctionOrObject<Record<string, Oas2PathItem>>;
+  PathsMap?: VisitFunctionOrObject<Record<string, Oas2PathItem>>;
   PathItem?: VisitFunctionOrObject<Oas2PathItem>;
   Parameter?: VisitFunctionOrObject<any>;
   Operation?: VisitFunctionOrObject<Oas2Operation>;
@@ -197,6 +198,18 @@ type Oas2FlatVisitor = {
   SecurityScheme?: VisitFunctionOrObject<Oas2SecurityScheme>;
 };
 
+const legacyTypesMap = {
+  Root: 'DefinitionRoot',
+  ServerVariablesMap: 'ServerVariableMap',
+  PathsMap: 'PathMap',
+  CallbacksMap: 'CallbackMap',
+  MediaTypesMap: 'MediaTypeMap',
+  ExamplesMap: 'ExampleMap',
+  EncodingsMap: 'EncodingMap',
+  HeadersMap: 'HeaderMap',
+  LinksMap: 'LinkMap',
+};
+
 type Oas3NestedVisitor = {
   [T in keyof Oas3FlatVisitor]: Oas3FlatVisitor[T] extends Function
     ? Oas3FlatVisitor[T]
@@ -225,7 +238,7 @@ export type Oas2TransformVisitor = BaseVisitor &
   Oas2FlatVisitor &
   Record<string, VisitFunction<any> | VisitObject<any>>;
 
-export type NestedVisitor<T> = Exclude<T, 'any' | 'ref' | 'DefinitionRoot'>;
+export type NestedVisitor<T> = Exclude<T, 'any' | 'ref' | 'Root'>;
 
 export type NormalizedOasVisitors<T extends BaseVisitor> = {
   [V in keyof T]-?: {
@@ -309,7 +322,7 @@ export function normalizeVisitors<T extends BaseVisitor>(
 
     const possibleChildren = new Set<NormalizedNodeType>();
 
-    for (let type of Object.values(from.properties)) {
+    for (const type of Object.values(from.properties)) {
       if (type === to) {
         addWeakFromStack(ruleConf, stack);
         continue;
@@ -333,7 +346,7 @@ export function normalizeVisitors<T extends BaseVisitor>(
       }
     }
 
-    for (let fromType of Array.from(possibleChildren.values())) {
+    for (const fromType of Array.from(possibleChildren.values())) {
       addWeakNodes(ruleConf, fromType, to, parentContext, stack);
     }
 
@@ -350,7 +363,7 @@ export function normalizeVisitors<T extends BaseVisitor>(
           visit: () => undefined,
           depth: 0,
           context: {
-            isSkippedLevel: true as true,
+            isSkippedLevel: true,
             seen: new Set(),
             parent: parentContext,
           },
@@ -380,8 +393,11 @@ export function normalizeVisitors<T extends BaseVisitor>(
     }
 
     for (const typeName of visitorKeys as Array<keyof T>) {
-      const typeVisitor = visitor[typeName] as any as NestedVisitObject<any, T>;
-      const normalizedTypeVisitor = normalizedVisitors[typeName]!;
+      const typeVisitor = (visitor[typeName] ||
+        visitor[
+          legacyTypesMap[typeName as keyof typeof legacyTypesMap] as keyof T
+        ]) as any as NestedVisitObject<any, T>;
+      const normalizedTypeVisitor = normalizedVisitors[typeName];
 
       if (!typeVisitor) continue;
 
@@ -407,7 +423,7 @@ export function normalizeVisitors<T extends BaseVisitor>(
         activatedOn: null,
         type: types[typeName],
         parent: parentContext,
-        isSkippedLevel: false as false,
+        isSkippedLevel: false,
       };
 
       if (typeof typeVisitor === 'object') {

package/src/walk.ts

@@ -18,6 +18,8 @@ import {
 import { pushStack, popStack } from './utils';
 import { OasVersion } from './oas-types';
 import { NormalizedNodeType, isNamedType } from './types';
+import type { RuleSeverity } from './config';
+
 type NonUndefined = string | number | boolean | symbol | bigint | object | Record<string, any>;
 
 export type ResolveResult<T extends NonUndefined> =
@@ -66,7 +68,7 @@ export type Problem = {
   suggest?: string[];
   location?: Partial<LocationObject> | Array<Partial<LocationObject>>;
   from?: LocationObject;
-  forceSeverity?: ProblemSeverity;
+  forceSeverity?: RuleSeverity;
   ruleId?: string;
 };
 
@@ -409,17 +411,19 @@ export function walkDocument<T>(opts: {
           : [opts.location]
         : [{ ...currentLocation, reportOnKey: false }];
 
-      ctx.problems.push({
-        ruleId: opts.ruleId || ruleId,
-        severity: opts.forceSeverity || severity,
-        ...opts,
-        suggest: opts.suggest || [],
-        location: loc.map((loc: any) => {
-          return { ...currentLocation, reportOnKey: false, ...loc };
-        }),
-      });
+      const ruleSeverity = opts.forceSeverity || severity;
+      if (ruleSeverity !== 'off') {
+        ctx.problems.push({
+          ruleId: opts.ruleId || ruleId,
+          severity: ruleSeverity,
+          ...opts,
+          suggest: opts.suggest || [],
+          location: loc.map((loc: any) => {
+            return { ...currentLocation, reportOnKey: false, ...loc };
+          }),
+        });
+      }
     }
-
     function getVisitorDataFn(ruleId: string) {
       ctx.visitorsData[ruleId] = ctx.visitorsData[ruleId] || {};
       return ctx.visitorsData[ruleId];