@redocly/openapi-core 1.0.0-beta.110 → 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/common/no-ambiguous-paths.ts

@@ -5,7 +5,7 @@ import { Oas2Paths } from '../../typings/swagger';
 
 export const NoAmbiguousPaths: Oas3Rule | Oas2Rule = () => {
   return {
-    PathsMap(pathMap: Oas3Paths | Oas2Paths, { report, location }: UserContext) {
+    Paths(pathMap: Oas3Paths | Oas2Paths, { report, location }: UserContext) {
       const seenPaths: string[] = [];
 
       for (const currentPath of Object.keys(pathMap)) {

package/src/rules/common/no-identical-paths.ts

@@ -5,18 +5,18 @@ import { Oas2Paths } from '../../typings/swagger';
 
 export const NoIdenticalPaths: Oas3Rule | Oas2Rule = () => {
   return {
-    PathsMap(pathMap: Oas3Paths | Oas2Paths, { report, location }: UserContext) {
-      const pathsMap = new Map<string, string>();
+    Paths(pathMap: Oas3Paths | Oas2Paths, { report, location }: UserContext) {
+      const Paths = new Map<string, string>();
       for (const pathName of Object.keys(pathMap)) {
         const id = pathName.replace(/{.+?}/g, '{VARIABLE}');
-        const existingSamePath = pathsMap.get(id);
+        const existingSamePath = Paths.get(id);
         if (existingSamePath) {
           report({
             message: `The path already exists which differs only by path parameter name(s): \`${existingSamePath}\` and \`${pathName}\`.`,
             location: location.child([pathName]).key(),
           });
         } else {
-          pathsMap.set(id, pathName);
+          Paths.set(id, pathName);
         }
       }
     },

package/src/rules/common/operation-2xx-response.ts

@@ -3,8 +3,8 @@ import { UserContext } from '../../walk';
 
 export const Operation2xxResponse: Oas3Rule | Oas2Rule = () => {
   return {
-    ResponsesMap(responses: Record<string, object>, { report }: UserContext) {
-      const codes = Object.keys(responses);
+    Responses(responses: Record<string, object>, { report }: UserContext) {
+      const codes = Object.keys(responses || {});
       if (!codes.some((code) => code === 'default' || /2[Xx0-9]{2}/.test(code))) {
         report({
           message: 'Operation must have at least one `2XX` response.',

package/src/rules/common/operation-4xx-response.ts

@@ -3,8 +3,8 @@ import { UserContext } from '../../walk';
 
 export const Operation4xxResponse: Oas3Rule | Oas2Rule = () => {
   return {
-    ResponsesMap(responses: Record<string, object>, { report }: UserContext) {
-      const codes = Object.keys(responses);
+    Responses(responses: Record<string, object>, { report }: UserContext) {
+      const codes = Object.keys(responses || {});
 
       if (!codes.some((code) => /4[Xx0-9]{2}/.test(code))) {
         report({

package/src/rules/common/path-not-include-query.ts

@@ -3,7 +3,7 @@ import { UserContext } from '../../walk';
 
 export const PathNotIncludeQuery: Oas3Rule | Oas2Rule = () => {
   return {
-    PathsMap: {
+    Paths: {
       PathItem(_operation: object, { report, key }: UserContext) {
         if (key.toString().includes('?')) {
           report({

package/src/rules/common/path-params-defined.ts

@@ -9,6 +9,7 @@ export const PathParamsDefined: Oas3Rule | Oas2Rule = () => {
   let pathTemplateParams: Set<string>;
   let definedPathParams: Set<string>;
   let currentPath: string;
+  let definedOperationParams: Set<string>;
 
   return {
     PathItem: {
@@ -31,9 +32,15 @@ export const PathParamsDefined: Oas3Rule | Oas2Rule = () => {
         }
       },
       Operation: {
+        enter() {
+          definedOperationParams = new Set();
+        },
         leave(_op: object, { report, location }: UserContext) {
           for (const templateParam of Array.from(pathTemplateParams.keys())) {
-            if (!definedPathParams.has(templateParam)) {
+            if (
+              !definedOperationParams.has(templateParam) &&
+              !definedPathParams.has(templateParam)
+            ) {
               report({
                 message: `The operation does not define the path parameter \`{${templateParam}}\` expected by path \`${currentPath}\`.`,
                 location: location.child(['parameters']).key(), // report on operation
@@ -43,7 +50,7 @@ export const PathParamsDefined: Oas3Rule | Oas2Rule = () => {
         },
         Parameter(parameter: Oas2Parameter | Oas3Parameter, { report, location }: UserContext) {
           if (parameter.in === 'path' && parameter.name) {
-            definedPathParams.add(parameter.name);
+            definedOperationParams.add(parameter.name);
             if (!pathTemplateParams.has(parameter.name)) {
               report({
                 message: `Path parameter \`${parameter.name}\` is not used in the path \`${currentPath}\`.`,

package/src/rules/common/response-contains-header.ts

@@ -16,7 +16,12 @@ export const ResponseContainsHeader: Oas3Rule | Oas2Rule = (options) => {
             names[getMatchingStatusCodeRange(key).toLowerCase()] ||
             [];
           for (const expectedHeader of expectedHeaders) {
-            if (!response.headers?.[expectedHeader]) {
+            if (
+              !response?.headers ||
+              !Object.keys(response?.headers).some(
+                (header) => header.toLowerCase() === expectedHeader.toLowerCase()
+              )
+            ) {
               report({
                 message: `Response object must contain a "${expectedHeader}" header.`,
                 location: location.child('headers').key(),

package/src/rules/common/security-defined.ts

@@ -13,10 +13,11 @@ export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
     }
   >();
 
+  const operationsWithoutSecurity: Location[] = [];
   let eachOperationHasSecurity: boolean = true;
 
   return {
-    DefinitionRoot: {
+    Root: {
       leave(root: Oas2Definition | Oas3Definition, { report }: UserContext) {
         for (const [name, scheme] of referencedSchemes.entries()) {
           if (scheme.defined) continue;
@@ -31,9 +32,12 @@ export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
         if (root.security || eachOperationHasSecurity) {
           return;
         } else {
-          report({
-            message: `Every API should have security defined on the root level or for each operation.`,
-          });
+          for (const operationLocation of operationsWithoutSecurity) {
+            report({
+              message: `Every operation should have security defined on it or on the root level.`,
+              location: operationLocation.key(),
+            });
+          }
         }
       },
     },
@@ -51,9 +55,10 @@ export const SecurityDefined: Oas3Rule | Oas2Rule = () => {
         }
       }
     },
-    Operation(operation: Oas2Operation | Oas3Operation) {
+    Operation(operation: Oas2Operation | Oas3Operation, { location }: UserContext) {
       if (!operation?.security) {
         eachOperationHasSecurity = false;
+        operationsWithoutSecurity.push(location);
       }
     },
   };

package/src/rules/common/spec.ts

@@ -1,8 +1,9 @@
 import type { Oas3Rule, Oas2Rule } from '../../visitors';
 import { isNamedType } from '../../types';
-import { oasTypeOf, matchesJsonSchemaType, getSuggest } from '../utils';
+import { oasTypeOf, matchesJsonSchemaType, getSuggest, validateSchemaEnumType } from '../utils';
 import { isRef } from '../../ref-utils';
 import { isPlainObject } from '../../utils';
+import { UserContext } from '../../walk';
 
 export const OasSpec: Oas3Rule | Oas2Rule = () => {
   return {
@@ -114,17 +115,20 @@ export const OasSpec: Oas3Rule | Oas2Rule = () => {
           propValue = resolve(propValue).node;
         }
 
-        if (propSchema.enum) {
-          if (!propSchema.enum.includes(propValue)) {
-            report({
-              location: propLocation,
-              message: `\`${propName}\` can be one of the following only: ${propSchema.enum
-                .map((i) => `"${i}"`)
-                .join(', ')}.`,
-              from: refLocation,
-              suggest: getSuggest(propValue, propSchema.enum),
-            });
+        if (propSchema.items && propSchema.items?.enum && Array.isArray(propValue)) {
+          for (let i = 0; i < propValue.length; i++) {
+            validateSchemaEnumType(propSchema.items?.enum, propValue[i], propName, refLocation, {
+              report,
+              location: location.child([propName, i]),
+            } as UserContext);
           }
+        }
+
+        if (propSchema.enum) {
+          validateSchemaEnumType(propSchema.enum, propValue, propName, refLocation, {
+            report,
+            location: location.child([propName]),
+          } as UserContext);
         } else if (propSchema.type && !matchesJsonSchemaType(propValue, propSchema.type, false)) {
           report({
             message: `Expected type \`${propSchema.type}\` but got \`${propValueType}\`.`,

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,