@redocly/openapi-core 1.0.0-beta.100

package/src/config/load.ts

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { RedoclyClient } from '../redocly';
+import { isEmptyObject, loadYaml } from '../utils';
+import { Config, DOMAINS } from './config';
+import { transformConfig } from './utils';
+import { resolveConfig } from './config-resolvers';
+
+import type { RawConfig, Region } from './types';
+
+export async function loadConfig(
+  configPath: string | undefined = findConfig(),
+  customExtends?: string[],
+): Promise<Config> {
+  const rawConfig = await getConfig(configPath);
+  if (customExtends !== undefined) {
+    rawConfig.lint = rawConfig.lint || {};
+    rawConfig.lint.extends = customExtends;
+  } else if (isEmptyObject(rawConfig)) {
+    // TODO: check if we can add recommended here. add message here?
+    // rawConfig.lint = { extends: ['recommended'], recommendedFallback: true };
+  }
+
+  const redoclyClient = new RedoclyClient();
+  const tokens = await redoclyClient.getTokens();
+
+  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, configPath);
+}
+
+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()) {
+  if (!configPath) return {};
+  try {
+    const rawConfig = ((await loadYaml(configPath)) || {}) as RawConfig;
+    return transformConfig(rawConfig);
+  } catch (e) {
+    throw new Error(`Error parsing config file at '${configPath}': ${e.message}`);
+  }
+}

package/src/config/minimal.ts

@@ -0,0 +1,58 @@
+import type { PluginLintConfig } from './types';
+
+export default {
+  rules: {
+    'info-description': 'warn',
+    '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',
+    'assertions': 'warn',
+    'operation-operationId': 'warn',
+    'operation-summary': 'warn',
+    'operation-operationId-unique': 'warn',
+    'operation-parameters-unique': 'warn',
+    'operation-tag-defined': 'off',
+    'operation-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',
+  },
+  oas3_0Rules: {
+    'no-invalid-media-type-examples': {
+      severity: 'warn',
+      disallowAdditionalProperties: true,
+    },
+    '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-servers-empty-enum': 'error',
+  },
+  oas3_1Rules: {
+    '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-servers-empty-enum': 'error',
+  },
+} as PluginLintConfig;

package/src/config/recommended.ts

@@ -0,0 +1,58 @@
+import type { PluginLintConfig } from './types';
+
+export default {
+  rules: {
+    'info-description': 'warn',
+    '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',
+    'assertions': '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',
+    'operation-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',
+  },
+  oas3_0Rules: {
+    'no-invalid-media-type-examples': {
+      severity: 'warn',
+      disallowAdditionalProperties: true,
+    },
+    '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-servers-empty-enum': 'error',
+  },
+  oas3_1Rules: {
+    '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-servers-empty-enum': 'error',
+  },
+} as PluginLintConfig;

package/src/config/rules.ts

@@ -0,0 +1,46 @@
+import { RuleSet, OasVersion } from '../oas-types';
+import { LintConfig } from './config';
+import { notUndefined } from '../utils';
+
+export function initRules<T extends Function, P extends RuleSet<T>>(
+  rules: P[],
+  config: LintConfig,
+  type: 'rules' | 'preprocessors' | 'decorators',
+  oasVersion: OasVersion,
+) {
+  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 visitors = rule(ruleSettings);
+
+        if (Array.isArray(visitors)) {
+          return visitors.map((visitor: any) => ({
+            severity: ruleSettings.severity,
+            ruleId,
+            visitor: visitor,
+          }))
+        }
+
+        return {
+          severity: ruleSettings.severity,
+          ruleId,
+          visitor: visitors, // note: actually it is only one visitor object
+        };
+      }),
+    )
+    .flatMap(visitor => visitor)
+    .filter(notUndefined);
+}

package/src/config/types.ts

@@ -0,0 +1,168 @@
+import type { ProblemSeverity } from '../walk';
+import type {
+  Oas3PreprocessorsSet,
+  OasMajorVersion,
+  Oas3DecoratorsSet,
+  Oas2RuleSet,
+  Oas2PreprocessorsSet,
+  Oas2DecoratorsSet,
+  Oas3RuleSet,
+  OasVersion,
+} from '../oas-types';
+import type { NodeType } from '../types';
+
+export type RuleConfig =
+  | ProblemSeverity
+  | 'off'
+  | ({
+      severity?: ProblemSeverity;
+    } & Record<string, any>);
+
+export type PreprocessorConfig =
+  | ProblemSeverity
+  | 'off'
+  | 'on'
+  | ({
+      severity?: ProblemSeverity;
+    } & Record<string, any>);
+
+export type DecoratorConfig = PreprocessorConfig;
+
+export type LintRawConfig = {
+  plugins?: (string | Plugin)[];
+  extends?: string[];
+  doNotResolveExamples?: boolean;
+  recommendedFallback?: boolean;
+
+  rules?: Record<string, RuleConfig>;
+  oas2Rules?: Record<string, RuleConfig>;
+  oas3_0Rules?: Record<string, RuleConfig>;
+  oas3_1Rules?: Record<string, RuleConfig>;
+
+  preprocessors?: Record<string, PreprocessorConfig>;
+  oas2Preprocessors?: Record<string, PreprocessorConfig>;
+  oas3_0Preprocessors?: Record<string, PreprocessorConfig>;
+  oas3_1Preprocessors?: Record<string, PreprocessorConfig>;
+
+  decorators?: Record<string, DecoratorConfig>;
+  oas2Decorators?: Record<string, DecoratorConfig>;
+  oas3_0Decorators?: Record<string, DecoratorConfig>;
+  oas3_1Decorators?: Record<string, DecoratorConfig>;
+};
+
+export type ResolvedLintConfig = PluginLintConfig & {
+  plugins?: Plugin[];
+  recommendedFallback?: boolean;
+  extends?: void | never;
+  extendPaths?: string[];
+  pluginPaths?: string[];
+};
+
+export type PreprocessorsConfig = {
+  oas3?: Oas3PreprocessorsSet;
+  oas2?: Oas2PreprocessorsSet;
+};
+
+export type DecoratorsConfig = {
+  oas3?: Oas3DecoratorsSet;
+  oas2?: Oas2DecoratorsSet;
+};
+
+export type TypesExtensionFn = (
+  types: Record<string, NodeType>,
+  oasVersion: OasVersion,
+) => Record<string, NodeType>;
+
+export type TypeExtensionsConfig = Partial<Record<OasMajorVersion, TypesExtensionFn>>;
+
+export type CustomRulesConfig = {
+  oas3?: Oas3RuleSet;
+  oas2?: Oas2RuleSet;
+};
+
+export type Plugin = {
+  id: string;
+  configs?: Record<string, PluginLintConfig>;
+  rules?: CustomRulesConfig;
+  preprocessors?: PreprocessorsConfig;
+  decorators?: DecoratorsConfig;
+  typeExtension?: TypeExtensionsConfig;
+};
+
+export type PluginLintConfig = Omit<LintRawConfig, 'plugins' | 'extends'>;
+
+export type ResolveHeader =
+  | {
+      name: string;
+      envVariable?: undefined;
+      value: string;
+      matches: string;
+    }
+  | {
+      name: string;
+      value?: undefined;
+      envVariable: string;
+      matches: string;
+    };
+
+export type RawResolveConfig = {
+  http?: Partial<HttpResolveConfig>;
+};
+
+export type HttpResolveConfig = {
+  headers: ResolveHeader[];
+  customFetch?: Function;
+};
+
+export type ResolveConfig = {
+  http: HttpResolveConfig;
+};
+
+export type Region = 'us' | 'eu';
+
+export type AccessTokens = { [region in Region]?: string };
+
+export type DeprecatedRawConfig = {
+  apiDefinitions?: Record<string, string>;
+  lint?: LintRawConfig;
+  resolve?: RawResolveConfig;
+  region?: Region;
+  referenceDocs?: Record<string, any>;
+};
+
+export type Api = {
+  root: string;
+  lint?: Omit<LintRawConfig, 'plugins'>;
+  'features.openapi'?: Record<string, any>;
+  'features.mockServer'?: Record<string, any>;
+};
+export type ResolvedApi = Omit<Api, 'lint'> & { lint: Omit<ResolvedLintConfig, 'plugins'>};
+
+export type RawConfig = {
+  apis?: Record<string, Api>;
+  lint?: LintRawConfig;
+  resolve?: RawResolveConfig;
+  region?: Region;
+  'features.openapi'?: Record<string, any>;
+  'features.mockServer'?: Record<string, any>;
+  organization?: string;
+};
+
+export type ResolvedConfig = Omit<RawConfig, 'lint' | 'apis'> & {
+  lint: ResolvedLintConfig;
+  apis: Record<string,ResolvedApi>
+};
+
+export type RulesFields =
+  | 'rules'
+  | 'oas2Rules'
+  | 'oas3_0Rules'
+  | 'oas3_1Rules'
+  | 'preprocessors'
+  | 'oas2Preprocessors'
+  | 'oas3_0Preprocessors'
+  | 'oas3_1Preprocessors'
+  | 'decorators'
+  | 'oas2Decorators'
+  | 'oas3_0Decorators'
+  | 'oas3_1Decorators';

package/src/config/utils.ts

@@ -0,0 +1,208 @@
+import { green, yellow } from 'colorette';
+import { assignExisting } from '../utils';
+import { Config } from './config';
+
+import type {
+  Api,
+  DeprecatedRawConfig,
+  Plugin,
+  RawConfig,
+  RawResolveConfig,
+  ResolveConfig,
+  ResolvedLintConfig,
+  RulesFields,
+} from './types';
+
+export function parsePresetName(presetName: string): { pluginId: string; configName: string } {
+  if (presetName.indexOf('/') > -1) {
+    const [pluginId, configName] = presetName.split('/');
+    return { pluginId, configName };
+  } else {
+    return { pluginId: '', configName: presetName };
+  }
+}
+
+export function transformApiDefinitionsToApis(
+  apiDefinitions: Record<string, string> = {},
+): Record<string, Api> {
+  let apis: Record<string, Api> = {};
+  for (const [apiName, apiPath] of Object.entries(apiDefinitions)) {
+    apis[apiName] = { root: apiPath };
+  }
+  return apis;
+}
+
+export function prefixRules<T extends Record<string, any>>(rules: T, prefix: string) {
+  if (!prefix) return rules;
+
+  const res: any = {};
+  for (const name of Object.keys(rules)) {
+    res[`${prefix}/${name}`] = rules[name];
+  }
+
+  return res;
+}
+
+export function mergeExtends(rulesConfList: ResolvedLintConfig[]) {
+  const result: Omit<ResolvedLintConfig, RulesFields> &
+    Required<Pick<ResolvedLintConfig, RulesFields>> = {
+    rules: {},
+    oas2Rules: {},
+    oas3_0Rules: {},
+    oas3_1Rules: {},
+
+    preprocessors: {},
+    oas2Preprocessors: {},
+    oas3_0Preprocessors: {},
+    oas3_1Preprocessors: {},
+
+    decorators: {},
+    oas2Decorators: {},
+    oas3_0Decorators: {},
+    oas3_1Decorators: {},
+
+    plugins: [],
+    pluginPaths: [],
+    extendPaths: [],
+  };
+
+  for (let rulesConf of rulesConfList) {
+    if (rulesConf.extends) {
+      throw new Error(
+        `\`extends\` is not supported in shared configs yet: ${JSON.stringify(
+          rulesConf,
+          null,
+          2,
+        )}.`,
+      );
+    }
+
+    Object.assign(result.rules, rulesConf.rules);
+    Object.assign(result.oas2Rules, rulesConf.oas2Rules);
+    assignExisting(result.oas2Rules, rulesConf.rules || {});
+    Object.assign(result.oas3_0Rules, rulesConf.oas3_0Rules);
+    assignExisting(result.oas3_0Rules, rulesConf.rules || {});
+    Object.assign(result.oas3_1Rules, rulesConf.oas3_1Rules);
+    assignExisting(result.oas3_1Rules, rulesConf.rules || {});
+
+    Object.assign(result.preprocessors, rulesConf.preprocessors);
+    Object.assign(result.oas2Preprocessors, rulesConf.oas2Preprocessors);
+    assignExisting(result.oas2Preprocessors, rulesConf.preprocessors || {});
+    Object.assign(result.oas3_0Preprocessors, rulesConf.oas3_0Preprocessors);
+    assignExisting(result.oas3_0Preprocessors, rulesConf.preprocessors || {});
+    Object.assign(result.oas3_1Preprocessors, rulesConf.oas3_1Preprocessors);
+    assignExisting(result.oas3_1Preprocessors, rulesConf.preprocessors || {});
+
+    Object.assign(result.decorators, rulesConf.decorators);
+    Object.assign(result.oas2Decorators, rulesConf.oas2Decorators);
+    assignExisting(result.oas2Decorators, rulesConf.decorators || {});
+    Object.assign(result.oas3_0Decorators, rulesConf.oas3_0Decorators);
+    assignExisting(result.oas3_0Decorators, rulesConf.decorators || {});
+    Object.assign(result.oas3_1Decorators, rulesConf.oas3_1Decorators);
+    assignExisting(result.oas3_1Decorators, rulesConf.decorators || {});
+
+    result.plugins!.push(...(rulesConf.plugins || []));
+    result.pluginPaths!.push(...(rulesConf.pluginPaths || []));
+    result.extendPaths!.push(...new Set(rulesConf.extendPaths));
+  }
+
+  return result;
+}
+
+export function getMergedConfig(config: Config, entrypointAlias?: string): Config {
+  const extendPaths = [
+    ...Object.values(config.apis).map((api) => api?.lint?.extendPaths),
+    config.rawConfig?.lint?.extendPaths,
+  ]
+    .flat()
+    .filter(Boolean) as string[];
+
+  const pluginPaths = [
+    ...Object.values(config.apis).map((api) => api?.lint?.pluginPaths),
+    config.rawConfig?.lint?.pluginPaths,
+  ]
+    .flat()
+    .filter(Boolean) as string[];
+
+  return entrypointAlias
+    ? new Config(
+        {
+          ...config.rawConfig,
+          lint: {
+            ...(config.apis[entrypointAlias]
+              ? config.apis[entrypointAlias].lint
+              : config.rawConfig.lint),
+            extendPaths,
+            pluginPaths,
+          },
+          'features.openapi': {
+            ...config['features.openapi'],
+            ...config.apis[entrypointAlias]?.['features.openapi'],
+          },
+          'features.mockServer': {
+            ...config['features.mockServer'],
+            ...config.apis[entrypointAlias]?.['features.mockServer'],
+          },
+          // TODO: merge everything else here
+        },
+        config.configFile,
+      )
+    : config;
+}
+
+export function transformConfig(rawConfig: DeprecatedRawConfig | RawConfig): RawConfig {
+  if ((rawConfig as RawConfig).apis && (rawConfig as DeprecatedRawConfig).apiDefinitions) {
+    throw new Error("Do not use 'apiDefinitions' field. Use 'apis' instead.\n");
+  }
+  if (
+    (rawConfig as RawConfig)['features.openapi'] &&
+    (rawConfig as DeprecatedRawConfig).referenceDocs
+  ) {
+    throw new Error("Do not use 'referenceDocs' field. Use 'features.openapi' instead.\n");
+  }
+  const { apiDefinitions, referenceDocs, ...rest } = rawConfig as DeprecatedRawConfig & RawConfig;
+  if (apiDefinitions) {
+    process.stderr.write(
+      `The ${yellow('apiDefinitions')} field is deprecated. Use ${green(
+        'apis',
+      )} instead. Read more about this change: https://redocly.com/docs/api-registry/guides/migration-guide-config-file/#changed-properties\n`,
+    );
+  }
+  if (referenceDocs) {
+    process.stderr.write(
+      `The ${yellow('referenceDocs')} field is deprecated. Use ${green(
+        'features.openapi',
+      )} instead. Read more about this change: https://redocly.com/docs/api-registry/guides/migration-guide-config-file/#changed-properties\n`,
+    );
+  }
+  return {
+    'features.openapi': referenceDocs,
+    apis: transformApiDefinitionsToApis(apiDefinitions),
+    ...rest,
+  };
+}
+
+export function getResolveConfig(resolve?: RawResolveConfig): ResolveConfig {
+  return {
+    http: {
+      headers: resolve?.http?.headers ?? [],
+      customFetch: undefined,
+    },
+  };
+}
+
+export function getUniquePlugins(plugins: Plugin[]): Plugin[] {
+  const seen = new Set();
+  const results = [];
+  for (const p of plugins) {
+    if (!seen.has(p.id)) {
+      results.push(p);
+      seen.add(p.id);
+    } else if (p.id) {
+      process.stderr.write(
+        `Duplicate plugin id "${yellow(p.id)}".\n`,
+      );
+    }
+  }
+  return results;
+}