@redocly/openapi-core 1.0.0 → 1.0.2

package/src/config/config.ts

@@ -0,0 +1,332 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseYaml, stringifyYaml } from '../js-yaml';
+import { slash, doesYamlFileExist } from '../utils';
+import { NormalizedProblem } from '../walk';
+import { OasVersion, OasMajorVersion, Oas2RuleSet, Oas3RuleSet } from '../oas-types';
+import { isBrowser, env } from '../env';
+
+import type { NodeType } from '../types';
+import type {
+  DecoratorConfig,
+  Plugin,
+  PreprocessorConfig,
+  Region,
+  ResolveConfig,
+  ResolvedApi,
+  ResolvedConfig,
+  ResolvedStyleguideConfig,
+  RuleConfig,
+  RuleSettings,
+  Telemetry,
+  ThemeRawConfig,
+} from './types';
+import { getResolveConfig } from './utils';
+import { isAbsoluteUrl } from '../ref-utils';
+
+export const IGNORE_FILE = '.redocly.lint-ignore.yaml';
+const IGNORE_BANNER =
+  `# This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.\n` +
+  `# See https://redoc.ly/docs/cli/ for more information.\n`;
+
+export const DEFAULT_REGION = 'us';
+
+function getDomains() {
+  const domains: { [region in Region]: string } = {
+    us: 'redocly.com',
+    eu: 'eu.redocly.com',
+  };
+
+  // FIXME: temporary fix for our lab environments
+  const domain = env.REDOCLY_DOMAIN;
+  if (domain?.endsWith('.redocly.host')) {
+    domains[domain.split('.')[0] as Region] = domain;
+  }
+  if (domain === 'redoc.online') {
+    domains[domain as Region] = domain;
+  }
+  return domains;
+}
+
+function getIgnoreFilePath(configFile?: string): string | undefined {
+  if (configFile) {
+    return doesYamlFileExist(configFile)
+      ? path.join(path.dirname(configFile), IGNORE_FILE)
+      : path.join(configFile, IGNORE_FILE);
+  } else {
+    return isBrowser ? undefined : path.join(process.cwd(), IGNORE_FILE);
+  }
+}
+
+export const DOMAINS = getDomains();
+export const AVAILABLE_REGIONS = Object.keys(DOMAINS) as Region[];
+
+export class StyleguideConfig {
+  plugins: Plugin[];
+  ignore: Record<string, Record<string, Set<string>>> = {};
+  doNotResolveExamples: boolean;
+  rules: Record<OasVersion, Record<string, RuleConfig>>;
+  preprocessors: Record<OasVersion, Record<string, PreprocessorConfig>>;
+  decorators: Record<OasVersion, Record<string, DecoratorConfig>>;
+
+  private _usedRules: Set<string> = new Set();
+  private _usedVersions: Set<OasVersion> = new Set();
+
+  recommendedFallback: boolean;
+
+  extendPaths: string[];
+  pluginPaths: string[];
+
+  constructor(public rawConfig: ResolvedStyleguideConfig, public configFile?: string) {
+    this.plugins = rawConfig.plugins || [];
+    this.doNotResolveExamples = !!rawConfig.doNotResolveExamples;
+    this.recommendedFallback = rawConfig.recommendedFallback || false;
+
+    this.rules = {
+      [OasVersion.Version2]: { ...rawConfig.rules, ...rawConfig.oas2Rules },
+      [OasVersion.Version3_0]: { ...rawConfig.rules, ...rawConfig.oas3_0Rules },
+      [OasVersion.Version3_1]: { ...rawConfig.rules, ...rawConfig.oas3_1Rules },
+    };
+
+    this.preprocessors = {
+      [OasVersion.Version2]: { ...rawConfig.preprocessors, ...rawConfig.oas2Preprocessors },
+      [OasVersion.Version3_0]: { ...rawConfig.preprocessors, ...rawConfig.oas3_0Preprocessors },
+      [OasVersion.Version3_1]: { ...rawConfig.preprocessors, ...rawConfig.oas3_1Preprocessors },
+    };
+
+    this.decorators = {
+      [OasVersion.Version2]: { ...rawConfig.decorators, ...rawConfig.oas2Decorators },
+      [OasVersion.Version3_0]: { ...rawConfig.decorators, ...rawConfig.oas3_0Decorators },
+      [OasVersion.Version3_1]: { ...rawConfig.decorators, ...rawConfig.oas3_1Decorators },
+    };
+
+    this.extendPaths = rawConfig.extendPaths || [];
+    this.pluginPaths = rawConfig.pluginPaths || [];
+    this.resolveIgnore(getIgnoreFilePath(configFile));
+  }
+
+  resolveIgnore(ignoreFile?: string) {
+    if (!ignoreFile || !doesYamlFileExist(ignoreFile)) return;
+
+    this.ignore =
+      (parseYaml(fs.readFileSync(ignoreFile, 'utf-8')) as Record<
+        string,
+        Record<string, Set<string>>
+      >) || {};
+
+    // resolve ignore paths
+    for (const fileName of Object.keys(this.ignore)) {
+      this.ignore[
+        isAbsoluteUrl(fileName) ? fileName : path.resolve(path.dirname(ignoreFile), fileName)
+      ] = this.ignore[fileName];
+
+      for (const ruleId of Object.keys(this.ignore[fileName])) {
+        this.ignore[fileName][ruleId] = new Set(this.ignore[fileName][ruleId]);
+      }
+
+      if (!isAbsoluteUrl(fileName)) {
+        delete this.ignore[fileName];
+      }
+    }
+  }
+
+  saveIgnore() {
+    const dir = this.configFile ? path.dirname(this.configFile) : process.cwd();
+    const ignoreFile = path.join(dir, IGNORE_FILE);
+    const mapped: Record<string, any> = {};
+    for (const absFileName of Object.keys(this.ignore)) {
+      const mappedDefinitionName = isAbsoluteUrl(absFileName)
+        ? absFileName
+        : slash(path.relative(dir, absFileName));
+      const ignoredRules = (mapped[mappedDefinitionName] = this.ignore[absFileName]);
+
+      for (const ruleId of Object.keys(ignoredRules)) {
+        ignoredRules[ruleId] = Array.from(ignoredRules[ruleId]) as any;
+      }
+    }
+    fs.writeFileSync(ignoreFile, IGNORE_BANNER + stringifyYaml(mapped));
+  }
+
+  addIgnore(problem: NormalizedProblem) {
+    const ignore = this.ignore;
+    const loc = problem.location[0];
+    if (loc.pointer === undefined) return;
+
+    const fileIgnore = (ignore[loc.source.absoluteRef] = ignore[loc.source.absoluteRef] || {});
+    const ruleIgnore = (fileIgnore[problem.ruleId] = fileIgnore[problem.ruleId] || new Set());
+
+    ruleIgnore.add(loc.pointer);
+  }
+
+  addProblemToIgnore(problem: NormalizedProblem) {
+    const loc = problem.location[0];
+    if (loc.pointer === undefined) return problem;
+
+    const fileIgnore = this.ignore[loc.source.absoluteRef] || {};
+    const ruleIgnore = fileIgnore[problem.ruleId];
+    const ignored = ruleIgnore && ruleIgnore.has(loc.pointer);
+    return ignored
+      ? {
+          ...problem,
+          ignored,
+        }
+      : problem;
+  }
+
+  extendTypes(types: Record<string, NodeType>, version: OasVersion) {
+    let extendedTypes = types;
+    for (const plugin of this.plugins) {
+      if (plugin.typeExtension !== undefined) {
+        switch (version) {
+          case OasVersion.Version3_0:
+          case OasVersion.Version3_1:
+            if (!plugin.typeExtension.oas3) continue;
+            extendedTypes = plugin.typeExtension.oas3(extendedTypes, version);
+            break;
+          case OasVersion.Version2:
+            if (!plugin.typeExtension.oas2) continue;
+            extendedTypes = plugin.typeExtension.oas2(extendedTypes, version);
+            break;
+          default:
+            throw new Error('Not implemented');
+        }
+      }
+    }
+    return extendedTypes;
+  }
+
+  getRuleSettings(ruleId: string, oasVersion: OasVersion): RuleSettings {
+    this._usedRules.add(ruleId);
+    this._usedVersions.add(oasVersion);
+    const settings = this.rules[oasVersion][ruleId] || 'off';
+    if (typeof settings === 'string') {
+      return {
+        severity: settings,
+      };
+    } else {
+      return { severity: 'error', ...settings };
+    }
+  }
+
+  getPreprocessorSettings(ruleId: string, oasVersion: OasVersion): RuleSettings {
+    this._usedRules.add(ruleId);
+    this._usedVersions.add(oasVersion);
+
+    const settings = this.preprocessors[oasVersion][ruleId] || 'off';
+    if (typeof settings === 'string') {
+      return {
+        severity: settings === 'on' ? 'error' : settings,
+      };
+    } else {
+      return { severity: 'error', ...settings };
+    }
+  }
+
+  getDecoratorSettings(ruleId: string, oasVersion: OasVersion): RuleSettings {
+    this._usedRules.add(ruleId);
+    this._usedVersions.add(oasVersion);
+    const settings = this.decorators[oasVersion][ruleId] || 'off';
+    if (typeof settings === 'string') {
+      return {
+        severity: settings === 'on' ? 'error' : settings,
+      };
+    } else {
+      return { severity: 'error', ...settings };
+    }
+  }
+
+  getUnusedRules() {
+    const rules = [];
+    const decorators = [];
+    const preprocessors = [];
+
+    for (const usedVersion of Array.from(this._usedVersions)) {
+      rules.push(
+        ...Object.keys(this.rules[usedVersion]).filter((name) => !this._usedRules.has(name))
+      );
+      decorators.push(
+        ...Object.keys(this.decorators[usedVersion]).filter((name) => !this._usedRules.has(name))
+      );
+      preprocessors.push(
+        ...Object.keys(this.preprocessors[usedVersion]).filter((name) => !this._usedRules.has(name))
+      );
+    }
+
+    return {
+      rules,
+      preprocessors,
+      decorators,
+    };
+  }
+
+  getRulesForOasVersion(version: OasMajorVersion) {
+    switch (version) {
+      case OasMajorVersion.Version3:
+        // eslint-disable-next-line no-case-declarations
+        const oas3Rules: Oas3RuleSet[] = []; // default ruleset
+        this.plugins.forEach((p) => p.preprocessors?.oas3 && oas3Rules.push(p.preprocessors.oas3));
+        this.plugins.forEach((p) => p.rules?.oas3 && oas3Rules.push(p.rules.oas3));
+        this.plugins.forEach((p) => p.decorators?.oas3 && oas3Rules.push(p.decorators.oas3));
+        return oas3Rules;
+      case OasMajorVersion.Version2:
+        // eslint-disable-next-line no-case-declarations
+        const oas2Rules: Oas2RuleSet[] = []; // default ruleset
+        this.plugins.forEach((p) => p.preprocessors?.oas2 && oas2Rules.push(p.preprocessors.oas2));
+        this.plugins.forEach((p) => p.rules?.oas2 && oas2Rules.push(p.rules.oas2));
+        this.plugins.forEach((p) => p.decorators?.oas2 && oas2Rules.push(p.decorators.oas2));
+        return oas2Rules;
+    }
+  }
+
+  skipRules(rules?: string[]) {
+    for (const ruleId of rules || []) {
+      for (const version of Object.values(OasVersion)) {
+        if (this.rules[version][ruleId]) {
+          this.rules[version][ruleId] = 'off';
+        }
+      }
+    }
+  }
+
+  skipPreprocessors(preprocessors?: string[]) {
+    for (const preprocessorId of preprocessors || []) {
+      for (const version of Object.values(OasVersion)) {
+        if (this.preprocessors[version][preprocessorId]) {
+          this.preprocessors[version][preprocessorId] = 'off';
+        }
+      }
+    }
+  }
+
+  skipDecorators(decorators?: string[]) {
+    for (const decoratorId of decorators || []) {
+      for (const version of Object.values(OasVersion)) {
+        if (this.decorators[version][decoratorId]) {
+          this.decorators[version][decoratorId] = 'off';
+        }
+      }
+    }
+  }
+}
+
+export class Config {
+  apis: Record<string, ResolvedApi>;
+  styleguide: StyleguideConfig;
+  resolve: ResolveConfig;
+  licenseKey?: string;
+  region?: Region;
+  theme: ThemeRawConfig;
+  organization?: string;
+  files: string[];
+  telemetry?: Telemetry;
+  constructor(public rawConfig: ResolvedConfig, public configFile?: string) {
+    this.apis = rawConfig.apis || {};
+    this.styleguide = new StyleguideConfig(rawConfig.styleguide || {}, configFile);
+    this.theme = rawConfig.theme || {};
+    this.resolve = getResolveConfig(rawConfig?.resolve);
+    this.region = rawConfig.region;
+    this.organization = rawConfig.organization;
+    this.files = rawConfig.files || [];
+    this.telemetry = rawConfig.telemetry;
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,7 @@
+export * from './config';
+export * from './types';
+export * from './rules';
+export * from './builtIn';
+export * from './load';
+export * from './utils';
+export * from './config-resolvers';

package/src/config/load.ts

@@ -0,0 +1,144 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { RedoclyClient } from '../redocly';
+import { isEmptyObject, loadYaml, doesYamlFileExist } from '../utils';
+import { parseYaml } from '../js-yaml';
+import { Config, DOMAINS } from './config';
+import { transformConfig } from './utils';
+import { resolveConfig } from './config-resolvers';
+
+import type { DeprecatedInRawConfig, FlatRawConfig, RawConfig, Region } from './types';
+import { RegionalTokenWithValidity } from '../redocly/redocly-client-types';
+
+async function addConfigMetadata({
+  rawConfig,
+  customExtends,
+  configPath,
+  tokens,
+  files,
+  region,
+}: {
+  rawConfig: RawConfig;
+  customExtends?: string[];
+  configPath?: string;
+  tokens?: RegionalTokenWithValidity[];
+  files?: string[];
+  region?: Region;
+}): Promise<Config> {
+  if (customExtends !== undefined) {
+    rawConfig.styleguide = rawConfig.styleguide || {};
+    rawConfig.styleguide.extends = customExtends;
+  } else if (isEmptyObject(rawConfig)) {
+    rawConfig.styleguide = { extends: ['recommended'], recommendedFallback: true };
+  }
+
+  if (tokens?.length) {
+    if (!rawConfig.resolve) rawConfig.resolve = {};
+    if (!rawConfig.resolve.http) rawConfig.resolve.http = {};
+    rawConfig.resolve.http.headers = [...(rawConfig.resolve.http.headers ?? [])];
+
+    for (const item of tokens) {
+      const domain = DOMAINS[item.region as Region];
+      rawConfig.resolve.http.headers.push(
+        {
+          matches: `https://api.${domain}/registry/**`,
+          name: 'Authorization',
+          envVariable: undefined,
+          value: item.token,
+        },
+        //support redocly.com domain for future compatibility
+        ...(item.region === 'us'
+          ? [
+              {
+                matches: `https://api.redoc.ly/registry/**`,
+                name: 'Authorization',
+                envVariable: undefined,
+                value: item.token,
+              },
+            ]
+          : [])
+      );
+    }
+  }
+
+  return resolveConfig(
+    { ...rawConfig, files: files ?? rawConfig.files, region: region ?? rawConfig.region },
+    configPath
+  );
+}
+
+export async function loadConfig(
+  options: {
+    configPath?: string;
+    customExtends?: string[];
+    processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>;
+    files?: string[];
+    region?: Region;
+  } = {}
+): Promise<Config> {
+  const { configPath = findConfig(), customExtends, processRawConfig, files, region } = options;
+  const rawConfig = await getConfig(configPath, processRawConfig);
+
+  const redoclyClient = new RedoclyClient();
+  const tokens = await redoclyClient.getTokens();
+
+  return addConfigMetadata({
+    rawConfig,
+    customExtends,
+    configPath,
+    tokens,
+    files,
+    region,
+  });
+}
+
+export const CONFIG_FILE_NAMES = ['redocly.yaml', 'redocly.yml', '.redocly.yaml', '.redocly.yml'];
+
+export function findConfig(dir?: string): string | undefined {
+  if (!fs.hasOwnProperty('existsSync')) return;
+  const existingConfigFiles = CONFIG_FILE_NAMES.map((name) =>
+    dir ? path.resolve(dir, name) : name
+  ).filter(fs.existsSync);
+  if (existingConfigFiles.length > 1) {
+    throw new Error(`
+      Multiple configuration files are not allowed. 
+      Found the following files: ${existingConfigFiles.join(', ')}. 
+      Please use 'redocly.yaml' instead.
+    `);
+  }
+  return existingConfigFiles[0];
+}
+
+export async function getConfig(
+  configPath: string | undefined = findConfig(),
+  processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>
+): Promise<RawConfig> {
+  if (!configPath || !doesYamlFileExist(configPath)) return {};
+  try {
+    const rawConfig =
+      (await loadYaml<RawConfig & DeprecatedInRawConfig & FlatRawConfig>(configPath)) || {};
+    if (typeof processRawConfig === 'function') {
+      await processRawConfig(rawConfig);
+    }
+    return transformConfig(rawConfig);
+  } catch (e) {
+    throw new Error(`Error parsing config file at '${configPath}': ${e.message}`);
+  }
+}
+
+type CreateConfigOptions = {
+  extends?: string[];
+  tokens?: RegionalTokenWithValidity[];
+};
+
+export async function createConfig(
+  config: string | RawConfig,
+  options?: CreateConfigOptions
+): Promise<Config> {
+  return addConfigMetadata({
+    rawConfig: transformConfig(
+      typeof config === 'string' ? (parseYaml(config) as RawConfig) : config
+    ),
+    ...options,
+  });
+}

package/src/config/minimal.ts

@@ -0,0 +1,61 @@
+import type { PluginStyleguideConfig } from './types';
+
+export default {
+  rules: {
+    'info-contact': 'off',
+    'info-license': 'off',
+    'info-license-url': 'off',
+    'tag-description': 'warn',
+    'tags-alphabetical': 'off',
+    'parameter-description': 'off',
+    'no-path-trailing-slash': 'warn',
+    'no-identical-paths': 'warn',
+    'no-ambiguous-paths': 'warn',
+    'path-declaration-must-exist': 'warn',
+    'path-not-include-query': 'warn',
+    'path-parameters-defined': 'warn',
+    'operation-description': 'off',
+    'operation-2xx-response': 'warn',
+    'operation-4xx-response': 'off',
+    'operation-operationId': 'warn',
+    'operation-summary': 'warn',
+    'operation-operationId-unique': 'warn',
+    'operation-parameters-unique': 'warn',
+    'operation-tag-defined': 'off',
+    'security-defined': 'warn',
+    'operation-operationId-url-safe': 'warn',
+    'operation-singular-tag': 'off',
+    'no-unresolved-refs': 'error',
+    'no-enum-type-mismatch': 'warn',
+    'boolean-parameter-prefixes': 'off',
+    'paths-kebab-case': 'off',
+    spec: 'error',
+    'spec-strict-refs': 'off',
+    'component-name-unique': 'off',
+  },
+  oas3_0Rules: {
+    'no-invalid-media-type-examples': {
+      severity: 'warn',
+      allowAdditionalProperties: false,
+    },
+    'no-server-example.com': 'warn',
+    'no-server-trailing-slash': 'error',
+    'no-empty-servers': 'warn',
+    'no-example-value-and-externalValue': 'warn',
+    'no-unused-components': 'warn',
+    'no-undefined-server-variable': 'warn',
+    'no-server-variables-empty-enum': 'error',
+    'spec-components-invalid-map-name': 'warn',
+  },
+  oas3_1Rules: {
+    'no-invalid-media-type-examples': 'warn',
+    'no-server-example.com': 'warn',
+    'no-server-trailing-slash': 'error',
+    'no-empty-servers': 'warn',
+    'no-example-value-and-externalValue': 'warn',
+    'no-unused-components': 'warn',
+    'no-undefined-server-variable': 'warn',
+    'no-server-variables-empty-enum': 'error',
+    'spec-components-invalid-map-name': 'warn',
+  },
+} as PluginStyleguideConfig;

package/src/config/recommended.ts

@@ -0,0 +1,61 @@
+import type { PluginStyleguideConfig } from './types';
+
+export default {
+  rules: {
+    'info-contact': 'off',
+    'info-license': 'warn',
+    'info-license-url': 'warn',
+    'tag-description': 'warn',
+    'tags-alphabetical': 'off',
+    'parameter-description': 'off',
+    'no-path-trailing-slash': 'error',
+    'no-identical-paths': 'error',
+    'no-ambiguous-paths': 'warn',
+    'path-declaration-must-exist': 'error',
+    'path-not-include-query': 'error',
+    'path-parameters-defined': 'error',
+    'operation-description': 'off',
+    'operation-2xx-response': 'warn',
+    'operation-4xx-response': 'warn',
+    'operation-operationId': 'warn',
+    'operation-summary': 'error',
+    'operation-operationId-unique': 'error',
+    'operation-operationId-url-safe': 'error',
+    'operation-parameters-unique': 'error',
+    'operation-tag-defined': 'off',
+    'security-defined': 'error',
+    'operation-singular-tag': 'off',
+    'no-unresolved-refs': 'error',
+    'no-enum-type-mismatch': 'error',
+    'boolean-parameter-prefixes': 'off',
+    'paths-kebab-case': 'off',
+    spec: 'error',
+    'spec-strict-refs': 'off',
+    'component-name-unique': 'off',
+  },
+  oas3_0Rules: {
+    'no-invalid-media-type-examples': {
+      severity: 'warn',
+      allowAdditionalProperties: false,
+    },
+    'no-server-example.com': 'warn',
+    'no-server-trailing-slash': 'error',
+    'no-empty-servers': 'error',
+    'no-example-value-and-externalValue': 'error',
+    'no-unused-components': 'warn',
+    'no-undefined-server-variable': 'error',
+    'no-server-variables-empty-enum': 'error',
+    'spec-components-invalid-map-name': 'error',
+  },
+  oas3_1Rules: {
+    'no-invalid-media-type-examples': 'warn',
+    'no-server-example.com': 'warn',
+    'no-server-trailing-slash': 'error',
+    'no-empty-servers': 'error',
+    'no-example-value-and-externalValue': 'error',
+    'no-unused-components': 'warn',
+    'no-undefined-server-variable': 'error',
+    'no-server-variables-empty-enum': 'error',
+    'spec-components-invalid-map-name': 'error',
+  },
+} as PluginStyleguideConfig;

package/src/config/rules.ts

@@ -0,0 +1,54 @@
+import { RuleSet, OasVersion } from '../oas-types';
+import { StyleguideConfig } from './config';
+import { isDefined } from '../utils';
+import type { ProblemSeverity } from '../walk';
+
+type InitializedRule = {
+  severity: ProblemSeverity;
+  ruleId: string;
+  visitor: any;
+};
+
+export function initRules<T extends Function, P extends RuleSet<T>>(
+  rules: P[],
+  config: StyleguideConfig,
+  type: 'rules' | 'preprocessors' | 'decorators',
+  oasVersion: OasVersion
+): InitializedRule[] {
+  return rules
+    .flatMap((ruleset) =>
+      Object.keys(ruleset).map((ruleId) => {
+        const rule = ruleset[ruleId];
+
+        const ruleSettings =
+          type === 'rules'
+            ? config.getRuleSettings(ruleId, oasVersion)
+            : type === 'preprocessors'
+            ? config.getPreprocessorSettings(ruleId, oasVersion)
+            : config.getDecoratorSettings(ruleId, oasVersion);
+
+        if (ruleSettings.severity === 'off') {
+          return undefined;
+        }
+        const severity: ProblemSeverity = ruleSettings.severity;
+
+        const visitors = rule(ruleSettings);
+
+        if (Array.isArray(visitors)) {
+          return visitors.map((visitor: any) => ({
+            severity,
+            ruleId,
+            visitor: visitor,
+          }));
+        }
+
+        return {
+          severity,
+          ruleId,
+          visitor: visitors, // note: actually it is only one visitor object
+        };
+      })
+    )
+    .flatMap((visitor) => visitor)
+    .filter(isDefined);
+}