@redocly/openapi-core 1.0.0 → 1.0.1

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

@@ -0,0 +1,53 @@
+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 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: Assertion[] = Object.values(opts).filter(
+    (opt: unknown) => typeof opt === 'object' && opt !== null
+  );
+
+  for (const [_, assertion] of assertions.entries()) {
+    if (!isString(assertion.subject.type)) {
+      throw new Error(`${assertion.assertionId}: 'type' (String) is required`);
+    }
+
+    const subjectVisitor = buildSubjectVisitor(assertion.assertionId, assertion);
+    const visitorObject = buildVisitorObject(assertion, subjectVisitor);
+    visitors.push(visitorObject);
+  }
+
+  return visitors;
+};

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

@@ -0,0 +1,331 @@
+import { asserts, runOnKeysSet, runOnValuesSet, Asserts } from './asserts';
+import { colorize } from '../../../logger';
+import { isRef } from '../../../ref-utils';
+import { isTruthy, keysOf, isString } from '../../../utils';
+import type { AssertionContext, AssertResult } from '../../../config';
+import type { Assertion, AssertionDefinition, AssertionLocators } from '.';
+import type {
+  Oas2Visitor,
+  Oas3Visitor,
+  SkipFunctionContext,
+  VisitFunction,
+} from '../../../visitors';
+import { UserContext } from 'core/src/walk';
+
+export type OrderDirection = 'asc' | 'desc';
+
+export type OrderOptions = {
+  direction: OrderDirection;
+  property: string;
+};
+
+export type AssertToApply = {
+  name: keyof Asserts;
+  conditions: any;
+  runsOnKeys: boolean;
+  runsOnValues: boolean;
+};
+
+type RunAssertionParams = {
+  ctx: AssertionContext;
+  assert: AssertToApply;
+  assertionProperty?: string;
+};
+
+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[],
+  ctx: AssertionContext
+): AssertResult[] {
+  const properties = getAssertionProperties(assertionDefinition);
+  const assertResults: Array<AssertResult[]> = [];
+
+  for (const assert of asserts) {
+    if (properties.length) {
+      for (const property of properties) {
+        assertResults.push(
+          runAssertion({
+            assert,
+            ctx,
+            assertionProperty: property,
+          })
+        );
+      }
+    } else {
+      assertResults.push(
+        runAssertion({
+          assert,
+          ctx,
+        })
+      );
+    }
+  }
+
+  return assertResults.flat();
+}
+
+export function buildVisitorObject(
+  assertion: Assertion,
+  subjectVisitor: VisitFunction<any>
+): Oas2Visitor | Oas3Visitor {
+  const targetVisitorLocatorPredicates = getPredicatesFromLocators(assertion.subject);
+  const targetVisitorSkipFunction = targetVisitorLocatorPredicates.length
+    ? (_: 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 assertionDefinitionNode = context[index];
+
+    if (!isString(assertionDefinitionNode.subject?.type)) {
+      throw new Error(
+        `${assertion.assertionId} -> where -> [${index}]: 'type' (String) is required`
+      );
+    }
+
+    const locatorPredicates = getPredicatesFromLocators(assertionDefinitionNode.subject);
+    const assertsToApply = getAssertsToApply(assertionDefinitionNode);
+
+    const skipFunction = (node: unknown, key: string | number, ctx: SkipFunctionContext): boolean =>
+      !locatorPredicates.every((predicate) => predicate(key)) ||
+      !!applyAssertions(assertionDefinitionNode, assertsToApply, { ...ctx, node }).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 = currentVisitorLevel[assertionDefinitionNode.subject?.type] =
+        nodeVisitor;
+    }
+  }
+
+  currentVisitorLevel[assertion.subject.type] = targetVisitor[assertion.subject.type];
+
+  return visitor;
+}
+
+export function buildSubjectVisitor(assertId: string, assertion: Assertion): VisitFunction<any> {
+  return (node: any, ctx: UserContext) => {
+    const properties = getAssertionProperties(assertion);
+
+    const defaultMessage = `${colorize.blue(assertId)} failed because the ${colorize.blue(
+      assertion.subject.type
+    )} ${colorize.blue(properties.join(', '))} didn't meet the assertions: ${
+      assertionMessageTemplates.problems
+    }`.replace(/ +/g, ' ');
+
+    const problems = applyAssertions(assertion, getAssertsToApply(assertion), {
+      ...ctx,
+      node,
+    });
+
+    if (problems.length) {
+      for (const problemGroup of groupProblemsByPointer(problems)) {
+        const message = assertion.message || defaultMessage;
+        const problemMessage = getProblemsMessage(problemGroup);
+        ctx.report({
+          message: message.replace(assertionMessageTemplates.problems, problemMessage),
+          location: getProblemsLocation(problemGroup) || ctx.location,
+          forceSeverity: assertion.severity || 'error',
+          suggest: assertion.suggest || [],
+          ruleId: assertId,
+        });
+      }
+    }
+  };
+}
+
+function groupProblemsByPointer(problems: AssertResult[]): AssertResult[][] {
+  const groups: Record<string, AssertResult[]> = {};
+  for (const problem of problems) {
+    if (!problem.location) continue;
+    const pointer = problem.location.pointer;
+    groups[pointer] = groups[pointer] || [];
+    groups[pointer].push(problem);
+  }
+  return Object.values(groups);
+}
+
+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;
+  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) {
+      const currPropValue = value[i][property];
+      const prevPropValue = value[i - 1][property];
+
+      if (!currPropValue || !prevPropValue) {
+        return false; // property doesn't exist, so collection is not ordered
+      }
+
+      currValue = currPropValue;
+      prevVal = prevPropValue;
+    }
+
+    if (typeof currValue === 'string' && typeof prevVal === 'string') {
+      currValue = currValue.toLowerCase();
+      prevVal = prevVal.toLowerCase();
+    }
+
+    const result = direction === 'asc' ? currValue >= prevVal : currValue <= prevVal;
+    if (!result) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function runAssertion({
+  assert,
+  ctx,
+  assertionProperty,
+}: RunAssertionParams): AssertResult[] {
+  const currentLocation = assert.name === 'ref' ? ctx.rawLocation : ctx.location;
+
+  if (assertionProperty) {
+    const values = isRef(ctx.node[assertionProperty])
+      ? ctx.resolve(ctx.node[assertionProperty])?.node
+      : ctx.node[assertionProperty];
+    const rawValues = ctx.rawNode[assertionProperty];
+
+    const location = currentLocation.child(assertionProperty);
+
+    return asserts[assert.name](values, assert.conditions, {
+      ...ctx,
+      baseLocation: location,
+      rawValue: rawValues,
+    });
+  } else {
+    const value = Array.isArray(ctx.node) ? ctx.node : Object.keys(ctx.node);
+
+    return asserts[assert.name](value, assert.conditions, {
+      ...ctx,
+      rawValue: ctx.rawNode,
+      baseLocation: currentLocation,
+    });
+  }
+}
+
+export function regexFromString(input: string): RegExp | null {
+  const matches = input.match(/^\/(.*)\/(.*)|(.*)/);
+  return matches && new RegExp(matches[1] || matches[3], matches[2]);
+}

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-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/info-license.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/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 {
+    Paths(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,52 @@
+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 allowed types: \`${schema.type}\`.`,
+            location: location.child(['enum', schema.enum.indexOf(mismatchedKey)]),
+          });
+        }
+      }
+    },
+  };
+};

package/src/rules/common/no-http-verbs-in-paths.ts

@@ -0,0 +1,36 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { Oas2PathItem } from '../../typings/swagger';
+import { Oas3PathItem } from '../../typings/openapi';
+import { UserContext } from '../../walk';
+import { isPathParameter, splitCamelCaseIntoWords } from '../../utils';
+
+const httpMethods = ['get', 'head', 'post', 'put', 'patch', 'delete', 'options', 'trace'];
+
+export const NoHttpVerbsInPaths: Oas3Rule | Oas2Rule = ({ splitIntoWords }) => {
+  return {
+    PathItem(_path: Oas2PathItem | Oas3PathItem, { key, report, location }: UserContext) {
+      const pathKey = key.toString();
+      if (!pathKey.startsWith('/')) return;
+      const pathSegments = pathKey.split('/');
+
+      for (const pathSegment of pathSegments) {
+        if (!pathSegment || isPathParameter(pathSegment)) continue;
+
+        const isHttpMethodIncluded = (method: string) => {
+          return splitIntoWords
+            ? splitCamelCaseIntoWords(pathSegment).has(method)
+            : pathSegment.toLocaleLowerCase().includes(method);
+        };
+
+        for (const method of httpMethods) {
+          if (isHttpMethodIncluded(method)) {
+            report({
+              message: `path \`${pathKey}\` should not contain http verb ${method}`,
+              location: location.key(),
+            });
+          }
+        }
+      }
+    },
+  };
+};

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

@@ -0,0 +1,24 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+import { Oas3Paths } from '../../typings/openapi';
+import { Oas2Paths } from '../../typings/swagger';
+
+export const NoIdenticalPaths: Oas3Rule | Oas2Rule = () => {
+  return {
+    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 = 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 {
+          Paths.set(id, pathName);
+        }
+      }
+    },
+  };
+};

package/src/rules/common/no-invalid-parameter-examples.ts

@@ -0,0 +1,36 @@
+import { UserContext } from '../../walk';
+import { Oas3Parameter } from '../../typings/openapi';
+import { getAdditionalPropertiesOption, validateExample } from '../utils';
+
+export const NoInvalidParameterExamples: any = (opts: any) => {
+  const allowAdditionalProperties = getAdditionalPropertiesOption(opts) ?? false;
+  return {
+    Parameter: {
+      leave(parameter: Oas3Parameter, ctx: UserContext) {
+        if (parameter.example) {
+          validateExample(
+            parameter.example,
+            parameter.schema!,
+            ctx.location.child('example'),
+            ctx,
+            allowAdditionalProperties
+          );
+        }
+
+        if (parameter.examples) {
+          for (const [key, example] of Object.entries(parameter.examples)) {
+            if ('value' in example) {
+              validateExample(
+                example.value,
+                parameter.schema!,
+                ctx.location.child(['examples', key]),
+                ctx,
+                true
+              );
+            }
+          }
+        }
+      },
+    },
+  };
+};

package/src/rules/common/no-invalid-schema-examples.ts

@@ -0,0 +1,27 @@
+import { UserContext } from '../../walk';
+import { Oas3_1Schema } from '../../typings/openapi';
+import { getAdditionalPropertiesOption, validateExample } from '../utils';
+
+export const NoInvalidSchemaExamples: any = (opts: any) => {
+  const allowAdditionalProperties = getAdditionalPropertiesOption(opts) ?? false;
+  return {
+    Schema: {
+      leave(schema: Oas3_1Schema, ctx: UserContext) {
+        if (schema.examples) {
+          for (const example of schema.examples) {
+            validateExample(
+              example,
+              schema,
+              ctx.location.child(['examples', schema.examples.indexOf(example)]),
+              ctx,
+              allowAdditionalProperties
+            );
+          }
+        }
+        if (schema.example) {
+          validateExample(schema.example, schema, ctx.location.child('example'), ctx, true);
+        }
+      },
+    },
+  };
+};

package/src/rules/common/no-path-trailing-slash.ts

@@ -0,0 +1,15 @@
+import { Oas3Rule, Oas2Rule } from '../../visitors';
+import { UserContext } from '../../walk';
+
+export const NoPathTrailingSlash: Oas3Rule | Oas2Rule = () => {
+  return {
+    PathItem(_path: any, { report, key, location }: UserContext) {
+      if ((key as string).endsWith('/') && key !== '/') {
+        report({
+          message: `\`${key}\` should not have a trailing slash.`,
+          location: location.key(),
+        });
+      }
+    },
+  };
+};