@redocly/cli 1.0.0-beta.96

package/src/commands/split/index.ts

@@ -0,0 +1,349 @@
+import { red, blue, yellow, green } from 'colorette';
+import * as fs from 'fs';
+import { parseYaml, slash, isRef } from '@redocly/openapi-core';
+import * as path from 'path';
+import { performance } from 'perf_hooks';
+const isEqual = require('lodash.isequal');
+
+import { printExecutionTime, pathToFilename, readYaml, writeYaml, exitWithError } from '../../utils';
+import { isString, isObject, isEmptyObject } from '../../js-utils';
+import {
+  Definition,
+  Oas2Definition,
+  Oas3Schema,
+  Oas3Definition,
+  Oas3_1Definition,
+  Oas3Components,
+  Oas3ComponentName,
+  ComponentsFiles,
+  refObj,
+  Oas3PathItem,
+  OPENAPI3_COMPONENT,
+  COMPONENTS,
+  componentsPath,
+  OPENAPI3_METHOD_NAMES,
+  OPENAPI3_COMPONENT_NAMES,
+  Referenced
+} from './types';
+
+export async function handleSplit (argv: {
+  entrypoint: string;
+  outDir: string
+  separator: string
+}) {
+  const startedAt = performance.now();
+  const { entrypoint, outDir, separator } = argv;
+  validateDefinitionFileName(entrypoint!);
+  const openapi = readYaml(entrypoint!) as Oas3Definition | Oas3_1Definition;
+  splitDefinition(openapi, outDir, separator);
+  process.stderr.write(
+    `🪓 Document: ${blue(entrypoint!)} ${green('is successfully split')}
+    and all related files are saved to the directory: ${blue(outDir)} \n`,
+  );
+  printExecutionTime('split', startedAt, entrypoint!);
+}
+
+function splitDefinition(openapi: Oas3Definition | Oas3_1Definition, openapiDir: string, pathSeparator: string) {
+  fs.mkdirSync(openapiDir, { recursive: true });
+
+  const componentsFiles: ComponentsFiles = {};
+  iterateComponents(openapi, openapiDir, componentsFiles);
+  iteratePathItems(openapi.paths, openapiDir, path.join(openapiDir, 'paths'), componentsFiles, pathSeparator);
+  const webhooks = (openapi as Oas3_1Definition).webhooks || (openapi as Oas3Definition)['x-webhooks'];
+  // use webhook_ prefix for code samples to prevent potential name-clashes with paths samples
+  iteratePathItems(webhooks, openapiDir, path.join(openapiDir, 'webhooks'), componentsFiles, pathSeparator, 'webhook_');
+
+  replace$Refs(openapi, openapiDir, componentsFiles);
+  writeYaml(openapi, path.join(openapiDir, 'openapi.yaml'));
+}
+
+function isStartsWithComponents(node: string) {
+  return node.startsWith(componentsPath)
+}
+
+function isNotYaml(filename: string) {
+  return !(filename.endsWith('.yaml') || filename.endsWith('.yml'));
+}
+
+function loadFile(fileName: string) {
+  try {
+    return parseYaml(fs.readFileSync(fileName, 'utf8')) as Definition;
+  } catch (e) {
+    return exitWithError(e.message);
+  }
+}
+
+function validateDefinitionFileName(fileName: string) {
+  if (!fs.existsSync(fileName)) exitWithError(`File ${blue(fileName)} does not exist \n`);
+  const file = loadFile(fileName);
+  if ((file as Oas2Definition).swagger) exitWithError('OpenAPI 2 is not supported by this command');
+  if (!(file as Oas3Definition | Oas3_1Definition).openapi) exitWithError('File does not conform to the OpenAPI Specification. OpenAPI version is not specified');
+  return true;
+}
+
+function langToExt(lang: string) {
+  const langObj: any = {
+    php: '.php',
+    'c#': '.cs',
+    shell: '.sh',
+    curl: '.sh',
+    bash: '.sh',
+    javascript: '.js',
+    js: '.js',
+    python: '.py'
+  }
+  return langObj[lang];
+}
+
+function traverseDirectoryDeep(directory: string, callback: any, componentsFiles: object) {
+  if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) return;
+  const files = fs.readdirSync(directory);
+  for (const f of files) {
+    const filename = path.join(directory, f);
+    if (fs.statSync(filename).isDirectory()) {
+      traverseDirectoryDeep(filename, callback, componentsFiles);
+    } else {
+      callback(filename, directory, componentsFiles);
+    }
+  }
+}
+
+function traverseDirectoryDeepCallback(
+  filename: string,
+  directory: string,
+  componentsFiles: object,
+) {
+  if (isNotYaml(filename)) return;
+  const pathData = readYaml(filename);
+  replace$Refs(pathData, directory, componentsFiles);
+  writeYaml(pathData, filename);
+}
+
+function crawl(object: any, visitor: any) {
+  if (!isObject(object)) return;
+  for (const key of Object.keys(object)) {
+    visitor(object, key);
+    crawl(object[key], visitor);
+  }
+}
+
+function replace$Refs(
+  obj: any,
+  relativeFrom: string,
+  componentFiles = {} as ComponentsFiles
+) {
+  crawl(obj, (node: any) => {
+    if (node.$ref && isString(node.$ref) && isStartsWithComponents(node.$ref)) {
+      replace(node, '$ref');
+    } else if (
+      node.discriminator &&
+      node.discriminator.mapping &&
+      isObject(node.discriminator.mapping)
+    ) {
+      const { mapping } = node.discriminator;
+      for (const name of Object.keys(mapping)) {
+        if (isString(mapping[name]) && isStartsWithComponents(mapping[name])) {
+          replace(node.discriminator.mapping, name);
+        }
+      }
+    }
+  });
+
+  function replace(node: refObj, key: string) {
+    const splittedNode = node[key].split('/');
+    const name = splittedNode.pop();
+    const groupName = splittedNode[2];
+    const filesGroupName = componentFiles[groupName];
+    if (!filesGroupName || !filesGroupName[name!]) return;
+    let filename = path.relative(relativeFrom, filesGroupName[name!].filename);
+    if (!filename.startsWith('.')) { filename = '.' + path.sep + filename; }
+    node[key] = filename;
+  }
+}
+
+function implicitlyReferenceDiscriminator(
+  obj: any,
+  defName: string,
+  filename: string,
+  schemaFiles: any
+) {
+  if (!obj.discriminator) return;
+  const defPtr = `#/${COMPONENTS}/${OPENAPI3_COMPONENT.Schemas}/${defName}`;
+  const implicitMapping = {} as any;
+  for (const [name, { inherits, filename: parentFilename }] of Object.entries(schemaFiles) as any) {
+    if (inherits.indexOf(defPtr) > -1) {
+      const res = path.relative(path.dirname(filename), parentFilename);
+      implicitMapping[name] = res.startsWith('.') ? res : '.' + path.sep + res;
+    }
+  }
+
+  if (isEmptyObject(implicitMapping)) return;
+  const discriminatorPropSchema = obj.properties[obj.discriminator.propertyName];
+  const discriminatorEnum = discriminatorPropSchema && discriminatorPropSchema.enum;
+  const mapping = (obj.discriminator.mapping = obj.discriminator.mapping || {});
+  for (const name of Object.keys(implicitMapping)) {
+    if (discriminatorEnum && !discriminatorEnum.includes(name)) { continue; }
+    if (mapping[name] && mapping[name] !== implicitMapping[name]) {
+      process.stderr.write(yellow(
+        `warning: explicit mapping overlaps with local mapping entry ${red(name)} at ${blue(filename)}. Please check it.`
+      ));
+    }
+    mapping[name] = implicitMapping[name];
+  }
+}
+
+function isNotSecurityComponentType(componentType: string) {
+  return componentType !== OPENAPI3_COMPONENT.SecuritySchemes
+}
+
+function findComponentTypes(components: any) {
+  return OPENAPI3_COMPONENT_NAMES
+    .filter(item => isNotSecurityComponentType(item) && Object.keys(components).includes(item))
+}
+
+function doesFileDiffer(filename: string, componentData: any) {
+  return fs.existsSync(filename) && !isEqual(readYaml(filename), componentData);
+}
+
+function removeEmptyComponents(openapi: Oas3Definition | Oas3_1Definition, componentType: Oas3ComponentName) {
+  if (openapi.components && isEmptyObject(openapi.components[componentType])) {
+    delete openapi.components[componentType];
+  }
+  if (isEmptyObject(openapi.components)) {
+    delete openapi.components;
+  }
+}
+
+function createComponentDir(componentDirPath: string, componentType: string) {
+  if (isNotSecurityComponentType(componentType)) {
+    fs.mkdirSync(componentDirPath, { recursive: true });
+  }
+}
+
+function extractFileNameFromPath(filename: string) {
+  return path.basename(filename, path.extname(filename));
+}
+
+function getFileNamePath(componentDirPath: string, componentName: string) {
+  return path.join(componentDirPath, componentName) + '.yaml';
+}
+
+function gatherComponentsFiles(
+  components: Oas3Components,
+  componentsFiles: ComponentsFiles,
+  componentType: Oas3ComponentName,
+  componentName: string,
+  filename: string
+) {
+  let inherits = [];
+  if (componentType === OPENAPI3_COMPONENT.Schemas) {
+    inherits = ((components?.[componentType]?.[componentName] as Oas3Schema)?.allOf || []).map((s: any) => s.$ref).filter(Boolean);
+  }
+  componentsFiles[componentType] = componentsFiles[componentType] || {};
+  componentsFiles[componentType][componentName] = { inherits, filename };
+}
+
+function iteratePathItems(
+  pathItems: Record<string,  Referenced<Oas3PathItem>> | undefined,
+  openapiDir: string,
+  outDir: string,
+  componentsFiles: object,
+  pathSeparator: string,
+  codeSamplesPathPrefix: string = '',
+) {
+  if (!pathItems) return;
+  fs.mkdirSync(outDir, { recursive: true });
+
+  for (const pathName of Object.keys(pathItems)) {
+    const pathFile = `${path.join(outDir, pathToFilename(pathName, pathSeparator))}.yaml`;
+    const pathData = pathItems[pathName] as Oas3PathItem;
+
+    if (isRef(pathData)) continue;
+    
+    for (const method of OPENAPI3_METHOD_NAMES) {
+      const methodData = pathData[method];
+      const methodDataXCode = methodData?.['x-code-samples'] || methodData?.['x-codeSamples'];
+      if (!methodDataXCode || !Array.isArray(methodDataXCode)) {
+        continue;
+      }
+      for (const sample of methodDataXCode) {
+        if (sample.source && (sample.source as any).$ref) continue;
+        const sampleFileName = path.join(
+          openapiDir,
+          'code_samples',
+          sample.lang,
+          codeSamplesPathPrefix + pathToFilename(pathName, pathSeparator),
+          method + langToExt(sample.lang),
+        );
+
+        fs.mkdirSync(path.dirname(sampleFileName), { recursive: true });
+        fs.writeFileSync(sampleFileName, sample.source);
+        // @ts-ignore
+        sample.source = {
+          $ref: slash(path.relative(outDir, sampleFileName))
+        };
+      }
+    }
+    writeYaml(pathData, pathFile);
+    pathItems[pathName] = {
+      $ref: slash(path.relative(openapiDir, pathFile))
+    };
+
+    traverseDirectoryDeep(outDir, traverseDirectoryDeepCallback, componentsFiles);
+  }
+}
+
+function iterateComponents(
+  openapi: Oas3Definition | Oas3_1Definition,
+  openapiDir: string,
+  componentsFiles: ComponentsFiles
+) {
+  const { components } = openapi;
+  if (components) {
+    const componentsDir = path.join(openapiDir, COMPONENTS);
+    fs.mkdirSync(componentsDir, { recursive: true });
+    const componentTypes = findComponentTypes(components);
+    componentTypes.forEach(iterateAndGatherComponentsFiles);
+    componentTypes.forEach(iterateComponentTypes);
+
+    function iterateAndGatherComponentsFiles(componentType: Oas3ComponentName) {
+      const componentDirPath = path.join(componentsDir, componentType);
+      for (const componentName of Object.keys(components?.[componentType] || {})) {
+        const filename = getFileNamePath(componentDirPath, componentName);
+        gatherComponentsFiles(components!, componentsFiles, componentType, componentName, filename);
+      }
+    }
+
+    function iterateComponentTypes(componentType: Oas3ComponentName) {
+      const componentDirPath = path.join(componentsDir, componentType);
+      createComponentDir(componentDirPath, componentType);
+      for (const componentName of Object.keys(components?.[componentType] || {})) {
+        const filename = getFileNamePath(componentDirPath, componentName);
+        const componentData = components?.[componentType]?.[componentName];
+        replace$Refs(componentData, path.dirname(filename), componentsFiles);
+        implicitlyReferenceDiscriminator(
+          componentData,
+          extractFileNameFromPath(filename),
+          filename,
+          componentsFiles.schemas || {}
+        );
+
+        if (doesFileDiffer(filename, componentData)) {
+          process.stderr.write(yellow(
+            `warning: conflict for ${componentName} - file already exists with different content: ${blue(filename)} ... Skip.\n`
+          ));
+        } else {
+          writeYaml(componentData, filename);
+        }
+
+        if (isNotSecurityComponentType(componentType)) {
+          // security schemas must referenced from components
+          delete openapi.components?.[componentType]?.[componentName];
+        }
+      }
+      removeEmptyComponents(openapi, componentType);
+    }
+  }
+}
+
+export { iteratePathItems };

package/src/commands/split/types.ts

@@ -0,0 +1,73 @@
+import {
+  Oas3Schema,
+  Oas3_1Schema,
+  Oas3Definition,
+  Oas3_1Definition,
+  Oas3Components,
+  Oas3PathItem,
+  Oas3Paths,
+  Oas3ComponentName,
+  Oas3_1Webhooks,
+  Oas2Definition,
+  Referenced
+} from "@redocly/openapi-core";
+export { Oas3_1Definition, Oas3Definition, Oas2Definition, Oas3Components, Oas3Paths, Oas3PathItem, Oas3ComponentName, Oas3_1Schema, Oas3Schema, Oas3_1Webhooks, Referenced }
+export type Definition = Oas3_1Definition | Oas3Definition | Oas2Definition;
+export interface ComponentsFiles {
+  [schemas: string]: any;
+}
+export interface refObj {
+  [$ref: string]: string;
+}
+
+export const COMPONENTS = 'components';
+export const PATHS = 'paths';
+export const WEBHOOKS = 'webhooks';
+export const xWEBHOOKS = 'x-webhooks';
+export const componentsPath = `#/${COMPONENTS}/`;
+
+enum OPENAPI3_METHOD {
+  Get = 'get',
+  Put = 'put',
+  Post = 'post',
+  Delete = 'delete',
+  Options = 'options',
+  Head = 'head',
+  Patch = 'patch',
+  Trace = 'trace'
+}
+
+export const OPENAPI3_METHOD_NAMES: OPENAPI3_METHOD[] = [
+  OPENAPI3_METHOD.Get,
+  OPENAPI3_METHOD.Put,
+  OPENAPI3_METHOD.Post,
+  OPENAPI3_METHOD.Delete,
+  OPENAPI3_METHOD.Options,
+  OPENAPI3_METHOD.Head,
+  OPENAPI3_METHOD.Patch,
+  OPENAPI3_METHOD.Trace
+];
+
+export enum OPENAPI3_COMPONENT {
+  Schemas = 'schemas',
+  Responses = 'responses',
+  Parameters = 'parameters',
+  Examples = 'examples',
+  Headers = 'headers',
+  RequestBodies = 'requestBodies',
+  Links = 'links',
+  Callbacks = 'callbacks',
+  SecuritySchemes = 'securitySchemes'
+}
+
+export const OPENAPI3_COMPONENT_NAMES: OPENAPI3_COMPONENT[] = [
+  OPENAPI3_COMPONENT.RequestBodies,
+  OPENAPI3_COMPONENT.Schemas,
+  OPENAPI3_COMPONENT.Responses,
+  OPENAPI3_COMPONENT.Parameters,
+  OPENAPI3_COMPONENT.Examples,
+  OPENAPI3_COMPONENT.Headers,
+  OPENAPI3_COMPONENT.Links,
+  OPENAPI3_COMPONENT.Callbacks,
+  OPENAPI3_COMPONENT.SecuritySchemes
+];

package/src/commands/stats.ts

@@ -0,0 +1,115 @@
+import { performance } from 'perf_hooks';
+import * as colors from 'colorette';
+import {
+  Config,
+  LintConfig,
+  loadConfig,
+  normalizeTypes,
+  Oas3Types,
+  Oas2Types,
+  StatsAccumulator,
+  StatsName,
+  BaseResolver,
+  resolveDocument,
+  detectOpenAPI,
+  OasMajorVersion,
+  openAPIMajor,
+  normalizeVisitors,
+  WalkContext,
+  walkDocument,
+  Stats,
+  bundle
+} from '@redocly/openapi-core';
+
+import { getFallbackEntryPointsOrExit } from '../utils'
+import { printExecutionTime } from '../utils';
+
+const statsAccumulator: StatsAccumulator = {
+  refs: { metric: '🚗 References', total: 0, color: 'red', items: new Set() },
+  externalDocs: { metric: '📦 External Documents', total: 0, color: 'magenta' },
+  schemas: { metric: '📈 Schemas', total: 0, color: 'white'},
+  parameters: { metric: '👉 Parameters', total: 0, color: 'yellow', items: new Set() },
+  links: { metric: '🔗 Links', total: 0, color: 'cyan', items: new Set() },
+  pathItems: { metric: '➡️ Path Items', total: 0, color: 'green' },
+  operations: { metric: '👷 Operations', total: 0, color: 'yellow' },
+  tags: { metric: '🔖 Tags', total: 0, color: 'white', items: new Set() },
+}
+
+function printStatsStylish(statsAccumulator: StatsAccumulator) {
+  for (const node in statsAccumulator) {
+    const { metric, total, color } = statsAccumulator[node as StatsName];
+    process.stderr.write(colors[color](`${metric}: ${total} \n`));
+  }
+}
+
+function printStatsJson(statsAccumulator: StatsAccumulator) {
+  const json: any = {};
+  for (const key of Object.keys(statsAccumulator)) {
+    json[key] = {
+      metric: statsAccumulator[key as StatsName].metric,
+      total: statsAccumulator[key as StatsName].total,
+    }
+  }
+  process.stdout.write(JSON.stringify(json, null, 2));
+}
+
+function printStats(statsAccumulator: StatsAccumulator, entrypoint: string, format: string) {
+  process.stderr.write(`Document: ${colors.magenta(entrypoint)} stats:\n\n`);
+  switch (format) {
+    case 'stylish': printStatsStylish(statsAccumulator); break;
+    case 'json': printStatsJson(statsAccumulator); break;
+  }
+}
+
+export async function handleStats (argv: {
+  config?: string;
+  entrypoint?: string;
+  format: string;
+}) {
+  const config: Config = await loadConfig(argv.config);
+  const [{ path }] = await getFallbackEntryPointsOrExit(argv.entrypoint ? [argv.entrypoint] : [], config);
+  const externalRefResolver = new BaseResolver(config.resolve);
+  const { bundle: document } = await bundle({ config, ref: path });
+  const lintConfig: LintConfig = config.lint;
+  const oasVersion = detectOpenAPI(document.parsed);
+  const oasMajorVersion = openAPIMajor(oasVersion);
+  const types = normalizeTypes(
+    lintConfig.extendTypes(
+      oasMajorVersion === OasMajorVersion.Version3 ? Oas3Types : Oas2Types,
+      oasVersion,
+    ),
+    lintConfig
+  );
+
+  const startedAt = performance.now();
+  const ctx: WalkContext = {
+    problems: [],
+    oasVersion: oasVersion,
+    visitorsData: {},
+  }
+
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.DefinitionRoot,
+    externalRefResolver,
+  });
+
+  const statsVisitor = normalizeVisitors([{
+    severity: 'warn',
+    ruleId: 'stats',
+    visitor: Stats(statsAccumulator)
+  }],
+    types
+  );
+
+  walkDocument({
+    document,
+    rootType: types.DefinitionRoot,
+    normalizedVisitors: statsVisitor,
+    resolvedRefMap,
+    ctx,
+  });
+
+  printStats(statsAccumulator, path, argv.format);
+  printExecutionTime('stats', startedAt, path);
+}