@redocly/openapi-core 1.0.0-beta.111 → 1.0.0-beta.112

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

@@ -1,8 +1,15 @@
-import type { AssertResult, RuleSeverity } from '../../../config';
+import { asserts, runOnKeysSet, runOnValuesSet, Asserts } from './asserts';
 import { colorize } from '../../../logger';
 import { isRef, Location } from '../../../ref-utils';
-import { UserContext } from '../../../walk';
-import { asserts } from './asserts';
+import { isTruthy, keysOf, isString } from '../../../utils';
+import type { AssertResult } from '../../../config';
+import type { Assertion, AssertionDefinition, AssertionLocators } from '.';
+import type {
+  Oas2Visitor,
+  Oas3Visitor,
+  SkipFunctionContext,
+  VisitFunction,
+} from '../../../visitors';
 
 export type OrderDirection = 'asc' | 'desc';
 
@@ -11,166 +18,236 @@ export type OrderOptions = {
   property: string;
 };
 
-type Assertion = {
-  property: string | string[];
-  context?: Record<string, any>[];
-  severity?: RuleSeverity;
-  suggest?: any[];
-  message?: string;
-  subject: string;
-};
-
 export type AssertToApply = {
-  name: string;
+  name: keyof Asserts;
   conditions: any;
   runsOnKeys: boolean;
   runsOnValues: boolean;
 };
 
+type AssertionContext = SkipFunctionContext & {
+  node: any;
+};
+
+const assertionMessageTemplates = {
+  problems: '{{problems}}',
+};
+
+function getPredicatesFromLocators(
+  locators: AssertionLocators
+): ((key: string | number) => boolean)[] {
+  const { filterInParentKeys, filterOutParentKeys, matchParentKeys } = locators;
+
+  const keyMatcher = matchParentKeys && regexFromString(matchParentKeys);
+  const matchKeysPredicate =
+    keyMatcher && ((key: string | number) => keyMatcher.test(key.toString()));
+
+  const filterInPredicate =
+    Array.isArray(filterInParentKeys) &&
+    ((key: string | number) => filterInParentKeys.includes(key.toString()));
+
+  const filterOutPredicate =
+    Array.isArray(filterOutParentKeys) &&
+    ((key: string | number) => !filterOutParentKeys.includes(key.toString()));
+
+  return [matchKeysPredicate, filterInPredicate, filterOutPredicate].filter(isTruthy);
+}
+
+export function getAssertsToApply(assertion: AssertionDefinition): AssertToApply[] {
+  const assertsToApply = keysOf(asserts)
+    .filter((assertName) => assertion.assertions[assertName] !== undefined)
+    .map((assertName) => {
+      return {
+        name: assertName,
+        conditions: assertion.assertions[assertName],
+        runsOnKeys: runOnKeysSet.has(assertName),
+        runsOnValues: runOnValuesSet.has(assertName),
+      };
+    });
+
+  const shouldRunOnKeys: AssertToApply | undefined = assertsToApply.find(
+    (assert: AssertToApply) => assert.runsOnKeys && !assert.runsOnValues
+  );
+  const shouldRunOnValues: AssertToApply | undefined = assertsToApply.find(
+    (assert: AssertToApply) => assert.runsOnValues && !assert.runsOnKeys
+  );
+
+  if (shouldRunOnValues && !assertion.subject.property) {
+    throw new Error(
+      `${shouldRunOnValues.name} can't be used on all keys. Please provide a single property`
+    );
+  }
+
+  if (shouldRunOnKeys && assertion.subject.property) {
+    throw new Error(
+      `${shouldRunOnKeys.name} can't be used on a single property. Please use 'property'.`
+    );
+  }
+
+  return assertsToApply;
+}
+
+function getAssertionProperties({ subject }: AssertionDefinition): string[] {
+  return (Array.isArray(subject.property) ? subject.property : [subject?.property]).filter(
+    Boolean
+  ) as string[];
+}
+
+function applyAssertions(
+  assertionDefinition: AssertionDefinition,
+  asserts: AssertToApply[],
+  { rawLocation, rawNode, resolve, location, node }: AssertionContext
+): AssertResult[] {
+  const properties = getAssertionProperties(assertionDefinition);
+  const assertResults: Array<AssertResult[]> = [];
+
+  for (const assert of asserts) {
+    const currentLocation = assert.name === 'ref' ? rawLocation : location;
+
+    if (properties.length) {
+      for (const property of properties) {
+        // we can have resolvable scalar so need to resolve value here.
+        const value = isRef(node[property]) ? resolve(node[property])?.node : node[property];
+        assertResults.push(
+          runAssertion({
+            values: value,
+            rawValues: rawNode[property],
+            assert,
+            location: currentLocation.child(property),
+          })
+        );
+      }
+    } else {
+      const value = assert.name === 'ref' ? rawNode : Object.keys(node);
+      assertResults.push(
+        runAssertion({
+          values: Object.keys(node),
+          rawValues: value,
+          assert,
+          location: currentLocation,
+        })
+      );
+    }
+  }
+
+  return assertResults.flat();
+}
+
 export function buildVisitorObject(
-  subject: string,
-  context: Record<string, any>[],
-  subjectVisitor: any
-) {
-  if (!context) {
-    return { [subject]: subjectVisitor };
+  assertion: Assertion,
+  subjectVisitor: VisitFunction<any>
+): Oas2Visitor | Oas3Visitor {
+  const targetVisitorLocatorPredicates = getPredicatesFromLocators(assertion.subject);
+  const targetVisitorSkipFunction = targetVisitorLocatorPredicates.length
+    ? (node: any, key: string | number) =>
+        !targetVisitorLocatorPredicates.every((predicate) => predicate(key))
+    : undefined;
+  const targetVisitor: Oas2Visitor | Oas3Visitor = {
+    [assertion.subject.type]: {
+      enter: subjectVisitor,
+      ...(targetVisitorSkipFunction && { skip: targetVisitorSkipFunction }),
+    },
+  };
+
+  if (!Array.isArray(assertion.where)) {
+    return targetVisitor;
   }
 
   let currentVisitorLevel: Record<string, any> = {};
   const visitor: Record<string, any> = currentVisitorLevel;
+  const context = assertion.where;
 
   for (let index = 0; index < context.length; index++) {
-    const node = context[index];
-    if (context.length === index + 1 && node.type === subject) {
-      // Visitors don't work properly for the same type nested nodes, so
-      // as a workaround for that we don't create separate visitor for the last element
-      // which is the same as subject;
-      // we will check includes/excludes it in the last visitor.
-      continue;
-    }
-    const matchParentKeys = node.matchParentKeys;
-    const excludeParentKeys = node.excludeParentKeys;
+    const assertionDefinitionNode = context[index];
 
-    if (matchParentKeys && excludeParentKeys) {
+    if (!isString(assertionDefinitionNode.subject?.type)) {
       throw new Error(
-        `Both 'matchParentKeys' and 'excludeParentKeys' can't be under one context item`
+        `${assertion.assertionId} -> where -> [${index}]: 'type' (String) is required`
       );
     }
 
-    if (matchParentKeys || excludeParentKeys) {
-      currentVisitorLevel[node.type] = {
-        skip: (_value: any, key: string) => {
-          if (matchParentKeys) {
-            return !matchParentKeys.includes(key);
-          }
-          if (excludeParentKeys) {
-            return excludeParentKeys.includes(key);
-          }
-        },
+    const locatorPredicates = getPredicatesFromLocators(assertionDefinitionNode.subject);
+    const assertsToApply = getAssertsToApply(assertionDefinitionNode);
+
+    const skipFunction = (
+      node: unknown,
+      key: string | number,
+      { location, rawLocation, resolve, rawNode }: SkipFunctionContext
+    ): boolean =>
+      !locatorPredicates.every((predicate) => predicate(key)) ||
+      !!applyAssertions(assertionDefinitionNode, assertsToApply, {
+        location,
+        node,
+        rawLocation,
+        rawNode,
+        resolve,
+      }).length;
+
+    const nodeVisitor = {
+      ...((locatorPredicates.length || assertsToApply.length) && { skip: skipFunction }),
+    };
+
+    if (
+      assertionDefinitionNode.subject.type === assertion.subject.type &&
+      index === context.length - 1
+    ) {
+      // We have to merge the visitors if the last node inside the `where` is the same as the subject.
+      targetVisitor[assertion.subject.type] = {
+        enter: subjectVisitor,
+        ...((nodeVisitor.skip && { skip: nodeVisitor.skip }) ||
+          (targetVisitorSkipFunction && {
+            skip: (
+              node,
+              key,
+              ctx // We may have locators defined on assertion level and on where level for the same node type
+            ) => !!(nodeVisitor.skip?.(node, key, ctx) || targetVisitorSkipFunction?.(node, key)),
+          })),
       };
     } else {
-      currentVisitorLevel[node.type] = {};
+      currentVisitorLevel = currentVisitorLevel[assertionDefinitionNode.subject?.type] =
+        nodeVisitor;
     }
-    currentVisitorLevel = currentVisitorLevel[node.type];
   }
 
-  currentVisitorLevel[subject] = subjectVisitor;
+  currentVisitorLevel[assertion.subject.type] = targetVisitor[assertion.subject.type];
 
   return visitor;
 }
 
-export function buildSubjectVisitor(
-  assertId: string,
-  assertion: Assertion,
-  asserts: AssertToApply[]
-) {
-  return (
-    node: any,
-    { report, location, rawLocation, key, type, resolve, rawNode }: UserContext
-  ) => {
-    let properties = assertion.property;
-    // We need to check context's last node if it has the same type as subject node;
-    // if yes - that means we didn't create context's last node visitor,
-    // so we need to handle 'matchParentKeys' and 'excludeParentKeys' conditions here;
-    if (assertion.context) {
-      const lastContextNode = assertion.context[assertion.context.length - 1];
-      if (lastContextNode.type === type.name) {
-        const matchParentKeys = lastContextNode.matchParentKeys;
-        const excludeParentKeys = lastContextNode.excludeParentKeys;
-
-        if (matchParentKeys && !matchParentKeys.includes(key)) {
-          return;
-        }
-        if (excludeParentKeys && excludeParentKeys.includes(key)) {
-          return;
-        }
-      }
-    }
-
-    if (properties) {
-      properties = Array.isArray(properties) ? properties : [properties];
-    }
+export function buildSubjectVisitor(assertId: string, assertion: Assertion): VisitFunction<any> {
+  return (node: any, { report, location, rawLocation, resolve, rawNode }) => {
+    const properties = getAssertionProperties(assertion);
 
     const defaultMessage = `${colorize.blue(assertId)} failed because the ${colorize.blue(
-      assertion.subject
-    )}${colorize.blue(
-      properties ? ` ${(properties as string[]).join(', ')}` : ''
-    )} didn't meet the assertions: {{problems}}`;
-
-    const assertResults: Array<AssertResult[]> = [];
-    for (const assert of asserts) {
-      const currentLocation = assert.name === 'ref' ? rawLocation : location;
-      if (properties) {
-        for (const property of properties) {
-          // we can have resolvable scalar so need to resolve value here.
-          const value = isRef(node[property]) ? resolve(node[property])?.node : node[property];
-          assertResults.push(
-            runAssertion({
-              values: value,
-              rawValues: rawNode[property],
-              assert,
-              location: currentLocation.child(property),
-            })
-          );
-        }
-      } else {
-        const value = assert.name === 'ref' ? rawNode : Object.keys(node);
-        assertResults.push(
-          runAssertion({
-            values: Object.keys(node),
-            rawValues: value,
-            assert,
-            location: currentLocation,
-          })
-        );
-      }
-    }
+      assertion.subject.type
+    )} ${colorize.blue(properties.join(', '))} didn't meet the assertions: ${
+      assertionMessageTemplates.problems
+    }`.replace(/ +/g, ' ');
+
+    const problems = applyAssertions(assertion, getAssertsToApply(assertion), {
+      rawLocation,
+      rawNode,
+      resolve,
+      location,
+      node,
+    });
 
-    const problems = assertResults.flat();
     if (problems.length) {
       const message = assertion.message || defaultMessage;
-
-      report({
-        message: message.replace('{{problems}}', getProblemsMessage(problems)),
-        location: getProblemsLocation(problems) || location,
-        forceSeverity: assertion.severity || 'error',
-        suggest: assertion.suggest || [],
-        ruleId: assertId,
-      });
+      for (const problem of problems) {
+        const problemMessage = problem.message ? problem.message : defaultMessage;
+        report({
+          message: message.replace(assertionMessageTemplates.problems, problemMessage),
+          location: problem.location || location,
+          forceSeverity: assertion.severity || 'error',
+          suggest: assertion.suggest || [],
+          ruleId: assertId,
+        });
+      }
     }
   };
 }
 
-function getProblemsLocation(problems: AssertResult[]) {
-  return problems.length ? problems[0].location : undefined;
-}
-
-function getProblemsMessage(problems: AssertResult[]) {
-  return problems.length === 1
-    ? problems[0].message ?? ''
-    : problems.map((problem) => `\n- ${problem.message ?? ''}`).join('');
-}
-
 export function getIntersectionLength(keys: string[], properties: string[]): number {
   const props = new Set(properties);
   let count = 0;

package/src/rules/oas2/index.ts

@@ -2,7 +2,6 @@ import { Oas2Rule } from '../../visitors';
 import { OasSpec } from '../common/spec';
 import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
 import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
-import { InfoDescription } from '../common/info-description';
 import { InfoContact } from '../common/info-contact';
 import { InfoLicense } from '../common/info-license';
 import { InfoLicenseUrl } from '../common/info-license-url';
@@ -45,7 +44,6 @@ export const rules = {
   spec: OasSpec as Oas2Rule,
   'no-invalid-schema-examples': NoInvalidSchemaExamples,
   'no-invalid-parameter-examples': NoInvalidParameterExamples,
-  'info-description': InfoDescription as Oas2Rule,
   'info-contact': InfoContact as Oas2Rule,
   'info-license': InfoLicense as Oas2Rule,
   'info-license-url': InfoLicenseUrl as Oas2Rule,

package/src/rules/oas3/index.ts

@@ -15,7 +15,6 @@ import { OperationIdUrlSafe } from '../common/operation-operationId-url-safe';
 import { TagsAlphabetical } from '../common/tags-alphabetical';
 import { NoServerExample } from './no-server-example.com';
 import { NoServerTrailingSlash } from './no-server-trailing-slash';
-import { InfoDescription } from '../common/info-description';
 import { TagDescription } from '../common/tag-description';
 import { InfoContact } from '../common/info-contact';
 import { InfoLicense } from '../common/info-license';
@@ -53,7 +52,6 @@ import { Operation4xxProblemDetailsRfc7807 } from './operation-4xx-problem-detai
 
 export const rules = {
   spec: OasSpec,
-  'info-description': InfoDescription,
   'info-contact': InfoContact,
   'info-license': InfoLicense,
   'info-license-url': InfoLicenseUrl,

package/src/types/redocly-yaml.ts

@@ -3,7 +3,6 @@ import { omitObjectProps, pickObjectProps, isCustomRuleId } from '../utils';
 
 const builtInRulesList = [
   'spec',
-  'info-description',
   'info-contact',
   'info-license',
   'info-license-url',
@@ -147,16 +146,8 @@ const ConfigRoot: NodeType = {
   properties: {
     organization: { type: 'string' },
     apis: 'ConfigApis',
-    apiDefinitions: {
-      type: 'object',
-      properties: {},
-      additionalProperties: { properties: { type: 'string' } },
-    }, // deprecated
     ...RootConfigStyleguide.properties,
-    styleguide: 'RootConfigStyleguide', // deprecated
-    lint: 'RootConfigStyleguide', // deprecated
     'features.openapi': 'ConfigReferenceDocs',
-    referenceDocs: 'ConfigReferenceDocs', // deprecated
     'features.mockServer': 'ConfigMockServer',
     region: { enum: ['us', 'eu'] },
     resolve: {
@@ -239,15 +230,9 @@ const ObjectRule: NodeType = {
   required: ['severity'],
 };
 
-const Assert: NodeType = {
+const AssertionDefinitionSubject: NodeType = {
   properties: {
-    subject: (value: unknown) => {
-      if (Array.isArray(value)) {
-        return { type: 'array', items: { enum: nodeTypesList } };
-      } else {
-        return { enum: nodeTypesList };
-      }
-    },
+    type: { enum: nodeTypesList },
     property: (value: unknown) => {
       if (Array.isArray(value)) {
         return { type: 'array', items: { type: 'string' } };
@@ -257,10 +242,15 @@ const Assert: NodeType = {
         return { type: 'string' };
       }
     },
-    context: listOf('Context'),
-    message: { type: 'string' },
-    suggest: { type: 'array', items: { type: 'string' } },
-    severity: { enum: ['error', 'warn', 'off'] },
+    filterInParentKeys: { type: 'array', items: { type: 'string' } },
+    filterOutParentKeys: { type: 'array', items: { type: 'string' } },
+    matchParentKeys: { type: 'string' },
+  },
+  required: ['type'],
+};
+
+const AssertionDefinitionAssertions: NodeType = {
+  properties: {
     enum: { type: 'array', items: { type: 'string' } },
     pattern: { type: 'string' },
     casing: {
@@ -280,27 +270,50 @@ const Assert: NodeType = {
     requireAny: { type: 'array', items: { type: 'string' } },
     disallowed: { type: 'array', items: { type: 'string' } },
     defined: { type: 'boolean' },
-    undefined: { type: 'boolean' },
+    // undefined: { type: 'boolean' }, // TODO: Remove `undefined` assertion from codebase overall
     nonEmpty: { type: 'boolean' },
     minLength: { type: 'integer' },
     maxLength: { type: 'integer' },
     ref: (value: string | boolean) =>
       typeof value === 'string' ? { type: 'string' } : { type: 'boolean' },
+    const: (value: string | boolean | number) => {
+      if (typeof value === 'string') {
+        return { type: 'string' };
+      }
+      if (typeof value === 'number') {
+        return { type: 'number' };
+      }
+      if (typeof value === 'boolean') {
+        return { type: 'boolean' };
+      } else {
+        return;
+      }
+    },
   },
   additionalProperties: (_value: unknown, key: string) => {
     if (/^\w+\/\w+$/.test(key)) return { type: 'object' };
     return;
   },
-  required: ['subject'],
 };
 
-const Context: NodeType = {
+const AssertDefinition: NodeType = {
   properties: {
-    type: { enum: nodeTypesList },
-    matchParentKeys: { type: 'array', items: { type: 'string' } },
-    excludeParentKeys: { type: 'array', items: { type: 'string' } },
+    subject: 'AssertionDefinitionSubject',
+    assertions: 'AssertionDefinitionAssertions',
   },
-  required: ['type'],
+  required: ['subject', 'assertions'],
+};
+
+const Assert: NodeType = {
+  properties: {
+    subject: 'AssertionDefinitionSubject',
+    assertions: 'AssertionDefinitionAssertions',
+    where: listOf('AssertDefinition'),
+    message: { type: 'string' },
+    suggest: { type: 'array', items: { type: 'string' } },
+    severity: { enum: ['error', 'warn', 'off'] },
+  },
+  required: ['subject', 'assertions'],
 };
 
 const ConfigLanguage: NodeType = {
@@ -926,7 +939,7 @@ export const ConfigTypes: Record<string, NodeType> = {
   ConfigSidebarLinks,
   CommonConfigSidebarLinks,
   ConfigTheme,
-  Context,
+  AssertDefinition,
   ThemeColors,
   CommonThemeColors,
   BorderThemeColors,
@@ -973,4 +986,6 @@ export const ConfigTypes: Record<string, NodeType> = {
   Sidebar,
   Heading,
   Typography,
+  AssertionDefinitionAssertions,
+  AssertionDefinitionSubject,
 };

package/src/utils.ts

@@ -232,6 +232,11 @@ export function identity<T>(value: T): T {
   return value;
 }
 
+export function keysOf<T>(obj: T) {
+  if (!obj) return [];
+  return Object.keys(obj) as (keyof T)[];
+}
+
 export function pickDefined<T extends Record<string, unknown>>(
   obj?: T
 ): Record<string, unknown> | undefined {

package/src/visitors.ts

@@ -50,6 +50,11 @@ import type { Stack } from './utils';
 import type { UserContext, ResolveResult, ProblemSeverity } from './walk';
 import type { Location } from './ref-utils';
 
+export type SkipFunctionContext = Pick<
+  UserContext,
+  'location' | 'rawNode' | 'resolve' | 'rawLocation'
+>;
+
 export type VisitFunction<T> = (
   node: T,
   ctx: UserContext & { ignoreNextVisitorsOnNode: () => void },
@@ -59,7 +64,7 @@ export type VisitFunction<T> = (
 
 type VisitRefFunction = (node: OasRef, ctx: UserContext, resolved: ResolveResult<any>) => void;
 
-type SkipFunction<T> = (node: T, key: string | number) => boolean;
+type SkipFunction<T> = (node: T, key: string | number, ctx: SkipFunctionContext) => boolean;
 
 type VisitObject<T> = {
   enter?: VisitFunction<T>;
@@ -210,6 +215,7 @@ const legacyTypesMap = {
   HeadersMap: 'HeaderMap',
   LinksMap: 'LinkMap',
   OAuth2Flows: 'SecuritySchemeFlows',
+  Responses: 'ResponsesMap',
 };
 
 type Oas3NestedVisitor = {

package/src/walk.ts

@@ -226,7 +226,14 @@ export function walkDocument<T>(opts: {
               nextLevelTypeActivated: null,
               withParentNode: context.parent?.activatedOn?.value.node,
               skipped:
-                (context.parent?.activatedOn?.value.skipped || skip?.(resolvedNode, key)) ?? false,
+                (context.parent?.activatedOn?.value.skipped ||
+                  skip?.(resolvedNode, key, {
+                    location,
+                    rawLocation,
+                    resolve,
+                    rawNode: node,
+                  })) ??
+                false,
             };
 
             context.activatedOn = pushStack<any>(context.activatedOn, activatedOn);