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

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

@@ -1,5 +1,6 @@
+import { AssertResult, CustomFunction } from 'core/src/config/types';
 import { Location } from '../../../ref-utils';
-import { isString as runOnValue } from '../../../utils';
+import { isString as runOnValue, isTruthy } from '../../../utils';
 import {
   OrderOptions,
   OrderDirection,
@@ -8,10 +9,9 @@ import {
   regexFromString,
 } from './utils';
 
-type AssertResult = { isValid: boolean; location?: Location };
 type Asserts = Record<
   string,
-  (value: any, condition: any, baseLocation: Location, rawValue?: any) => AssertResult
+  (value: any, condition: any, baseLocation: Location, rawValue?: any) => AssertResult[]
 >;
 
 export const runOnKeysSet = new Set([
@@ -43,57 +43,80 @@ export const runOnValuesSet = new Set([
 
 export const asserts: Asserts = {
   pattern: (value: string | string[], condition: string, baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
+    if (typeof value === 'undefined') return []; // property doesn't exist, no need to lint it with this assert
     const values = runOnValue(value) ? [value] : value;
     const regx = regexFromString(condition);
-    for (const _val of values) {
-      if (!regx?.test(_val)) {
-        return { isValid: false, location: runOnValue(value) ? baseLocation : baseLocation.key() };
-      }
-    }
-    return { isValid: true };
+
+    return values
+      .map(
+        (_val) =>
+          !regx?.test(_val) && {
+            message: `"${_val}" should match a regex ${condition}`,
+            location: runOnValue(value) ? baseLocation : baseLocation.key(),
+          }
+      )
+      .filter(isTruthy);
   },
   enum: (value: string | string[], condition: string[], baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
+    if (typeof value === 'undefined') return []; // property doesn't exist, no need to lint it with this assert
     const values = runOnValue(value) ? [value] : value;
-    for (const _val of values) {
-      if (!condition.includes(_val)) {
-        return {
-          isValid: false,
-          location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
-        };
-      }
-    }
-    return { isValid: true };
+    return values
+      .map(
+        (_val) =>
+          !condition.includes(_val) && {
+            message: `"${_val}" should be one of the predefined values`,
+            location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
+          }
+      )
+      .filter(isTruthy);
   },
   defined: (value: string | undefined, condition: boolean = true, baseLocation: Location) => {
     const isDefined = typeof value !== 'undefined';
-    return { isValid: condition ? isDefined : !isDefined, location: baseLocation };
+    const isValid = condition ? isDefined : !isDefined;
+    return isValid
+      ? []
+      : [
+          {
+            message: condition ? `Should be defined` : 'Should be not defined',
+            location: baseLocation,
+          },
+        ];
   },
   required: (value: string[], keys: string[], baseLocation: Location) => {
-    for (const requiredKey of keys) {
-      if (!value.includes(requiredKey)) {
-        return { isValid: false, location: baseLocation.key() };
-      }
-    }
-    return { isValid: true };
+    return keys
+      .map(
+        (requiredKey) =>
+          !value.includes(requiredKey) && {
+            message: `${requiredKey} is required`,
+            location: baseLocation.key(),
+          }
+      )
+      .filter(isTruthy);
   },
   disallowed: (value: string | string[], condition: string[], baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
+    if (typeof value === 'undefined') return []; // property doesn't exist, no need to lint it with this assert
     const values = runOnValue(value) ? [value] : value;
-    for (const _val of values) {
-      if (condition.includes(_val)) {
-        return {
-          isValid: false,
-          location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
-        };
-      }
-    }
-    return { isValid: true };
+    return values
+      .map(
+        (_val) =>
+          condition.includes(_val) && {
+            message: `"${_val}" is disallowed`,
+            location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
+          }
+      )
+      .filter(isTruthy);
   },
   undefined: (value: any, condition: boolean = true, baseLocation: Location) => {
     const isUndefined = typeof value === 'undefined';
-    return { isValid: condition ? isUndefined : !isUndefined, location: baseLocation };
+    const isValid = condition ? isUndefined : !isUndefined;
+    return isValid
+      ? []
+      : [
+          {
+            message: condition ? `Should not be defined` : 'Should be defined',
+            location: baseLocation,
+          },
+        ];
   },
   nonEmpty: (
     value: string | undefined | null,
@@ -101,85 +124,120 @@ export const asserts: Asserts = {
     baseLocation: Location
   ) => {
     const isEmpty = typeof value === 'undefined' || value === null || value === '';
-    return { isValid: condition ? !isEmpty : isEmpty, location: baseLocation };
+    const isValid = condition ? !isEmpty : isEmpty;
+    return isValid
+      ? []
+      : [
+          {
+            message: condition ? `Should not be empty` : 'Should be empty',
+            location: baseLocation,
+          },
+        ];
   },
   minLength: (value: string | any[], condition: number, baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
-    return { isValid: value.length >= condition, location: baseLocation };
+    if (typeof value === 'undefined' || value.length >= condition) return []; // property doesn't exist, no need to lint it with this assert
+    return [{ message: `Should have at least ${condition} characters`, location: baseLocation }];
   },
   maxLength: (value: string | any[], condition: number, baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
-    return { isValid: value.length <= condition, location: baseLocation };
+    if (typeof value === 'undefined' || value.length <= condition) return []; // property doesn't exist, no need to lint it with this assert
+    return [{ message: `Should have at most ${condition} characters`, location: baseLocation }];
   },
   casing: (value: string | string[], condition: string, baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
+    if (typeof value === 'undefined') return []; // property doesn't exist, no need to lint it with this assert
     const values: string[] = runOnValue(value) ? [value] : value;
-    for (const _val of values) {
-      let matchCase = false;
-      switch (condition) {
-        case 'camelCase':
-          matchCase = !!_val.match(/^[a-z][a-zA-Z0-9]+$/g);
-          break;
-        case 'kebab-case':
-          matchCase = !!_val.match(/^([a-z][a-z0-9]*)(-[a-z0-9]+)*$/g);
-          break;
-        case 'snake_case':
-          matchCase = !!_val.match(/^([a-z][a-z0-9]*)(_[a-z0-9]+)*$/g);
-          break;
-        case 'PascalCase':
-          matchCase = !!_val.match(/^[A-Z][a-zA-Z0-9]+$/g);
-          break;
-        case 'MACRO_CASE':
-          matchCase = !!_val.match(/^([A-Z][A-Z0-9]*)(_[A-Z0-9]+)*$/g);
-          break;
-        case 'COBOL-CASE':
-          matchCase = !!_val.match(/^([A-Z][A-Z0-9]*)(-[A-Z0-9]+)*$/g);
-          break;
-        case 'flatcase':
-          matchCase = !!_val.match(/^[a-z][a-z0-9]+$/g);
-          break;
-      }
-      if (!matchCase) {
-        return {
-          isValid: false,
-          location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
-        };
-      }
-    }
-    return { isValid: true };
+    const casingRegexes: Record<string, RegExp> = {
+      camelCase: /^[a-z][a-zA-Z0-9]+$/g,
+      'kebab-case': /^([a-z][a-z0-9]*)(-[a-z0-9]+)*$/g,
+      snake_case: /^([a-z][a-z0-9]*)(_[a-z0-9]+)*$/g,
+      PascalCase: /^[A-Z][a-zA-Z0-9]+$/g,
+      MACRO_CASE: /^([A-Z][A-Z0-9]*)(_[A-Z0-9]+)*$/g,
+      'COBOL-CASE': /^([A-Z][A-Z0-9]*)(-[A-Z0-9]+)*$/g,
+      flatcase: /^[a-z][a-z0-9]+$/g,
+    };
+    return values
+      .map(
+        (_val) =>
+          !_val.match(casingRegexes[condition]) && {
+            message: `"${_val}" should use ${condition}`,
+            location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
+          }
+      )
+      .filter(isTruthy);
   },
   sortOrder: (value: any[], condition: OrderOptions | OrderDirection, baseLocation: Location) => {
-    if (typeof value === 'undefined') return { isValid: true };
-    return { isValid: isOrdered(value, condition), location: baseLocation };
+    if (typeof value === 'undefined' || isOrdered(value, condition)) return [];
+    const direction = (condition as OrderOptions).direction || (condition as OrderDirection);
+    const property = (condition as OrderOptions).property;
+    return [
+      {
+        message: `Should be sorted in ${
+          direction === 'asc' ? 'an ascending' : 'a descending'
+        } order${property ? ` by property ${property}` : ''}`,
+        location: baseLocation,
+      },
+    ];
   },
   mutuallyExclusive: (value: string[], condition: string[], baseLocation: Location) => {
-    return { isValid: getIntersectionLength(value, condition) < 2, location: baseLocation.key() };
+    if (getIntersectionLength(value, condition) < 2) return [];
+    return [
+      {
+        message: `${condition.join(', ')} keys should be mutually exclusive`,
+        location: baseLocation.key(),
+      },
+    ];
   },
   mutuallyRequired: (value: string[], condition: string[], baseLocation: Location) => {
-    return {
-      isValid:
-        getIntersectionLength(value, condition) > 0
-          ? getIntersectionLength(value, condition) === condition.length
-          : true,
-      location: baseLocation.key(),
-    };
+    const isValid =
+      getIntersectionLength(value, condition) > 0
+        ? getIntersectionLength(value, condition) === condition.length
+        : true;
+    return isValid
+      ? []
+      : [
+          {
+            message: `Properties ${condition.join(', ')} are mutually required`,
+            location: baseLocation.key(),
+          },
+        ];
   },
   requireAny: (value: string[], condition: string[], baseLocation: Location) => {
-    return { isValid: getIntersectionLength(value, condition) >= 1, location: baseLocation.key() };
+    return getIntersectionLength(value, condition) >= 1
+      ? []
+      : [
+          {
+            message: `Should have any of ${condition.join(', ')}`,
+            location: baseLocation.key(),
+          },
+        ];
   },
   ref: (_value: any, condition: string | boolean, baseLocation, rawValue: any) => {
-    if (typeof rawValue === 'undefined') return { isValid: true }; // property doesn't exist, no need to lint it with this assert
+    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') {
-      return {
-        isValid: condition ? hasRef : !hasRef,
-        location: hasRef ? baseLocation : baseLocation.key(),
-      };
+      const isValid = condition ? hasRef : !hasRef;
+      return isValid
+        ? []
+        : [
+            {
+              message: condition ? `should use $ref` : 'should not use $ref',
+              location: hasRef ? baseLocation : baseLocation.key(),
+            },
+          ];
     }
     const regex = regexFromString(condition);
-    return {
-      isValid: hasRef && regex?.test(rawValue['$ref']),
-      location: hasRef ? baseLocation : baseLocation.key(),
-    };
+    const isValid = hasRef && regex?.test(rawValue['$ref']);
+    return isValid
+      ? []
+      : [
+          {
+            message: `$ref value should match ${condition}`,
+            location: hasRef ? baseLocation : baseLocation.key(),
+          },
+        ];
   },
 };
+
+export function buildAssertCustomFunction(fn: CustomFunction) {
+  return (value: string[], options: any, baseLocation: Location) =>
+    fn.call(null, value, options, baseLocation);
+}

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

@@ -7,7 +7,7 @@ export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
 
   // 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/master/packages/core/src/config/config.ts#L311
+  // 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(
@@ -17,7 +17,6 @@ export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
   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`);
     }
@@ -30,12 +29,8 @@ export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
       .filter((assertName: string) => assertion[assertName] !== undefined)
       .map((assertName: string) => {
         return {
-          assertId,
           name: assertName,
           conditions: assertion[assertName],
-          message: assertion.message,
-          severity: assertion.severity || 'error',
-          suggest: assertion.suggest || [],
           runsOnKeys: runOnKeysSet.has(assertName),
           runsOnValues: runOnValuesSet.has(assertName),
         };
@@ -61,11 +56,7 @@ export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
     }
 
     for (const subject of subjects) {
-      const subjectVisitor = buildSubjectVisitor(
-        assertion.property,
-        assertsToApply,
-        assertion.context
-      );
+      const subjectVisitor = buildSubjectVisitor(assertId, assertion, assertsToApply);
       const visitorObject = buildVisitorObject(subject, assertion.context, subjectVisitor);
       visitors.push(visitorObject);
     }

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

@@ -1,5 +1,7 @@
+import type { AssertResult, RuleSeverity } from '../../../config';
+import { colorize } from '../../../logger';
 import { isRef, Location } from '../../../ref-utils';
-import { Problem, ProblemSeverity, UserContext } from '../../../walk';
+import { UserContext } from '../../../walk';
 import { asserts } from './asserts';
 
 export type OrderDirection = 'asc' | 'desc';
@@ -9,13 +11,18 @@ 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;
-  assertId?: string;
   conditions: any;
-  message?: string;
-  severity?: ProblemSeverity;
-  suggest?: string[];
   runsOnKeys: boolean;
   runsOnValues: boolean;
 };
@@ -73,19 +80,20 @@ export function buildVisitorObject(
 }
 
 export function buildSubjectVisitor(
-  properties: string | string[],
-  asserts: AssertToApply[],
-  context?: Record<string, any>[]
+  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 (context) {
-      const lastContextNode = context[context.length - 1];
+    if (assertion.context) {
+      const lastContextNode = assertion.context[assertion.context.length - 1];
       if (lastContextNode.type === type.name) {
         const matchParentKeys = lastContextNode.matchParentKeys;
         const excludeParentKeys = lastContextNode.excludeParentKeys;
@@ -103,34 +111,66 @@ export function buildSubjectVisitor(
       properties = Array.isArray(properties) ? properties : [properties];
     }
 
+    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];
-          runAssertion({
-            values: value,
-            rawValues: rawNode[property],
-            assert,
-            location: currentLocation.child(property),
-            report,
-          });
+          assertResults.push(
+            runAssertion({
+              values: value,
+              rawValues: rawNode[property],
+              assert,
+              location: currentLocation.child(property),
+            })
+          );
         }
       } else {
         const value = assert.name === 'ref' ? rawNode : Object.keys(node);
-        runAssertion({
-          values: Object.keys(node),
-          rawValues: value,
-          assert,
-          location: currentLocation,
-          report,
-        });
+        assertResults.push(
+          runAssertion({
+            values: Object.keys(node),
+            rawValues: value,
+            assert,
+            location: currentLocation,
+          })
+        );
       }
     }
+
+    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,
+      });
+    }
   };
 }
 
+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;
@@ -170,20 +210,10 @@ type RunAssertionParams = {
   rawValues: any;
   assert: AssertToApply;
   location: Location;
-  report: (problem: Problem) => void;
 };
 
-function runAssertion({ values, rawValues, assert, location, report }: RunAssertionParams) {
-  const lintResult = asserts[assert.name](values, assert.conditions, location, rawValues);
-  if (!lintResult.isValid) {
-    report({
-      message: assert.message || `The ${assert.assertId} doesn't meet required conditions`,
-      location: lintResult.location || location,
-      forceSeverity: assert.severity,
-      suggest: assert.suggest,
-      ruleId: assert.assertId,
-    });
-  }
+function runAssertion({ values, rawValues, assert, location }: RunAssertionParams): AssertResult[] {
+  return asserts[assert.name](values, assert.conditions, location, rawValues);
 }
 
 export function regexFromString(input: string): RegExp | null {

package/src/rules/oas3/__tests__/no-invalid-media-type-examples.test.ts

@@ -128,7 +128,7 @@ describe('no-invalid-media-type-examples', () => {
               "source": "foobar.yaml",
             },
           ],
-          "message": "Example value must conform to the schema: must NOT have additional properties \`c\`.",
+          "message": "Example value must conform to the schema: must NOT have unevaluated properties \`c\`.",
           "ruleId": "no-invalid-media-type-examples",
           "severity": "error",
           "suggest": Array [],
@@ -137,7 +137,7 @@ describe('no-invalid-media-type-examples', () => {
     `);
   });
 
-  it('should not on invalid example with allowAdditionalProperties', async () => {
+  it('should not report on valid example with allowAdditionalProperties', async () => {
     const document = parseYamlToDocument(
       outdent`
         openapi: 3.0.0
@@ -177,6 +177,55 @@ describe('no-invalid-media-type-examples', () => {
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
   });
 
+  it('should not report on valid example with allowAdditionalProperties and allOf and $ref', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        components:
+          schemas:
+            C:
+              properties:
+                c:
+                  type: string
+        paths:
+          /pet:
+            get:
+              responses:
+                200:
+                  content:
+                    application/json:
+                      example:
+                        a: "string"
+                        b: 13
+                        c: "string"
+                      schema:
+                        type: object
+                        allOf:
+                          - $ref: '#/components/schemas/C'
+                        properties:
+                          a:
+                            type: string
+                          b:
+                            type: number
+
+      `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'no-invalid-media-type-examples': {
+          severity: 'error',
+          allowAdditionalProperties: false,
+        },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
+
   it('should not on invalid examples', async () => {
     const document = parseYamlToDocument(
       outdent`

package/src/rules/utils.ts

@@ -109,7 +109,8 @@ export function validateExample(
           message: `Example value must conform to the schema: ${error.message}.`,
           location: {
             ...new Location(dataLoc.source, error.instancePath),
-            reportOnKey: error.keyword === 'additionalProperties',
+            reportOnKey:
+              error.keyword === 'unevaluatedProperties' || error.keyword === 'additionalProperties',
           },
           from: location,
           suggest: error.suggest,

package/src/types/redocly-yaml.ts

@@ -165,6 +165,12 @@ const ConfigRoot: NodeType = {
         doNotResolveExamples: { type: 'boolean' },
       },
     },
+    files: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+    },
   },
 };
 
@@ -187,6 +193,12 @@ const ConfigApisProperties: NodeType = {
     ...ConfigStyleguide.properties,
     'features.openapi': 'ConfigReferenceDocs',
     'features.mockServer': 'ConfigMockServer',
+    files: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+    },
   },
   required: ['root'],
 };
@@ -275,6 +287,10 @@ const Assert: NodeType = {
     ref: (value: string | boolean) =>
       typeof value === 'string' ? { type: 'string' } : { type: 'boolean' },
   },
+  additionalProperties: (_value: unknown, key: string) => {
+    if (/^\w+\/\w+$/.test(key)) return { type: 'object' };
+    return;
+  },
   required: ['subject'],
 };