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

package/src/decorators/oas2/index.ts

@@ -0,0 +1,20 @@
+import { Oas2Decorator } from '../../visitors';
+import { RegistryDependencies } from '../common/registry-dependencies';
+import { OperationDescriptionOverride } from '../common/operation-description-override';
+import { TagDescriptionOverride } from '../common/tag-description-override';
+import { InfoDescriptionOverride } from '../common/info-description-override';
+import { InfoOverride } from '../common/info-override';
+import { RemoveXInternal } from '../common/remove-x-internal';
+import { FilterIn } from '../common/filters/filter-in';
+import { FilterOut } from '../common/filters/filter-out';
+
+export const decorators = {
+  'registry-dependencies': RegistryDependencies as Oas2Decorator,
+  'operation-description-override': OperationDescriptionOverride as Oas2Decorator,
+  'tag-description-override': TagDescriptionOverride as Oas2Decorator,
+  'info-description-override': InfoDescriptionOverride as Oas2Decorator,
+  'info-override': InfoOverride as Oas2Decorator,
+  'remove-x-internal': RemoveXInternal as Oas2Decorator,
+  'filter-in': FilterIn as Oas2Decorator,
+  'filter-out': FilterOut as Oas2Decorator,
+};

package/src/decorators/oas3/index.ts

@@ -0,0 +1,22 @@
+import { Oas3Decorator } from '../../visitors';
+import { RegistryDependencies } from '../common/registry-dependencies';
+import { OperationDescriptionOverride } from '../common/operation-description-override';
+import { TagDescriptionOverride } from '../common/tag-description-override';
+import { InfoDescriptionOverride } from '../common/info-description-override';
+import { InfoOverride } from '../common/info-override';
+import { RemoveXInternal } from '../common/remove-x-internal';
+import { FilterIn } from '../common/filters/filter-in';
+import { FilterOut } from '../common/filters/filter-out';
+import { MediaTypeExamplesOverride } from '../common/media-type-examples-override';
+
+export const decorators = {
+  'registry-dependencies': RegistryDependencies as Oas3Decorator,
+  'operation-description-override': OperationDescriptionOverride as Oas3Decorator,
+  'tag-description-override': TagDescriptionOverride as Oas3Decorator,
+  'info-description-override': InfoDescriptionOverride as Oas3Decorator,
+  'info-override': InfoOverride as Oas3Decorator,
+  'remove-x-internal': RemoveXInternal as Oas3Decorator,
+  'filter-in': FilterIn as Oas3Decorator,
+  'filter-out': FilterOut as Oas3Decorator,
+  'media-type-examples-override': MediaTypeExamplesOverride as Oas3Decorator,
+};

package/src/env.ts

@@ -0,0 +1,5 @@
+export const isBrowser =
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  typeof window !== 'undefined' || typeof self !== 'undefined' || typeof process === 'undefined'; // main and worker thread
+export const env = isBrowser ? {} : process.env || {};

package/src/format/codeframes.ts

@@ -0,0 +1,216 @@
+import * as yamlAst from 'yaml-ast-parser';
+import { unescapePointer } from '../ref-utils';
+import { LineColLocationObject, Loc, LocationObject } from '../walk';
+import { colorize, colorOptions } from '../logger';
+
+type YAMLMapping = yamlAst.YAMLMapping & { kind: yamlAst.Kind.MAPPING };
+type YAMLMap = yamlAst.YamlMap & { kind: yamlAst.Kind.MAP };
+type YAMLAnchorReference = yamlAst.YAMLAnchorReference & { kind: yamlAst.Kind.ANCHOR_REF };
+type YAMLSequence = yamlAst.YAMLSequence & { kind: yamlAst.Kind.SEQ };
+type YAMLScalar = yamlAst.YAMLScalar & { kind: yamlAst.Kind.SCALAR };
+type YAMLNode = YAMLMapping | YAMLMap | YAMLAnchorReference | YAMLSequence | YAMLScalar;
+
+const MAX_LINE_LENGTH = 150;
+const MAX_CODEFRAME_LINES = 3;
+
+// TODO: temporary
+function parsePointer(pointer: string) {
+  return pointer.substr(2).split('/').map(unescapePointer);
+}
+
+export function getCodeframe(location: LineColLocationObject, color: boolean) {
+  colorOptions.enabled = color;
+  const { start, end = { line: start.line, col: start.col + 1 }, source } = location;
+  const lines = source.getLines();
+  const startLineNum = start.line;
+  const endLineNum = Math.max(Math.min(end.line, lines.length), start.line);
+  let skipLines = Math.max(endLineNum - startLineNum - MAX_CODEFRAME_LINES + 1, 0);
+  if (skipLines < 2) skipLines = 0; // do not skip one line
+
+  // Lines specified like this: ["prefix", "string"],
+  const prefixedLines: [string, string][] = [];
+
+  let currentPad = 0;
+
+  for (let i = startLineNum; i <= endLineNum; i++) {
+    if (skipLines > 0 && i >= endLineNum - skipLines) break;
+    const line = lines[i - 1] || '';
+    if (line !== '') currentPad = padSize(line);
+    const startIdx = i === startLineNum ? start.col - 1 : currentPad;
+    const endIdx = i === endLineNum ? end.col - 1 : line.length;
+
+    prefixedLines.push([`${i}`, markLine(line, startIdx, endIdx, colorize.red)]);
+    if (!color) prefixedLines.push(['', underlineLine(line, startIdx, endIdx)]);
+  }
+
+  if (skipLines > 0) {
+    prefixedLines.push([
+      `…`,
+      `${whitespace(currentPad)}${colorize.gray(`< ${skipLines} more lines >`)}`,
+    ]);
+    // print last line
+    prefixedLines.push([
+      `${endLineNum}`,
+      markLine(lines[endLineNum - 1], -1, end.col - 1, colorize.red),
+    ]);
+
+    if (!color) prefixedLines.push(['', underlineLine(lines[endLineNum - 1], -1, end.col - 1)]);
+  }
+
+  return printPrefixedLines([
+    [`${startLineNum - 2}`, markLine(lines[startLineNum - 1 - 2])],
+    [`${startLineNum - 1}`, markLine(lines[startLineNum - 1 - 1])],
+    ...prefixedLines,
+    [`${endLineNum + 1}`, markLine(lines[endLineNum - 1 + 1])],
+    [`${endLineNum + 2}`, markLine(lines[endLineNum - 1 + 2])],
+  ]);
+
+  function markLine(
+    line: string,
+    startIdx: number = -1,
+    endIdx: number = +Infinity,
+    variant = colorize.gray
+  ) {
+    if (!color) return line;
+    if (!line) return line;
+
+    if (startIdx === -1) {
+      startIdx = padSize(line);
+    }
+
+    endIdx = Math.min(endIdx, line.length);
+    return (
+      line.substr(0, startIdx) + variant(line.substring(startIdx, endIdx)) + line.substr(endIdx)
+    );
+  }
+}
+
+function printPrefixedLines(lines: [string, string][]): string {
+  const existingLines = lines.filter(([_, line]) => line !== undefined);
+
+  const padLen = Math.max(...existingLines.map(([prefix]) => prefix.length));
+  const dedentLen = Math.min(
+    ...existingLines.map(([_, line]) => (line === '' ? Infinity : padSize(line)))
+  );
+
+  return existingLines
+    .map(
+      ([prefix, line]) =>
+        colorize.gray(leftPad(padLen, prefix) + ' |') +
+        (line ? ' ' + limitLineLength(line.substring(dedentLen)) : '')
+    )
+    .join('\n');
+}
+
+function limitLineLength(line: string, maxLen: number = MAX_LINE_LENGTH) {
+  const overflowLen = line.length - maxLen;
+  if (overflowLen > 0) {
+    const charsMoreText = colorize.gray(`...<${overflowLen} chars>`);
+    return line.substring(0, maxLen - charsMoreText.length) + charsMoreText;
+  } else {
+    return line;
+  }
+}
+
+function underlineLine(line: string, startIdx: number = -1, endIdx: number = +Infinity) {
+  if (startIdx === -1) {
+    startIdx = padSize(line);
+  }
+
+  endIdx = Math.min(endIdx, line.length);
+  return whitespace(startIdx) + '^'.repeat(Math.max(endIdx - startIdx, 1));
+}
+
+function whitespace(len: number): string {
+  return ' '.repeat(len);
+}
+
+function leftPad(len: number, str: string): string {
+  return whitespace(len - str.length) + str;
+}
+
+function padSize(line: string): number {
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] !== ' ') return i;
+  }
+  return line.length;
+}
+
+export function getLineColLocation(location: LocationObject): LineColLocationObject {
+  if (location.pointer === undefined) return location;
+
+  const { source, pointer, reportOnKey } = location;
+  const ast = source.getAst(yamlAst.safeLoad) as YAMLNode;
+  const astNode = getAstNodeByPointer(ast, pointer, !!reportOnKey);
+  return {
+    ...location,
+    pointer: undefined,
+    ...positionsToLoc(source.body, astNode?.startPosition ?? 1, astNode?.endPosition ?? 1),
+  };
+}
+
+function positionsToLoc(
+  source: string,
+  startPos: number,
+  endPos: number
+): { start: Loc; end: Loc } {
+  let currentLine = 1;
+  let currentCol = 1;
+  let start: Loc = { line: 1, col: 1 };
+
+  for (let i = 0; i < endPos - 1; i++) {
+    if (i === startPos - 1) {
+      start = { line: currentLine, col: currentCol + 1 };
+    }
+    if (source[i] === '\n') {
+      currentLine++;
+      currentCol = 1;
+      if (i === startPos - 1) {
+        start = { line: currentLine, col: currentCol };
+      }
+
+      if (source[i + 1] === '\r') i++; // TODO: test it
+      continue;
+    }
+    currentCol++;
+  }
+
+  const end = startPos === endPos ? { ...start } : { line: currentLine, col: currentCol + 1 };
+  return { start, end };
+}
+
+export function getAstNodeByPointer(root: YAMLNode, pointer: string, reportOnKey: boolean) {
+  const pointerSegments = parsePointer(pointer);
+  if (root === undefined) {
+    return undefined;
+  }
+
+  let currentNode = root;
+  for (const key of pointerSegments) {
+    if (currentNode.kind === yamlAst.Kind.MAP) {
+      const mapping = currentNode.mappings.find((m) => m.key.value === key);
+      if (!mapping) break;
+      currentNode = mapping as YAMLNode;
+      if (!mapping?.value) break; // If node has value - return value, if not - return node itself
+      currentNode = mapping.value as YAMLNode;
+    } else if (currentNode.kind === yamlAst.Kind.SEQ) {
+      const elem = currentNode.items[parseInt(key, 10)] as YAMLNode;
+      if (!elem) break;
+      currentNode = elem as YAMLNode;
+    }
+  }
+
+  if (!reportOnKey) {
+    return currentNode;
+  } else {
+    const parent = currentNode.parent as YAMLNode;
+    if (!parent) return currentNode;
+    if (parent.kind === yamlAst.Kind.SEQ) {
+      return currentNode;
+    } else if (parent.kind === yamlAst.Kind.MAPPING) {
+      return parent.key;
+    } else {
+      return currentNode;
+    }
+  }
+}

package/src/format/format.ts

@@ -0,0 +1,375 @@
+import * as path from 'path';
+import { colorOptions, colorize, logger } from '../logger';
+import { output } from '../output';
+
+const coreVersion = require('../../package.json').version;
+
+import { NormalizedProblem, ProblemSeverity, LineColLocationObject, LocationObject } from '../walk';
+import { getCodeframe, getLineColLocation } from './codeframes';
+import { env } from '../env';
+import { isAbsoluteUrl } from '../ref-utils';
+
+export type Totals = {
+  errors: number;
+  warnings: number;
+  ignored: number;
+};
+
+const ERROR_MESSAGE = {
+  INVALID_SEVERITY_LEVEL: 'Invalid severity level; accepted values: error or warn',
+};
+
+const BG_COLORS = {
+  warn: (str: string) => colorize.bgYellow(colorize.black(str)),
+  error: colorize.bgRed,
+};
+
+const COLORS = {
+  warn: colorize.yellow,
+  error: colorize.red,
+};
+
+const SEVERITY_NAMES = {
+  warn: 'Warning',
+  error: 'Error',
+};
+
+const CODECLIMATE_SEVERITY_MAPPING = {
+  error: 'critical',
+  warn: 'minor',
+};
+
+const MAX_SUGGEST = 5;
+
+function severityToNumber(severity: ProblemSeverity) {
+  return severity === 'error' ? 1 : 2;
+}
+
+export type OutputFormat =
+  | 'codeframe'
+  | 'stylish'
+  | 'json'
+  | 'checkstyle'
+  | 'codeclimate'
+  | 'summary';
+
+export function getTotals(problems: (NormalizedProblem & { ignored?: boolean })[]): Totals {
+  let errors = 0;
+  let warnings = 0;
+  let ignored = 0;
+
+  for (const m of problems) {
+    if (m.ignored) {
+      ignored++;
+      continue;
+    }
+    if (m.severity === 'error') errors++;
+    if (m.severity === 'warn') warnings++;
+  }
+
+  return {
+    errors,
+    warnings,
+    ignored,
+  };
+}
+
+export function formatProblems(
+  problems: (NormalizedProblem & { ignored?: boolean })[],
+  opts: {
+    maxProblems?: number;
+    cwd?: string;
+    format?: OutputFormat;
+    color?: boolean;
+    totals: Totals;
+    version: string;
+  }
+) {
+  const {
+    maxProblems = 100,
+    cwd = process.cwd(),
+    format = 'codeframe',
+    color = colorOptions.enabled,
+    totals = getTotals(problems),
+    version = coreVersion,
+  } = opts;
+
+  colorOptions.enabled = color; // force colors if specified
+
+  const totalProblems = problems.length;
+  problems = problems.filter((m) => !m.ignored);
+  const ignoredProblems = totalProblems - problems.length;
+
+  problems = problems
+    .sort((a, b) => severityToNumber(a.severity) - severityToNumber(b.severity))
+    .slice(0, maxProblems);
+
+  if (!totalProblems && format !== 'json') return;
+
+  switch (format) {
+    case 'json':
+      outputJSON();
+      break;
+    case 'codeframe':
+      for (let i = 0; i < problems.length; i++) {
+        const problem = problems[i];
+        logger.info(`${formatCodeframe(problem, i)}\n`);
+      }
+      break;
+    case 'stylish': {
+      const groupedByFile = groupByFiles(problems);
+      for (const [file, { ruleIdPad, locationPad: positionPad, fileProblems }] of Object.entries(
+        groupedByFile
+      )) {
+        logger.info(`${colorize.blue(isAbsoluteUrl(file) ? file : path.relative(cwd, file))}:\n`);
+
+        for (let i = 0; i < fileProblems.length; i++) {
+          const problem = fileProblems[i];
+          logger.info(`${formatStylish(problem, positionPad, ruleIdPad)}\n`);
+        }
+
+        logger.info('\n');
+      }
+      break;
+    }
+    case 'checkstyle': {
+      const groupedByFile = groupByFiles(problems);
+
+      output.write('<?xml version="1.0" encoding="UTF-8"?>\n');
+      output.write('<checkstyle version="4.3">\n');
+
+      for (const [file, { fileProblems }] of Object.entries(groupedByFile)) {
+        output.write(
+          `<file name="${xmlEscape(isAbsoluteUrl(file) ? file : path.relative(cwd, file))}">\n`
+        );
+        fileProblems.forEach(formatCheckstyle);
+        output.write(`</file>\n`);
+      }
+
+      output.write(`</checkstyle>\n`);
+      break;
+    }
+    case 'codeclimate':
+      outputForCodeClimate();
+      break;
+    case 'summary':
+      formatSummary(problems);
+      break;
+  }
+
+  if (totalProblems - ignoredProblems > maxProblems) {
+    logger.info(
+      `< ... ${totalProblems - maxProblems} more problems hidden > ${colorize.gray(
+        'increase with `--max-problems N`'
+      )}\n`
+    );
+  }
+
+  function outputForCodeClimate() {
+    const issues = problems.map((p) => {
+      const location = p.location[0]; // TODO: support multiple location
+      const lineCol = getLineColLocation(location);
+      return {
+        description: p.message,
+        location: {
+          path: isAbsoluteUrl(location.source.absoluteRef)
+            ? location.source.absoluteRef
+            : path.relative(cwd, location.source.absoluteRef),
+          lines: {
+            begin: lineCol.start.line,
+          },
+        },
+        severity: CODECLIMATE_SEVERITY_MAPPING[p.severity],
+        fingerprint: `${p.ruleId}${p.location.length > 0 ? '-' + p.location[0].pointer : ''}`,
+      };
+    });
+    output.write(JSON.stringify(issues, null, 2));
+  }
+
+  function outputJSON() {
+    const resultObject = {
+      totals,
+      version,
+      problems: problems.map((p) => {
+        const problem = {
+          ...p,
+          location: p.location.map((location: any) => ({
+            ...location,
+            source: {
+              ref: isAbsoluteUrl(location.source.absoluteRef)
+                ? location.source.absoluteRef
+                : path.relative(cwd, location.source.absoluteRef),
+            },
+          })),
+          from: p.from
+            ? {
+                ...p.from,
+                source: {
+                  ref: isAbsoluteUrl(p.from?.source.absoluteRef)
+                    ? p.from?.source.absoluteRef
+                    : path.relative(cwd, p.from?.source.absoluteRef || cwd),
+                },
+              }
+            : undefined,
+        };
+
+        if (env.FORMAT_JSON_WITH_CODEFRAMES) {
+          const location = p.location[0]; // TODO: support multiple locations
+          const loc = getLineColLocation(location);
+          (problem as any).codeframe = getCodeframe(loc, color);
+        }
+        return problem;
+      }),
+    };
+    output.write(JSON.stringify(resultObject, null, 2));
+  }
+
+  function getBgColor(problem: NormalizedProblem) {
+    const { severity } = problem;
+    if (!BG_COLORS[severity]) {
+      throw new Error(ERROR_MESSAGE.INVALID_SEVERITY_LEVEL);
+    }
+    return BG_COLORS[severity];
+  }
+
+  function formatCodeframe(problem: NormalizedProblem, idx: number) {
+    const bgColor = getBgColor(problem);
+    const location = problem.location[0]; // TODO: support multiple locations
+    const relativePath = isAbsoluteUrl(location.source.absoluteRef)
+      ? location.source.absoluteRef
+      : path.relative(cwd, location.source.absoluteRef);
+    const loc = getLineColLocation(location);
+    const atPointer = location.pointer ? colorize.gray(`at ${location.pointer}`) : '';
+    const fileWithLoc = `${relativePath}:${loc.start.line}:${loc.start.col}`;
+    return (
+      `[${idx + 1}] ${bgColor(fileWithLoc)} ${atPointer}\n\n` +
+      `${problem.message}\n\n` +
+      formatDidYouMean(problem) +
+      getCodeframe(loc, color) +
+      '\n\n' +
+      formatFrom(cwd, problem.from) +
+      `${SEVERITY_NAMES[problem.severity]} was generated by the ${colorize.blue(
+        problem.ruleId
+      )} rule.\n\n`
+    );
+  }
+
+  function formatStylish(problem: OnlyLineColProblem, locationPad: number, ruleIdPad: number) {
+    const color = COLORS[problem.severity];
+    if (!SEVERITY_NAMES[problem.severity]) {
+      return 'Error not found severity. Please check your config file. Allowed values: `warn,error,off`';
+    }
+    const severityName = color(SEVERITY_NAMES[problem.severity].toLowerCase().padEnd(7));
+    const { start } = problem.location[0];
+    return `  ${`${start.line}:${start.col}`.padEnd(
+      locationPad
+    )}  ${severityName}  ${problem.ruleId.padEnd(ruleIdPad)}  ${problem.message}`;
+  }
+
+  function formatCheckstyle(problem: OnlyLineColProblem) {
+    const { line, col } = problem.location[0].start;
+    const severity = problem.severity == 'warn' ? 'warning' : 'error';
+    const message = xmlEscape(problem.message);
+    const source = xmlEscape(problem.ruleId);
+    output.write(
+      `<error line="${line}" column="${col}" severity="${severity}" message="${message}" source="${source}" />\n`
+    );
+  }
+}
+
+function formatSummary(problems: NormalizedProblem[]): void {
+  const counts: Record<string, { count: number; severity: ProblemSeverity }> = {};
+  for (const problem of problems) {
+    counts[problem.ruleId] = counts[problem.ruleId] || { count: 0, severity: problem.severity };
+    counts[problem.ruleId].count++;
+  }
+  const sorted = Object.entries(counts).sort(([, a], [, b]) => {
+    const severityDiff = severityToNumber(a.severity) - severityToNumber(b.severity);
+    return severityDiff || b.count - a.count;
+  });
+
+  for (const [ruleId, info] of sorted) {
+    const color = COLORS[info.severity];
+    const severityName = color(SEVERITY_NAMES[info.severity].toLowerCase().padEnd(7));
+    logger.info(`${severityName} ${ruleId}: ${info.count}\n`);
+  }
+
+  logger.info('\n');
+}
+
+function formatFrom(cwd: string, location?: LocationObject) {
+  if (!location) return '';
+  const relativePath = path.relative(cwd, location.source.absoluteRef);
+  const loc = getLineColLocation(location);
+  const fileWithLoc = `${relativePath}:${loc.start.line}:${loc.start.col}`;
+  const atPointer = location.pointer ? colorize.gray(`at ${location.pointer}`) : '';
+
+  return `referenced from ${colorize.blue(fileWithLoc)} ${atPointer} \n\n`;
+}
+
+function formatDidYouMean(problem: NormalizedProblem) {
+  if (problem.suggest.length === 0) return '';
+
+  if (problem.suggest.length === 1) {
+    return `Did you mean: ${problem.suggest[0]} ?\n\n`;
+  } else {
+    return `Did you mean:\n  - ${problem.suggest.slice(0, MAX_SUGGEST).join('\n  - ')}\n\n`;
+  }
+}
+
+type OnlyLineColProblem = Omit<NormalizedProblem, 'location'> & {
+  location: LineColLocationObject[];
+};
+
+const groupByFiles = (problems: NormalizedProblem[]) => {
+  const fileGroups: Record<
+    string,
+    {
+      locationPad: number;
+      ruleIdPad: number;
+      fileProblems: OnlyLineColProblem[];
+    }
+  > = {};
+  for (const problem of problems) {
+    const absoluteRef = problem.location[0].source.absoluteRef; // TODO: multiple errors
+    fileGroups[absoluteRef] = fileGroups[absoluteRef] || {
+      fileProblems: [],
+      ruleIdPad: 0,
+      locationPad: 0,
+    };
+
+    const mappedProblem = { ...problem, location: problem.location.map(getLineColLocation) };
+    fileGroups[absoluteRef].fileProblems.push(mappedProblem);
+    fileGroups[absoluteRef].ruleIdPad = Math.max(
+      problem.ruleId.length,
+      fileGroups[absoluteRef].ruleIdPad
+    );
+
+    fileGroups[absoluteRef].locationPad = Math.max(
+      Math.max(...mappedProblem.location.map((loc) => `${loc.start.line}:${loc.start.col}`.length)),
+      fileGroups[absoluteRef].locationPad
+    );
+  }
+
+  return fileGroups;
+};
+
+function xmlEscape(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/[<>&"'\x00-\x1F\x7F\u0080-\uFFFF]/gu, (char) => {
+    switch (char) {
+      case '<':
+        return '&lt;';
+      case '>':
+        return '&gt;';
+      case '&':
+        return '&amp;';
+      case '"':
+        return '&quot;';
+      case "'":
+        return '&apos;';
+      default:
+        return `&#${char.charCodeAt(0)};`;
+    }
+  });
+}