@redocly/openapi-core 1.0.0-rc.3 → 1.0.1

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

@@ -0,0 +1,100 @@
+import { Assertions } from '../.';
+
+const opts = {
+  '0': {
+    subject: {
+      type: 'Operation',
+      property: 'summary',
+    },
+    description: 'example warn text',
+    severity: 'warn',
+    assertions: { pattern: '/example/' },
+  },
+  '1': {
+    subject: {
+      type: 'PathItem',
+    },
+    where: [
+      {
+        subject: { type: 'Operation', filterInParentKeys: ['post'], property: 'responses' },
+        assertions: { defined: true },
+      },
+    ],
+    description: 'example warn text',
+    severity: 'warn',
+    assertions: { mutuallyExclusive: ['summary', 'security'] },
+  },
+  '2': {
+    subject: { type: 'PathItem', property: 'tags' },
+    where: [
+      { subject: { type: 'Operation', property: 'responses' }, assertions: { defined: true } },
+    ],
+    description: 'example warn text',
+    severity: 'warn',
+    assertions: { sortOrder: 'desc' },
+  },
+  '3': {
+    subject: { type: 'Foo', property: 'test' },
+    where: [
+      { subject: { type: 'Bar' }, assertions: {} },
+      { subject: { type: 'Baz' }, assertions: {} },
+    ],
+    description: 'example warn text',
+    severity: 'warn',
+    assertions: { sortOrder: 'desc' },
+  },
+  '4': {
+    subject: {
+      type: 'any',
+      property: 'description',
+    },
+    description: 'example warn text',
+    severity: 'warn',
+    assertions: { notPattern: '/example/' },
+  },
+};
+
+describe('Oas3 assertions', () => {
+  it('should return the right visitor structure', () => {
+    const visitors = Assertions(opts as any);
+    expect(visitors).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "Operation": Object {
+            "enter": [Function],
+          },
+        },
+        Object {
+          "Operation": Object {
+            "PathItem": Object {
+              "enter": [Function],
+            },
+            "skip": [Function],
+          },
+        },
+        Object {
+          "Operation": Object {
+            "PathItem": Object {
+              "enter": [Function],
+            },
+            "skip": [Function],
+          },
+        },
+        Object {
+          "Bar": Object {
+            "Baz": Object {
+              "Foo": Object {
+                "enter": [Function],
+              },
+            },
+          },
+        },
+        Object {
+          "any": Object {
+            "enter": [Function],
+          },
+        },
+      ]
+    `);
+  });
+});

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

@@ -0,0 +1,236 @@
+import { Assertion, AssertionDefinition } from '..';
+import { AssertionContext } from '../../../../config';
+import { Location } from '../../../../ref-utils';
+import { Source } from '../../../../resolve';
+import { isOrdered, buildVisitorObject, getIntersectionLength, runAssertion } from '../utils';
+
+describe('Oas3 assertions', () => {
+  describe('Utils', () => {
+    describe('getCounts', () => {
+      it('should return the right counts', () => {
+        const arr = ['foo', 'bar', 'baz'];
+        expect(getIntersectionLength(arr, ['foo'])).toBe(1);
+        expect(getIntersectionLength(arr, ['foo', 'bar', 'baz'])).toBe(3);
+        expect(getIntersectionLength(arr, ['foo', 'test', 'baz'])).toBe(2);
+        expect(getIntersectionLength(arr, ['example', 'test'])).toBe(0);
+      });
+    });
+
+    describe('isOrdered', () => {
+      it('should say if array is ordered or not in specific direction', () => {
+        expect(isOrdered(['example', 'foo', 'test'], 'asc')).toBeTruthy();
+        expect(isOrdered(['example'], 'asc')).toBeTruthy();
+        expect(isOrdered(['test', 'foo', 'example'], 'desc')).toBeTruthy();
+        expect(isOrdered(['example'], 'desc')).toBeTruthy();
+        expect(isOrdered(['example', 'test', 'foo'], 'asc')).toBeFalsy();
+        expect(isOrdered(['example', 'foo', 'test'], 'desc')).toBeFalsy();
+      });
+    });
+
+    describe('buildVisitorObject', () => {
+      it('should return a consistent visitor structure', () => {
+        const where: AssertionDefinition[] = [
+          {
+            subject: {
+              type: 'Foo',
+              filterInParentKeys: ['test'],
+            },
+            assertions: {},
+          },
+          {
+            subject: {
+              type: 'Bar',
+              filterInParentKeys: ['test'],
+            },
+            assertions: {},
+          },
+          {
+            subject: {
+              type: 'Roof',
+              filterInParentKeys: ['test'],
+            },
+            assertions: {},
+          },
+        ] as AssertionDefinition[];
+
+        const visitors = buildVisitorObject(
+          { subject: { type: 'Bar' }, where, assertions: {} } as Assertion,
+          () => {}
+        );
+
+        expect(visitors).toMatchInlineSnapshot(`
+          Object {
+            "Foo": Object {
+              "Bar": Object {
+                "Roof": Object {
+                  "Bar": Object {
+                    "enter": [Function],
+                  },
+                  "skip": [Function],
+                },
+                "skip": [Function],
+              },
+              "skip": [Function],
+            },
+          }
+        `);
+      });
+
+      it('should return the right visitor structure', () => {
+        const where = [
+          {
+            subject: {
+              type: 'Operation',
+              filterInParentKeys: ['put'],
+            },
+            assertions: {},
+          },
+          {
+            subject: {
+              type: 'Responses',
+              filterInParentKeys: [201, 200],
+            },
+            assertions: {},
+          },
+        ];
+
+        const visitors = buildVisitorObject(
+          { subject: { type: 'MediaTypesMap' }, where, assertions: {} } as Assertion,
+          () => {}
+        );
+
+        expect(visitors).toMatchInlineSnapshot(`
+          Object {
+            "Operation": Object {
+              "Responses": Object {
+                "MediaTypesMap": Object {
+                  "enter": [Function],
+                },
+                "skip": [Function],
+              },
+              "skip": [Function],
+            },
+          }
+        `);
+      });
+    });
+
+    describe('runAssertion', () => {
+      const baseLocation = new Location(jest.fn() as any as Source, 'pointer');
+      const rawLocation = new Location(jest.fn() as any as Source, 'raw-pointer');
+      // { $ref: 'text' }, true, {...assertionProperties, rawValue:  { $ref: 'text' }}
+
+      const ctxStub = {
+        location: baseLocation,
+        node: {
+          property: 'test',
+        },
+        rawNode: {
+          property: 'test',
+        },
+        rawLocation: rawLocation,
+      } as AssertionContext;
+
+      it('should catch error cause property should be not defined with assertionProperty', () => {
+        const result = runAssertion({
+          assert: {
+            name: 'defined',
+            conditions: false,
+            runsOnKeys: true,
+            runsOnValues: false,
+          },
+          ctx: ctxStub,
+          assertionProperty: 'property',
+        });
+
+        const expectedLocation = new Location(jest.fn() as any as Source, 'pointer/property');
+
+        expect(JSON.stringify(result)).toEqual(
+          JSON.stringify([
+            {
+              message: 'Should be not defined',
+              location: expectedLocation,
+            },
+          ])
+        );
+      });
+
+      it('should pass cause property defined', () => {
+        const result = runAssertion({
+          assert: {
+            name: 'defined',
+            conditions: true,
+            runsOnKeys: true,
+            runsOnValues: false,
+          },
+          ctx: ctxStub,
+          assertionProperty: 'property',
+        });
+
+        expect(result).toEqual([]);
+      });
+
+      it('should failure cause property does not passed', () => {
+        const result = runAssertion({
+          assert: {
+            name: 'defined',
+            conditions: false,
+            runsOnKeys: true,
+            runsOnValues: false,
+          },
+          ctx: ctxStub,
+        });
+
+        expect(result).toEqual([
+          {
+            message: 'Should be not defined',
+            location: baseLocation,
+          },
+        ]);
+      });
+
+      it('should pass with ref assertion cause it is defined', () => {
+        const result = runAssertion({
+          assert: {
+            name: 'ref',
+            conditions: true,
+            runsOnKeys: true,
+            runsOnValues: false,
+          },
+          ctx: {
+            ...ctxStub,
+            rawNode: {
+              $ref: 'test',
+            },
+          },
+        });
+
+        expect(result).toEqual([]);
+      });
+
+      it('should failure with ref assertion cause it is defined', () => {
+        const result = runAssertion({
+          assert: {
+            name: 'ref',
+            conditions: false,
+            runsOnKeys: true,
+            runsOnValues: false,
+          },
+          ctx: {
+            ...ctxStub,
+            rawNode: {
+              $ref: 'test',
+            },
+          },
+        });
+
+        expect(result).toEqual([
+          {
+            message: 'should not use $ref',
+            location: rawLocation,
+          },
+        ]);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,357 @@
+import { AssertionContext, AssertResult, CustomFunction } from 'core/src/config/types';
+import { Location } from '../../../ref-utils';
+import { isPlainObject, isString as runOnValue, isTruthy } from '../../../utils';
+import {
+  OrderOptions,
+  OrderDirection,
+  isOrdered,
+  getIntersectionLength,
+  regexFromString,
+} from './utils';
+
+export type AssertionFnContext = AssertionContext & { baseLocation: Location; rawValue?: any };
+
+export type AssertionFn = (value: any, condition: any, ctx: AssertionFnContext) => AssertResult[];
+
+export type Asserts = {
+  pattern: AssertionFn;
+  notPattern: 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',
+  'pattern',
+  'notPattern',
+  'minLength',
+  'maxLength',
+  'casing',
+  'sortOrder',
+  'disallowed',
+  'required',
+  'requireAny',
+  'ref',
+  'const',
+  'defined', // In case if `property` for assertions is not added
+]);
+export const runOnValuesSet = new Set<keyof Asserts>([
+  'pattern',
+  'notPattern',
+  'enum',
+  'defined',
+  'undefined',
+  'nonEmpty',
+  'minLength',
+  'maxLength',
+  'casing',
+  'sortOrder',
+  'ref',
+  'const',
+]);
+
+export const asserts: Asserts = {
+  pattern: (value: string | string[], condition: string, { baseLocation }: AssertionFnContext) => {
+    if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
+    const values = Array.isArray(value) ? value : [value];
+    const regex = regexFromString(condition);
+
+    return values
+      .map(
+        (_val) =>
+          !regex?.test(_val) && {
+            message: `"${_val}" should match a regex ${condition}`,
+            location: runOnValue(value) ? baseLocation : baseLocation.key(),
+          }
+      )
+      .filter(isTruthy);
+  },
+  notPattern: (
+    value: string | string[],
+    condition: string,
+    { baseLocation }: AssertionFnContext
+  ) => {
+    if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
+    const values = Array.isArray(value) ? value : [value];
+    const regex = regexFromString(condition);
+
+    return values
+      .map(
+        (_val) =>
+          regex?.test(_val) && {
+            message: `"${_val}" should not match a regex ${condition}`,
+            location: runOnValue(value) ? baseLocation : baseLocation.key(),
+          }
+      )
+      .filter(isTruthy);
+  },
+  enum: (value: string | string[], condition: string[], { baseLocation }: AssertionFnContext) => {
+    if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
+    const values = Array.isArray(value) ? value : [value];
+    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 }: AssertionFnContext
+  ) => {
+    const isDefined = typeof value !== 'undefined';
+    const isValid = condition ? isDefined : !isDefined;
+    return isValid
+      ? []
+      : [
+          {
+            message: condition ? `Should be defined` : 'Should be not defined',
+            location: baseLocation,
+          },
+        ];
+  },
+  required: (value: string[], keys: string[], { baseLocation }: AssertionFnContext) => {
+    return keys
+      .map(
+        (requiredKey) =>
+          !value.includes(requiredKey) && {
+            message: `${requiredKey} is required`,
+            location: baseLocation.key(),
+          }
+      )
+      .filter(isTruthy);
+  },
+  disallowed: (
+    value: string | string[],
+    condition: string[],
+    { baseLocation }: AssertionFnContext
+  ) => {
+    if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
+    const values = Array.isArray(value) ? value : [value];
+    return values
+      .map(
+        (_val) =>
+          condition.includes(_val) && {
+            message: `"${_val}" is disallowed`,
+            location: runOnValue(value) ? baseLocation : baseLocation.child(_val).key(),
+          }
+      )
+      .filter(isTruthy);
+  },
+  const: (
+    value: string | number | boolean | string[] | number[],
+    condition: string | number | boolean,
+    { baseLocation }: AssertionFnContext
+  ) => {
+    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: unknown, condition: boolean = true, { baseLocation }: AssertionFnContext) => {
+    const isUndefined = typeof value === 'undefined';
+    const isValid = condition ? isUndefined : !isUndefined;
+    return isValid
+      ? []
+      : [
+          {
+            message: condition ? `Should not be defined` : 'Should be defined',
+            location: baseLocation,
+          },
+        ];
+  },
+  nonEmpty: (
+    value: string | undefined | null,
+    condition: boolean = true,
+    { baseLocation }: AssertionFnContext
+  ) => {
+    const isEmpty = typeof value === 'undefined' || value === null || value === '';
+    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 }: AssertionFnContext) => {
+    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 }: AssertionFnContext) => {
+    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 }: AssertionFnContext) => {
+    if (typeof value === 'undefined' || isPlainObject(value)) return []; // property doesn't exist or is an object, no need to lint it with this assert
+    const values = Array.isArray(value) ? value : [value];
+    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: unknown[],
+    condition: OrderOptions | OrderDirection,
+    { baseLocation }: AssertionFnContext
+  ) => {
+    const direction = (condition as OrderOptions).direction || (condition as OrderDirection);
+    const property = (condition as OrderOptions).property;
+    if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'object' && !property) {
+      return [
+        {
+          message: `Please define a property to sort objects by`,
+          location: baseLocation,
+        },
+      ];
+    }
+    if (typeof value === 'undefined' || isOrdered(value, condition)) return [];
+
+    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 }: AssertionFnContext
+  ) => {
+    if (getIntersectionLength(value, condition) < 2) return [];
+    return [
+      {
+        message: `${condition.join(', ')} keys should be mutually exclusive`,
+        location: baseLocation.key(),
+      },
+    ];
+  },
+  mutuallyRequired: (
+    value: string[],
+    condition: string[],
+    { baseLocation }: AssertionFnContext
+  ) => {
+    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 }: AssertionFnContext) => {
+    return getIntersectionLength(value, condition) >= 1
+      ? []
+      : [
+          {
+            message: `Should have any of ${condition.join(', ')}`,
+            location: baseLocation.key(),
+          },
+        ];
+  },
+  ref: (
+    _value: unknown,
+    condition: string | boolean,
+    { baseLocation, rawValue }: AssertionFnContext
+  ) => {
+    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') {
+      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);
+    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): AssertionFn {
+  return (value: string[], options: any, ctx: AssertionFnContext) =>
+    fn.call(null, value, options, ctx);
+}