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

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

@@ -9,12 +9,33 @@ import {
   regexFromString,
 } from './utils';
 
-type Asserts = Record<
-  string,
-  (value: any, condition: any, baseLocation: Location, rawValue?: any) => AssertResult[]
->;
+export type AssertionFn = (
+  value: any,
+  condition: any,
+  baseLocation: Location,
+  rawValue?: any
+) => AssertResult[];
 
-export const runOnKeysSet = new Set([
+export type Asserts = {
+  pattern: AssertionFn;
+  enum: AssertionFn;
+  defined: AssertionFn;
+  required: AssertionFn;
+  disallowed: AssertionFn;
+  undefined: AssertionFn;
+  nonEmpty: AssertionFn;
+  minLength: AssertionFn;
+  maxLength: AssertionFn;
+  casing: AssertionFn;
+  sortOrder: AssertionFn;
+  mutuallyExclusive: AssertionFn;
+  mutuallyRequired: AssertionFn;
+  requireAny: AssertionFn;
+  ref: AssertionFn;
+  const: AssertionFn;
+};
+
+export const runOnKeysSet = new Set<keyof Asserts>([
   'mutuallyExclusive',
   'mutuallyRequired',
   'enum',
@@ -27,8 +48,10 @@ export const runOnKeysSet = new Set([
   'required',
   'requireAny',
   'ref',
+  'const',
+  'defined', // In case if `property` for assertions is not added
 ]);
-export const runOnValuesSet = new Set([
+export const runOnValuesSet = new Set<keyof Asserts>([
   'pattern',
   'enum',
   'defined',
@@ -39,6 +62,7 @@ export const runOnValuesSet = new Set([
   'casing',
   'sortOrder',
   'ref',
+  'const',
 ]);
 
 export const asserts: Asserts = {
@@ -106,6 +130,34 @@ export const asserts: Asserts = {
       )
       .filter(isTruthy);
   },
+  const: (
+    value: string | number | boolean | string[] | number[],
+    condition: string | number | boolean,
+    baseLocation: Location
+  ) => {
+    if (typeof value === 'undefined') return [];
+
+    if (Array.isArray(value)) {
+      return value
+        .map(
+          (_val) =>
+            condition !== _val && {
+              message: `"${_val}" should be equal ${condition} `,
+              location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
+            }
+        )
+        .filter(isTruthy);
+    } else {
+      return value !== condition
+        ? [
+            {
+              message: `${value} should be equal ${condition}`,
+              location: baseLocation,
+            },
+          ]
+        : [];
+    }
+  },
   undefined: (value: any, condition: boolean = true, baseLocation: Location) => {
     const isUndefined = typeof value === 'undefined';
     const isValid = condition ? isUndefined : !isUndefined;
@@ -210,7 +262,7 @@ export const asserts: Asserts = {
           },
         ];
   },
-  ref: (_value: any, condition: string | boolean, baseLocation, rawValue: any) => {
+  ref: (_value: any, condition: string | boolean, baseLocation: Location, rawValue: any) => {
     if (typeof rawValue === 'undefined') return []; // property doesn't exist, no need to lint it with this assert
     const hasRef = rawValue.hasOwnProperty('$ref');
     if (typeof condition === 'boolean') {
@@ -237,7 +289,7 @@ export const asserts: Asserts = {
   },
 };
 
-export function buildAssertCustomFunction(fn: CustomFunction) {
+export function buildAssertCustomFunction(fn: CustomFunction): AssertionFn {
   return (value: string[], options: any, baseLocation: Location) =>
     fn.call(null, value, options, baseLocation);
 }

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

@@ -1,65 +1,55 @@
-import { asserts, runOnKeysSet, runOnValuesSet } from './asserts';
-import { AssertToApply, buildSubjectVisitor, buildVisitorObject } from './utils';
-import { Oas2Rule, Oas3Rule } from '../../../visitors';
+import { asserts, AssertionFn } from './asserts';
+import { buildSubjectVisitor, buildVisitorObject } from './utils';
+import { Oas2Visitor, Oas3Visitor } from '../../../visitors';
+import { RuleSeverity } from '../../../config';
+import { isString } from '../../../utils';
+
+export type AssertionLocators = {
+  filterInParentKeys?: (string | number)[];
+  filterOutParentKeys?: (string | number)[];
+  matchParentKeys?: string;
+};
+
+export type AssertionDefinition = {
+  subject: {
+    type: string;
+    property?: string | string[];
+  } & AssertionLocators;
+  assertions: { [name in keyof typeof asserts]?: AssertionFn };
+};
 
-export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
-  const visitors: any[] = [];
+export type RawAssertion = AssertionDefinition & {
+  where?: AssertionDefinition[];
+  message?: string;
+  suggest?: string[];
+  severity?: RuleSeverity;
+};
+
+export type Assertion = RawAssertion & { assertionId: string };
+
+export const Assertions = (opts: Record<string, Assertion>) => {
+  const visitors: (Oas2Visitor | Oas3Visitor)[] = [];
 
   // As 'Assertions' has an array of asserts,
   // that array spreads into an 'opts' object on init rules phase here
   // https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/config/config.ts#L311
   // that is why we need to iterate through 'opts' values;
   // before - filter only object 'opts' values
-  const assertions: any[] = Object.values(opts).filter(
+  const assertions: Assertion[] = Object.values(opts).filter(
     (opt: unknown) => typeof opt === 'object' && opt !== null
   );
 
   for (const [index, assertion] of assertions.entries()) {
     const assertId =
       (assertion.assertionId && `${assertion.assertionId} assertion`) || `assertion #${index + 1}`;
-    if (!assertion.subject) {
-      throw new Error(`${assertId}: 'subject' is required`);
-    }
 
-    const subjects: string[] = Array.isArray(assertion.subject)
-      ? assertion.subject
-      : [assertion.subject];
-
-    const assertsToApply: AssertToApply[] = Object.keys(asserts)
-      .filter((assertName: string) => assertion[assertName] !== undefined)
-      .map((assertName: string) => {
-        return {
-          name: assertName,
-          conditions: assertion[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.property) {
-      throw new Error(
-        `${shouldRunOnValues.name} can't be used on all keys. Please provide a single property.`
-      );
+    if (!isString(assertion.subject.type)) {
+      throw new Error(`${assertId}: 'type' (String) is required`);
     }
 
-    if (shouldRunOnKeys && assertion.property) {
-      throw new Error(
-        `${shouldRunOnKeys.name} can't be used on a single property. Please use 'property'.`
-      );
-    }
-
-    for (const subject of subjects) {
-      const subjectVisitor = buildSubjectVisitor(assertId, assertion, assertsToApply);
-      const visitorObject = buildVisitorObject(subject, assertion.context, subjectVisitor);
-      visitors.push(visitorObject);
-    }
+    const subjectVisitor = buildSubjectVisitor(assertId, assertion);
+    const visitorObject = buildVisitorObject(assertion, subjectVisitor);
+    visitors.push(visitorObject);
   }
 
   return visitors;

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/common/spec.ts

@@ -158,6 +158,13 @@ export const OasSpec: Oas3Rule | Oas2Rule = () => {
             });
           }
         }
+
+        if (propName === 'nullable' && !node.type) {
+          report({
+            message: 'The `type` field must be defined when the `nullable` field is used.',
+            location: location.child([propName]),
+          });
+        }
       }
     },
   };

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/__tests__/no-invalid-media-type-examples.test.ts

@@ -438,4 +438,36 @@ describe('no-invalid-media-type-examples', () => {
       ]
     `);
   });
+
+  it('should not report if allOf used with discriminator', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          /pet:
+            get:
+              responses:
+                '200':
+                  content:
+                    application/json:
+                      schema:
+                        discriminator:
+                          propertyName: powerSource
+                          mapping: {}
+                        allOf: []
+                      examples:
+                        first:
+                          value: {}
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'no-invalid-media-type-examples': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
 });

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,