@redocly/openapi-core 1.0.0 → 1.0.1

package/src/config/types.ts

@@ -0,0 +1,231 @@
+import type { ProblemSeverity, UserContext } from '../walk';
+import type {
+  Oas3PreprocessorsSet,
+  OasMajorVersion,
+  Oas3DecoratorsSet,
+  Oas2RuleSet,
+  Oas2PreprocessorsSet,
+  Oas2DecoratorsSet,
+  Oas3RuleSet,
+  OasVersion,
+} from '../oas-types';
+import type { NodeType } from '../types';
+import { Location } from '../ref-utils';
+import type { SkipFunctionContext } from '../visitors';
+
+export type RuleSeverity = ProblemSeverity | 'off';
+
+export type RuleSettings = { severity: RuleSeverity };
+
+export type PreprocessorSeverity = RuleSeverity | 'on';
+
+export type RuleConfig =
+  | RuleSeverity
+  | ({
+      severity?: ProblemSeverity;
+    } & Record<string, any>);
+
+export type PreprocessorConfig =
+  | PreprocessorSeverity
+  | ({
+      severity?: ProblemSeverity;
+    } & Record<string, any>);
+
+export type DecoratorConfig = PreprocessorConfig;
+
+export type StyleguideRawConfig = {
+  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 ApiStyleguideRawConfig = Omit<StyleguideRawConfig, 'plugins'>;
+
+export type ResolvedStyleguideConfig = PluginStyleguideConfig & {
+  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 AssertionContext = Partial<UserContext> & SkipFunctionContext & { node: any };
+
+export type AssertResult = { message?: string; location?: Location };
+export type CustomFunction = (
+  value: any,
+  options: unknown,
+  baseLocation: Location
+) => AssertResult[];
+
+export type AssertionsConfig = Record<string, CustomFunction>;
+
+export type Plugin = {
+  id: string;
+  configs?: Record<string, PluginStyleguideConfig>;
+  rules?: CustomRulesConfig;
+  preprocessors?: PreprocessorsConfig;
+  decorators?: DecoratorsConfig;
+  typeExtension?: TypeExtensionsConfig;
+  assertions?: AssertionsConfig;
+};
+
+export type PluginStyleguideConfig = Omit<StyleguideRawConfig, '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>;
+  doNotResolveExamples?: boolean;
+};
+
+export type HttpResolveConfig = {
+  headers: ResolveHeader[];
+  customFetch?: Function;
+};
+
+export type ResolveConfig = {
+  http: HttpResolveConfig;
+};
+
+export type Region = 'us' | 'eu';
+export type Telemetry = 'on' | 'off';
+
+export type AccessTokens = { [region in Region]?: string };
+
+export type DeprecatedInRawConfig = {
+  apiDefinitions?: Record<string, string>;
+  lint?: StyleguideRawConfig;
+  styleguide?: StyleguideRawConfig;
+  referenceDocs?: Record<string, any>;
+  apis?: Record<string, Api & DeprecatedInApi>;
+} & DeprecatedFeaturesConfig;
+
+export type Api = {
+  root: string;
+  styleguide?: ApiStyleguideRawConfig;
+} & ThemeConfig;
+
+export type DeprecatedInApi = {
+  lint?: ApiStyleguideRawConfig;
+} & DeprecatedFeaturesConfig;
+
+export type ResolvedApi = Omit<Api, 'styleguide'> & {
+  styleguide: ResolvedStyleguideConfig;
+  files?: string[];
+};
+
+export type RawConfig = {
+  apis?: Record<string, Api>;
+  styleguide?: StyleguideRawConfig;
+  resolve?: RawResolveConfig;
+  region?: Region;
+  organization?: string;
+  files?: string[];
+  telemetry?: Telemetry;
+} & ThemeConfig;
+
+export type FlatApi = Omit<Api, 'styleguide'> &
+  Omit<ApiStyleguideRawConfig, 'doNotResolveExamples'>;
+
+export type FlatRawConfig = Omit<RawConfig, 'styleguide' | 'resolve' | 'apis'> &
+  Omit<StyleguideRawConfig, 'doNotResolveExamples'> & {
+    resolve?: RawResolveConfig;
+    apis?: Record<string, FlatApi>;
+  } & ThemeRawConfig;
+
+export type ResolvedConfig = Omit<RawConfig, 'apis' | 'styleguide'> & {
+  apis: Record<string, ResolvedApi>;
+  styleguide: ResolvedStyleguideConfig;
+};
+
+type DeprecatedFeaturesConfig = {
+  'features.openapi'?: Record<string, any>;
+  'features.mockServer'?: Record<string, any>;
+};
+
+export type ThemeConfig = {
+  theme?: ThemeRawConfig;
+};
+
+export type ThemeRawConfig = {
+  openapi?: Record<string, any>;
+  mockServer?: Record<string, any>;
+};
+
+export type RulesFields =
+  | 'rules'
+  | 'oas2Rules'
+  | 'oas3_0Rules'
+  | 'oas3_1Rules'
+  | 'preprocessors'
+  | 'oas2Preprocessors'
+  | 'oas3_0Preprocessors'
+  | 'oas3_1Preprocessors'
+  | 'decorators'
+  | 'oas2Decorators'
+  | 'oas3_0Decorators'
+  | 'oas3_1Decorators';
+
+export enum AuthProviderType {
+  OIDC = 'OIDC',
+  SAML2 = 'SAML2',
+  BASIC = 'BASIC',
+}
+
+export enum ApigeeDevOnboardingIntegrationAuthType {
+  SERVICE_ACCOUNT = 'SERVICE_ACCOUNT',
+  OAUTH2 = 'OAUTH2',
+}
+
+export const DEFAULT_TEAM_CLAIM_NAME = 'https://redocly.com/sso/teams';

package/src/config/utils.ts

@@ -0,0 +1,349 @@
+import {
+  assignExisting,
+  isDefined,
+  isTruthy,
+  showErrorForDeprecatedField,
+  showWarningForDeprecatedField,
+} from '../utils';
+import { Config } from './config';
+import type {
+  Api,
+  DeprecatedInApi,
+  DeprecatedInRawConfig,
+  FlatApi,
+  FlatRawConfig,
+  Plugin,
+  RawConfig,
+  RawResolveConfig,
+  ResolveConfig,
+  ResolvedStyleguideConfig,
+  RulesFields,
+  StyleguideRawConfig,
+  ThemeConfig,
+} from './types';
+import { logger, colorize } from '../logger';
+
+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?: DeprecatedInRawConfig['apiDefinitions']
+): Record<string, Api> | undefined {
+  if (!apiDefinitions) return undefined;
+  const apis: Record<string, Api> = {};
+  for (const [apiName, apiPath] of Object.entries(apiDefinitions)) {
+    apis[apiName] = { root: apiPath };
+  }
+  return apis;
+}
+
+function extractFlatConfig<
+  T extends Partial<
+    (Api & DeprecatedInApi & FlatApi) & (DeprecatedInRawConfig & RawConfig & FlatRawConfig)
+  >
+>({
+  plugins,
+  extends: _extends,
+
+  rules,
+  oas2Rules,
+  oas3_0Rules,
+  oas3_1Rules,
+
+  preprocessors,
+  oas2Preprocessors,
+  oas3_0Preprocessors,
+  oas3_1Preprocessors,
+
+  decorators,
+  oas2Decorators,
+  oas3_0Decorators,
+  oas3_1Decorators,
+
+  ...rawConfigRest
+}: T): {
+  styleguideConfig?: StyleguideRawConfig;
+  rawConfigRest: Omit<T, 'plugins' | 'extends' | RulesFields>;
+} {
+  const styleguideConfig = {
+    plugins,
+    extends: _extends,
+
+    rules,
+    oas2Rules,
+    oas3_0Rules,
+    oas3_1Rules,
+
+    preprocessors,
+    oas2Preprocessors,
+    oas3_0Preprocessors,
+    oas3_1Preprocessors,
+
+    decorators,
+    oas2Decorators,
+    oas3_0Decorators,
+    oas3_1Decorators,
+
+    doNotResolveExamples: rawConfigRest.resolve?.doNotResolveExamples,
+  };
+
+  if (
+    (rawConfigRest.lint && rawConfigRest.styleguide) ||
+    (Object.values(styleguideConfig).some(isDefined) &&
+      (rawConfigRest.lint || rawConfigRest.styleguide))
+  ) {
+    throw new Error(
+      `Do not use 'lint', 'styleguide' and flat syntax together. \nSee more about the configuration in the docs: https://redocly.com/docs/cli/configuration/ \n`
+    );
+  }
+
+  return {
+    styleguideConfig: Object.values(styleguideConfig).some(isDefined)
+      ? styleguideConfig
+      : undefined,
+
+    rawConfigRest,
+  };
+}
+
+function transformApis(
+  legacyApis?: Record<string, Api & DeprecatedInApi & FlatApi>
+): Record<string, Api> | undefined {
+  if (!legacyApis) return undefined;
+  const apis: Record<string, Api> = {};
+  for (const [apiName, { lint, ...apiContent }] of Object.entries(legacyApis)) {
+    const { styleguideConfig, rawConfigRest } = extractFlatConfig(apiContent);
+    apis[apiName] = {
+      styleguide: styleguideConfig || lint,
+      ...rawConfigRest,
+    };
+  }
+  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: ResolvedStyleguideConfig[]) {
+  const result: Omit<ResolvedStyleguideConfig, RulesFields> &
+    Required<Pick<ResolvedStyleguideConfig, RulesFields>> = {
+    rules: {},
+    oas2Rules: {},
+    oas3_0Rules: {},
+    oas3_1Rules: {},
+
+    preprocessors: {},
+    oas2Preprocessors: {},
+    oas3_0Preprocessors: {},
+    oas3_1Preprocessors: {},
+
+    decorators: {},
+    oas2Decorators: {},
+    oas3_0Decorators: {},
+    oas3_1Decorators: {},
+
+    plugins: [],
+    pluginPaths: [],
+    extendPaths: [],
+  };
+
+  for (const 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, apiName?: string): Config {
+  const extendPaths = [
+    ...Object.values(config.apis).map((api) => api?.styleguide?.extendPaths),
+    config.rawConfig?.styleguide?.extendPaths,
+  ]
+    .flat()
+    .filter(isTruthy);
+
+  const pluginPaths = [
+    ...Object.values(config.apis).map((api) => api?.styleguide?.pluginPaths),
+    config.rawConfig?.styleguide?.pluginPaths,
+  ]
+    .flat()
+    .filter(isTruthy);
+
+  return apiName
+    ? new Config(
+        {
+          ...config.rawConfig,
+          styleguide: {
+            ...(config.apis[apiName]
+              ? config.apis[apiName].styleguide
+              : config.rawConfig.styleguide),
+            extendPaths,
+            pluginPaths,
+          },
+          theme: {
+            ...config.rawConfig.theme,
+            ...config.apis[apiName]?.theme,
+          },
+          files: [...config.files, ...(config.apis?.[apiName]?.files ?? [])],
+          // TODO: merge everything else here
+        },
+        config.configFile
+      )
+    : config;
+}
+
+export function checkForDeprecatedFields(
+  deprecatedField: keyof (DeprecatedInRawConfig & RawConfig),
+  updatedField: keyof FlatRawConfig | undefined,
+  rawConfig: DeprecatedInRawConfig & RawConfig & FlatRawConfig,
+  updatedObject: keyof FlatRawConfig | undefined
+): void {
+  const isDeprecatedFieldInApis =
+    rawConfig.apis &&
+    Object.values(rawConfig.apis).some(
+      (api: Api & FlatApi & DeprecatedInApi & DeprecatedInRawConfig & RawConfig & FlatRawConfig) =>
+        api[deprecatedField]
+    );
+
+  if (rawConfig[deprecatedField] && updatedField === null) {
+    showWarningForDeprecatedField(deprecatedField);
+  }
+
+  if (rawConfig[deprecatedField] && updatedField && rawConfig[updatedField]) {
+    showErrorForDeprecatedField(deprecatedField, updatedField);
+  }
+
+  if (rawConfig[deprecatedField] && updatedObject && rawConfig[updatedObject]) {
+    showErrorForDeprecatedField(deprecatedField, updatedField, updatedObject);
+  }
+
+  if (rawConfig[deprecatedField] || isDeprecatedFieldInApis) {
+    showWarningForDeprecatedField(deprecatedField, updatedField, updatedObject);
+  }
+}
+
+export function transformConfig(
+  rawConfig: DeprecatedInRawConfig & RawConfig & FlatRawConfig
+): RawConfig {
+  const migratedFields: [
+    keyof (DeprecatedInRawConfig & RawConfig),
+    keyof FlatRawConfig | undefined,
+    keyof ThemeConfig | undefined
+  ][] = [
+    ['apiDefinitions', 'apis', undefined],
+    ['referenceDocs', 'openapi', 'theme'],
+    ['lint', undefined, undefined],
+    ['styleguide', undefined, undefined],
+    ['features.openapi', 'openapi', 'theme'],
+  ];
+
+  for (const [deprecatedField, updatedField, updatedObject] of migratedFields) {
+    checkForDeprecatedFields(deprecatedField, updatedField, rawConfig, updatedObject);
+  }
+
+  const { apis, apiDefinitions, referenceDocs, lint, ...rest } = rawConfig;
+
+  const { styleguideConfig, rawConfigRest } = extractFlatConfig(rest);
+
+  const transformedConfig: RawConfig = {
+    theme: {
+      openapi: {
+        ...referenceDocs,
+        ...rawConfig['features.openapi'],
+        ...rawConfig.theme?.openapi,
+      },
+      mockServer: {
+        ...rawConfig['features.mockServer'],
+        ...rawConfig.theme?.mockServer,
+      },
+    },
+    apis: transformApis(apis) || transformApiDefinitionsToApis(apiDefinitions),
+    styleguide: styleguideConfig || lint,
+    ...rawConfigRest,
+  };
+  showDeprecationMessages(transformedConfig);
+  return transformedConfig;
+}
+
+function showDeprecationMessages(config: RawConfig) {
+  let allRules = { ...config.styleguide?.rules };
+  for (const api of Object.values(config.apis || {})) {
+    allRules = { ...allRules, ...api?.styleguide?.rules };
+  }
+  for (const ruleKey of Object.keys(allRules)) {
+    if (ruleKey.startsWith('assert/')) {
+      logger.warn(
+        `\nThe 'assert/' syntax in ${ruleKey} is deprecated. Update your configuration to use 'rule/' instead. Examples and more information: https://redocly.com/docs/cli/rules/configurable-rules/\n`
+      );
+    }
+  }
+}
+
+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) {
+      logger.warn(`Duplicate plugin id "${colorize.red(p.id)}".\n`);
+    }
+  }
+  return results;
+}