@redocly/openapi-core 1.0.0-beta.100

package/src/format/codeframes.ts

@@ -0,0 +1,210 @@
+import { gray, red, options as colorOptions } from 'colorette';
+import * as yamlAst from 'yaml-ast-parser';
+import { unescapePointer } from '../ref-utils';
+import { LineColLocationObject, Loc, LocationObject } from '../walk';
+
+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);
+    let startIdx = i === startLineNum ? start.col - 1 : currentPad;
+    let endIdx = i === endLineNum ? end.col - 1 : line.length;
+
+    prefixedLines.push([`${i}`, markLine(line, startIdx, endIdx, red)]);
+    if (!color) prefixedLines.push(['', underlineLine(line, startIdx, endIdx)]);
+  }
+
+  if (skipLines > 0) {
+    prefixedLines.push([`…`, `${whitespace(currentPad)}${gray(`< ${skipLines} more lines >`)}`]);
+    // print last line
+    prefixedLines.push([`${endLineNum}`, markLine(lines[endLineNum - 1], -1, end.col - 1, 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 = 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]) =>
+        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 = 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,339 @@
+import * as path from 'path';
+import {
+  options as colorOptions,
+  gray,
+  blue,
+  bgRed,
+  bgYellow,
+  black,
+  yellow,
+  red,
+} from 'colorette';
+
+const coreVersion = require('../../package.json').version;
+
+import { NormalizedProblem, ProblemSeverity, LineColLocationObject, LocationObject } from '../walk';
+import { getCodeframe, getLineColLocation } from './codeframes';
+import { env } from "../config";
+
+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) => bgYellow(black(str)),
+  error: bgRed,
+};
+
+const COLORS = {
+  warn: yellow,
+  error: 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';
+
+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];
+        process.stderr.write(`${formatCodeframe(problem, i)}\n`);
+      }
+      break;
+    case 'stylish': {
+      const groupedByFile = groupByFiles(problems);
+      for (const [file, { ruleIdPad, locationPad: positionPad, fileProblems }] of Object.entries(
+        groupedByFile,
+      )) {
+        process.stderr.write(`${blue(path.relative(cwd, file))}:\n`);
+
+        for (let i = 0; i < fileProblems.length; i++) {
+          const problem = fileProblems[i];
+          process.stderr.write(`${formatStylish(problem, positionPad, ruleIdPad)}\n`);
+        }
+
+        process.stderr.write('\n');
+      }
+      break;
+    }
+    case 'checkstyle': {
+      const groupedByFile = groupByFiles(problems);
+
+      process.stdout.write('<?xml version="1.0" encoding="UTF-8"?>\n');
+      process.stdout.write('<checkstyle version="4.3">\n');
+
+      for (const [file, { fileProblems }] of Object.entries(groupedByFile)) {
+        process.stdout.write(`<file name="${xmlEscape(path.relative(cwd, file))}">\n`);
+        fileProblems.forEach(formatCheckstyle);
+        process.stdout.write(`</file>\n`);
+      }
+
+      process.stdout.write(`</checkstyle>\n`);
+      break;
+    }
+    case 'codeclimate':
+      outputForCodeClimate();
+      break;
+  }
+
+  if (totalProblems - ignoredProblems > maxProblems) {
+    process.stderr.write(
+      `< ... ${totalProblems - maxProblems} more problems hidden > ${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: 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 : ''}`,
+      };
+    });
+    process.stdout.write(JSON.stringify(issues, null, 2));
+  }
+
+  function outputJSON() {
+    const resultObject = {
+      totals,
+      version,
+      problems: problems.map((p) => {
+        let problem = {
+          ...p,
+          location: p.location.map((location: any) => ({
+            ...location,
+            source: {
+              ref: path.relative(cwd, location.source.absoluteRef),
+            },
+          })),
+          from: p.from
+            ? {
+                ...p.from,
+                source: {
+                  ref: 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;
+      }),
+    };
+    process.stdout.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 = path.relative(cwd, location.source.absoluteRef);
+    const loc = getLineColLocation(location);
+    const atPointer = location.pointer ? 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 ${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);
+    process.stdout.write(
+      `<error line="${line}" column="${col}" severity="${severity}" message="${message}" source="${source}" />\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}`;
+
+  return `referenced from ${blue(fileWithLoc)}\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 {
+  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)};`;
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+export { BundleOutputFormat, readFileFromUrl, slash } from './utils';
+export { Oas3_1Types } from './types/oas3_1';
+export { Oas3Types } from './types/oas3';
+export { Oas2Types } from './types/oas2';
+export { ConfigTypes } from './types/redocly-yaml';
+export {
+  Oas3Definition,
+  Oas3_1Definition,
+  Oas3Components,
+  Oas3PathItem,
+  Oas3Paths,
+  Oas3ComponentName,
+  Oas3Schema,
+  Oas3_1Schema,
+  Oas3Tag,
+  Oas3_1Webhooks,
+  Referenced,
+} from './typings/openapi';
+export { Oas2Definition } from './typings/swagger';
+export { StatsAccumulator, StatsName } from './typings/common';
+export { normalizeTypes } from './types';
+export { Stats } from './rules/other/stats';
+
+export {
+  Config,
+  LintConfig,
+  RawConfig,
+  IGNORE_FILE,
+  Region,
+  getMergedConfig,
+  transformConfig,
+  loadConfig,
+  getConfig,
+  findConfig,
+  CONFIG_FILE_NAMES,
+} from './config';
+
+
+export { RedoclyClient, isRedoclyRegistryURL } from './redocly';
+
+export {
+  Source,
+  BaseResolver,
+  Document,
+  resolveDocument,
+  ResolveError,
+  YamlParseError,
+  makeDocumentFromString,
+} from './resolve';
+export { parseYaml, stringifyYaml } from './js-yaml';
+export { unescapePointer, isRef } from './ref-utils';
+export { detectOpenAPI, OasMajorVersion, openAPIMajor, OasVersion } from './oas-types';
+export { normalizeVisitors } from './visitors';
+
+export {
+  WalkContext,
+  walkDocument,
+  NormalizedProblem,
+  ProblemSeverity,
+  LineColLocationObject,
+  LocationObject,
+  Loc,
+} from './walk';
+
+export { getAstNodeByPointer, getLineColLocation } from './format/codeframes';
+export { formatProblems, OutputFormat, getTotals, Totals } from './format/format';
+export { lint, lint as validate, lintDocument, lintFromString, lintConfig } from './lint';
+export { bundle, bundleDocument, mapTypeToComponent } from './bundle';

package/src/js-yaml/index.ts

@@ -0,0 +1,18 @@
+// TODO: add a type for "types" https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/js-yaml/index.d.ts
+// @ts-ignore
+import { JSON_SCHEMA, types, LoadOptions, DumpOptions, load, dump  } from 'js-yaml';
+
+const DEFAULT_SCHEMA_WITHOUT_TIMESTAMP = JSON_SCHEMA.extend({
+  implicit: [types.merge],
+  explicit: [
+    types.binary,
+    types.omap,
+    types.pairs,
+    types.set,
+  ],
+});
+
+export const parseYaml = (str: string, opts?: LoadOptions): unknown =>
+  load(str, {schema: DEFAULT_SCHEMA_WITHOUT_TIMESTAMP, ...opts});
+
+export const stringifyYaml = (obj: any, opts?: DumpOptions): string => dump(obj, opts);