@redocly/openapi-core 1.0.0-beta.100

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

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

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

@@ -0,0 +1,89 @@
+import { isOrdered, buildVisitorObject, getIntersectionLength } 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 context = [
+          {
+            type: 'Foo',
+            matchParentKeys: ['test'],
+          },
+          {
+            type: 'Bar',
+            matchParentKeys: ['test'],
+          },
+          {
+            type: 'Roof',
+            matchParentKeys: ['test'],
+          },
+        ];
+
+        const visitors = buildVisitorObject('Bar', context, () => {}) as any;
+
+        expect(visitors).toMatchInlineSnapshot(`
+          Object {
+            "Foo": Object {
+              "Bar": Object {
+                "Roof": Object {
+                  "Bar": [Function],
+                  "skip": [Function],
+                },
+                "skip": [Function],
+              },
+              "skip": [Function],
+            },
+          }
+        `);
+      });
+
+      it('should return the right visitor structure', () => {
+        const context = [
+          {
+            type: 'Operation',
+            matchParentKeys: ['put'],
+          },
+          {
+            type: 'ResponsesMap',
+            matchParentKeys: [201, 200],
+          },
+        ];
+
+        const visitors = buildVisitorObject('MediaTypeMap', context, () => {}) as any;
+
+        expect(visitors).toMatchInlineSnapshot(`
+          Object {
+            "Operation": Object {
+              "ResponsesMap": Object {
+                "MediaTypeMap": [Function],
+                "skip": [Function],
+              },
+              "skip": [Function],
+            },
+          }
+        `);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,137 @@
+import { OrderOptions, OrderDirection, isOrdered, getIntersectionLength } from './utils';
+
+type Asserts = Record<string, (value: any, condition: any) => boolean>;
+
+export const runOnKeysSet = new Set([
+  'mutuallyExclusive',
+  'mutuallyRequired',
+  'enum',
+  'pattern',
+  'minLength',
+  'maxLength',
+  'casing',
+  'sortOrder',
+  'disallowed',
+  'required',
+]);
+export const runOnValuesSet = new Set([
+  'pattern',
+  'enum',
+  'defined',
+  'undefined',
+  'nonEmpty',
+  'minLength',
+  'maxLength',
+  'casing',
+  'sortOrder',
+]);
+
+export const asserts: Asserts = {
+  pattern: (value: string | string[], condition: string): boolean => {
+    if (typeof value === 'undefined') return true; // property doesn't exist, no need to lint it with this assert
+    const values = typeof value === 'string' ? [value] : value;
+    const regexOptions = condition.match(/(\b\/\b)(.+)/g) || ['/'];
+    condition = condition.slice(1).replace(regexOptions[0], '');
+    const regx = new RegExp(condition, regexOptions[0].slice(1));
+    for (let _val of values) {
+      if (!_val.match(regx)) {
+        return false;
+      }
+    }
+    return true;
+  },
+  enum: (value: string | string[], condition: string[]): boolean => {
+    if (typeof value === 'undefined') return true; // property doesn't exist, no need to lint it with this assert
+    const values = typeof value === 'string' ? [value] : value;
+    for (let _val of values) {
+      if (!condition.includes(_val)) {
+        return false;
+      }
+    }
+    return true;
+  },
+  defined: (value: string | undefined, condition: boolean = true): boolean => {
+    const isDefined = typeof value !== 'undefined';
+    return condition ? isDefined : !isDefined;
+  },
+  required: (value: string[], keys: string[]): boolean => {
+    for (const requiredKey of keys) {
+      if (!value.includes(requiredKey)) {
+        return false;
+      }
+    }
+    return true;
+  },
+  disallowed: (value: string | string[], condition: string[]): boolean => {
+    if (typeof value === 'undefined') return true; // property doesn't exist, no need to lint it with this assert
+    const values = typeof value === 'string' ? [value] : value;
+    for (let _val of values) {
+      if (condition.includes(_val)) {
+        return false;
+      }
+    }
+    return true;
+  },
+  undefined: (value: any, condition: boolean = true): boolean => {
+    const isUndefined = typeof value === 'undefined';
+    return condition ? isUndefined : !isUndefined;
+  },
+  nonEmpty: (value: string | undefined | null, condition: boolean = true): boolean => {
+    const isEmpty = typeof value === 'undefined' || value === null || value === '';
+    return condition ? !isEmpty : isEmpty;
+  },
+  minLength: (value: string | any[], condition: number): boolean => {
+    if (typeof value === 'undefined') return true; // property doesn't exist, no need to lint it with this assert
+    return value.length >= condition;
+  },
+  maxLength: (value: string | any[], condition: number): boolean => {
+    if (typeof value === 'undefined') return true; // property doesn't exist, no need to lint it with this assert
+    return value.length <= condition;
+  },
+  casing: (value: string | string[], condition: string): boolean => {
+    if (typeof value === 'undefined') return true; // property doesn't exist, no need to lint it with this assert
+    const values = typeof value === 'string' ? [value] : value;
+    for (let _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 false;
+      }
+    }
+    return true;
+  },
+  sortOrder: (value: any[], condition: OrderOptions | OrderDirection): boolean => {
+    if (typeof value === 'undefined') return true;
+    return isOrdered(value, condition);
+  },
+  mutuallyExclusive: (value: string[], condition: string[]): boolean => {
+    return getIntersectionLength(value, condition) < 2;
+  },
+  mutuallyRequired: (value: string[], condition: string[]): boolean => {
+    return getIntersectionLength(value, condition) > 0
+      ? getIntersectionLength(value, condition) === condition.length
+      : true;
+  },
+};

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

@@ -0,0 +1,75 @@
+import { asserts, runOnKeysSet, runOnValuesSet } from './asserts';
+import { AssertToApply, buildSubjectVisitor, buildVisitorObject } from './utils';
+import { Oas2Rule, Oas3Rule } from '../../../visitors';
+
+export const Assertions: Oas3Rule | Oas2Rule = (opts: object) => {
+  let visitors: any[] = [];
+
+  // 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
+  // that is why we need to iterate through 'opts' values;
+  // before - filter only object 'opts' values
+  const assertions: any[] = 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 {
+          assertId,
+          name: assertName,
+          conditions: assertion[assertName],
+          message: assertion.message,
+          severity: assertion.severity || 'error',
+          suggest: assertion.suggest || [],
+          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 (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(
+        assertion.property,
+        assertsToApply,
+        assertion.context,
+      );
+      const visitorObject = buildVisitorObject(subject, assertion.context, subjectVisitor);
+      visitors.push(visitorObject);
+    }
+  }
+
+  return visitors;
+};

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

@@ -0,0 +1,167 @@
+import { isRef } from '../../../ref-utils';
+import { Problem, ProblemSeverity, UserContext } from '../../../walk';
+import { asserts } from './asserts';
+
+export type OrderDirection = 'asc' | 'desc';
+
+export type OrderOptions = {
+  direction: OrderDirection;
+  property: string;
+};
+
+export type AssertToApply = {
+  name: string;
+  assertId?: string;
+  conditions: any;
+  message?: string;
+  severity?: ProblemSeverity;
+  suggest?: string[];
+  runsOnKeys: boolean;
+  runsOnValues: boolean;
+};
+
+export function buildVisitorObject(
+  subject: string,
+  context: Record<string, any>[],
+  subjectVisitor: any,
+) {
+  if (!context) {
+    return { [subject]: subjectVisitor };
+  }
+
+  let currentVisitorLevel: Record<string, any> = {};
+  const visitor: Record<string, any> = currentVisitorLevel;
+
+  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;
+
+    if (matchParentKeys && excludeParentKeys) {
+      throw new Error(
+        `Both 'matchParentKeys' and 'excludeParentKeys' can't be under one context item`,
+      );
+    }
+
+    if (matchParentKeys || excludeParentKeys) {
+      currentVisitorLevel[node.type] = {
+        skip: (_value: any, key: string) => {
+          if (matchParentKeys) {
+            return !matchParentKeys.includes(key);
+          }
+          if (excludeParentKeys) {
+            return excludeParentKeys.includes(key);
+          }
+        },
+      };
+    } else {
+      currentVisitorLevel[node.type] = {};
+    }
+    currentVisitorLevel = currentVisitorLevel[node.type];
+  }
+
+  currentVisitorLevel[subject] = subjectVisitor;
+
+  return visitor;
+}
+
+export function buildSubjectVisitor(
+  properties: string | string[],
+  asserts: AssertToApply[],
+  context?: Record<string, any>[],
+) {
+  return function (node: any, { report, location, key, type, resolve }: UserContext) {
+    // 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 (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];
+    }
+
+    for (const assert of asserts) {
+      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(value, assert, location.child(property), report);
+        }
+      } else {
+        runAssertion(Object.keys(node), assert, location.key(), report);
+      }
+    }
+  };
+}
+
+export function getIntersectionLength(keys: string[], properties: string[]): number {
+  const props = new Set(properties);
+  let count = 0;
+  for (const key of keys) {
+    if (props.has(key)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+export function isOrdered(value: any[], options: OrderOptions | OrderDirection): boolean {
+  const direction = (options as OrderOptions).direction || (options as OrderDirection);
+  const property = (options as OrderOptions).property;
+  for (let i = 1; i < value.length; i++) {
+    let currValue = value[i];
+    let prevVal = value[i - 1];
+
+    if (property) {
+      if (!value[i][property] || !value[i - 1][property]) {
+        return false; // property doesn't exist, so collection is not ordered
+      }
+      currValue = value[i][property];
+      prevVal = value[i - 1][property];
+    }
+
+    const result = direction === 'asc' ? currValue >= prevVal : currValue <= prevVal;
+    if (!result) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function runAssertion(
+  values: string | string[],
+  assert: AssertToApply,
+  location: any,
+  report: (problem: Problem) => void,
+) {
+  const lintResult = asserts[assert.name](values, assert.conditions);
+  if (!lintResult) {
+    report({
+      message: assert.message || `The ${assert.assertId} doesn't meet required conditions`,
+      location,
+      forceSeverity: assert.severity,
+      suggest: assert.suggest,
+      ruleId: assert.assertId,
+    });
+  }
+}

package/src/rules/common/info-contact.ts

@@ -0,0 +1,15 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { missingRequiredField } from '../utils';
+
+export const InfoContact: Oas3Rule | Oas2Rule = () => {
+  return {
+    Info(info, { report, location }) {
+      if (!info.contact) {
+        report({
+          message: missingRequiredField('Info', 'contact'),
+          location: location.child('contact').key(),
+        });
+      }
+    },
+  };
+};

package/src/rules/common/info-description.ts

@@ -0,0 +1,10 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { validateDefinedAndNonEmpty } from '../utils';
+
+export const InfoDescription: Oas3Rule | Oas2Rule = () => {
+  return {
+    Info(info, ctx) {
+      validateDefinedAndNonEmpty('description', info, ctx);
+    },
+  };
+};

package/src/rules/common/info-license-url.ts

@@ -0,0 +1,15 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { missingRequiredField } from '../utils';
+
+export const InfoLicense: Oas3Rule | Oas2Rule = () => {
+  return {
+    Info(info, { report }) {
+      if (!info.license) {
+        report({
+          message: missingRequiredField('Info', 'license'),
+          location: { reportOnKey: true }
+        });
+      }
+    },
+  };
+};

package/src/rules/common/license-url.ts

@@ -0,0 +1,10 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { validateDefinedAndNonEmpty } from '../utils';
+
+export const InfoLicenseUrl: Oas3Rule | Oas2Rule = () => {
+  return {
+    License(license, ctx) {
+      validateDefinedAndNonEmpty('url', license, ctx);
+    },
+  };
+};

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

@@ -0,0 +1,50 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3Paths } from '../../typings/openapi';
+import { Oas2Paths } from '../../typings/swagger';
+
+export const NoAmbiguousPaths: Oas3Rule | Oas2Rule = () => {
+  return {
+    PathMap(pathMap: Oas3Paths | Oas2Paths, { report, location }: UserContext) {
+      const seenPaths: string[] = [];
+
+      for (const currentPath of Object.keys(pathMap)) {
+        const ambiguousPath = seenPaths.find((seenPath) =>
+          arePathsAmbiguous(seenPath, currentPath),
+        );
+        if (ambiguousPath) {
+          report({
+            message: `Paths should resolve unambiguously. Found two ambiguous paths: \`${ambiguousPath}\` and \`${currentPath}\`.`,
+            location: location.child([currentPath]).key(),
+          });
+        }
+        seenPaths.push(currentPath);
+      }
+    },
+  };
+};
+
+function arePathsAmbiguous(a: string, b: string) {
+  const partsA = a.split('/');
+  const partsB = b.split('/');
+
+  if (partsA.length !== partsB.length) return false;
+
+  let aVars = 0;
+  let bVars = 0;
+  let ambiguous = true;
+  for (let i = 0; i < partsA.length; i++) {
+    const aIsVar = partsA[i].match(/^{.+?}$/);
+    const bIsVar = partsB[i].match(/^{.+?}$/);
+
+    if (aIsVar || bIsVar) {
+      if (aIsVar) aVars++;
+      if (bIsVar) bVars++;
+      continue;
+    } else if (partsA[i] !== partsB[i]) {
+      ambiguous = false;
+    }
+  }
+
+  return ambiguous && aVars === bVars;
+}

package/src/rules/common/no-enum-type-mismatch.ts

@@ -0,0 +1,49 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { matchesJsonSchemaType, oasTypeOf } from '../utils';
+import { Oas2Schema } from '../../typings/swagger';
+import { Oas3Schema } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+
+export const NoEnumTypeMismatch: Oas3Rule | Oas2Rule = () => {
+  return {
+    Schema(schema: Oas2Schema | Oas3Schema, { report, location }: UserContext) {
+      if (schema.enum && !Array.isArray(schema.enum)) return;
+      if (schema.enum && schema.type && !Array.isArray(schema.type)) {
+        const typeMismatchedValues = schema.enum.filter(
+          (item) => !matchesJsonSchemaType(item, schema.type as string, schema.nullable as boolean),
+        );
+        for (const mismatchedValue of typeMismatchedValues) {
+          report({
+            message: `All values of \`enum\` field must be of the same type as the \`type\` field: expected "${
+              schema.type
+            }" but received "${oasTypeOf(mismatchedValue)}".`,
+            location: location.child(['enum', schema.enum.indexOf(mismatchedValue)]),
+          });
+        }
+      }
+
+      if (schema.enum && schema.type && Array.isArray(schema.type)) {
+        const mismatchedResults: { [key: string]: string[]; } = {};
+        for (const enumValue of schema.enum) {
+          mismatchedResults[enumValue] = [];
+
+          for (const type of schema.type) {
+            const valid = matchesJsonSchemaType(enumValue, type as string, schema.nullable as boolean);
+            if (!valid)
+              mismatchedResults[enumValue].push(type);
+          }
+
+          if(mismatchedResults[enumValue].length !== schema.type.length)
+            delete mismatchedResults[enumValue];
+        };
+
+        for (const mismatchedKey of Object.keys(mismatchedResults)) {
+          report({
+            message: `Enum value \`${mismatchedKey}\` must be of one type. Allowed types: \`${schema.type}\`.`,
+            location: location.child(['enum', schema.enum.indexOf(mismatchedKey)]),
+          });
+        };
+      }
+    },
+  };
+};