@redocly/cli 1.0.0 → 1.0.1

package/src/commands/split/__tests__/index.test.ts

@@ -0,0 +1,137 @@
+import { iteratePathItems, handleSplit } from '../index';
+import * as path from 'path';
+import * as openapiCore from '@redocly/openapi-core';
+import { ComponentsFiles } from '../types';
+import { blue, green } from 'colorette';
+
+const utils = require('../../../utils');
+
+jest.mock('../../../utils', () => ({
+  ...jest.requireActual('../../../utils'),
+  writeYaml: jest.fn(),
+}));
+
+jest.mock('@redocly/openapi-core', () => ({
+  ...jest.requireActual('@redocly/openapi-core'),
+  isRef: jest.fn(),
+}));
+
+describe('#split', () => {
+  const openapiDir = 'test';
+  const componentsFiles: ComponentsFiles = {};
+
+  it('should split the file and show the success message', async () => {
+    const filePath = 'packages/cli/src/commands/split/__tests__/fixtures/spec.json';
+    jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    await handleSplit({
+      api: filePath,
+      outDir: openapiDir,
+      separator: '_',
+    });
+
+    expect(process.stderr.write).toBeCalledTimes(2);
+    expect((process.stderr.write as jest.Mock).mock.calls[0][0]).toBe(
+      `🪓 Document: ${blue(filePath!)} ${green('is successfully split')}
+    and all related files are saved to the directory: ${blue(openapiDir)} \n`
+    );
+    expect((process.stderr.write as jest.Mock).mock.calls[1][0]).toContain(
+      `${filePath}: split processed in <test>ms`
+    );
+  });
+
+  it('should use the correct separator', async () => {
+    const filePath = 'packages/cli/src/commands/split/__tests__/fixtures/spec.json';
+
+    jest.spyOn(utils, 'pathToFilename').mockImplementation(() => 'newFilePath');
+
+    await handleSplit({
+      api: filePath,
+      outDir: openapiDir,
+      separator: '_',
+    });
+
+    expect(utils.pathToFilename).toBeCalledWith(expect.anything(), '_');
+    utils.pathToFilename.mockRestore();
+  });
+
+  it('should have correct path with paths', () => {
+    const openapi = require('./fixtures/spec.json');
+
+    jest.spyOn(openapiCore, 'slash').mockImplementation(() => 'paths/test.yaml');
+    jest.spyOn(path, 'relative').mockImplementation(() => 'paths/test.yaml');
+    iteratePathItems(
+      openapi.paths,
+      openapiDir,
+      path.join(openapiDir, 'paths'),
+      componentsFiles,
+      '_'
+    );
+
+    expect(openapiCore.slash).toHaveBeenCalledWith('paths/test.yaml');
+    expect(path.relative).toHaveBeenCalledWith('test', 'test/paths/test.yaml');
+  });
+
+  it('should have correct path with webhooks', () => {
+    const openapi = require('./fixtures/webhooks.json');
+
+    jest.spyOn(openapiCore, 'slash').mockImplementation(() => 'webhooks/test.yaml');
+    jest.spyOn(path, 'relative').mockImplementation(() => 'webhooks/test.yaml');
+    iteratePathItems(
+      openapi.webhooks,
+      openapiDir,
+      path.join(openapiDir, 'webhooks'),
+      componentsFiles,
+      'webhook_'
+    );
+
+    expect(openapiCore.slash).toHaveBeenCalledWith('webhooks/test.yaml');
+    expect(path.relative).toHaveBeenCalledWith('test', 'test/webhooks/test.yaml');
+  });
+
+  it('should have correct path with x-webhooks', () => {
+    const openapi = require('./fixtures/spec.json');
+
+    jest.spyOn(openapiCore, 'slash').mockImplementation(() => 'webhooks/test.yaml');
+    jest.spyOn(path, 'relative').mockImplementation(() => 'webhooks/test.yaml');
+    iteratePathItems(
+      openapi['x-webhooks'],
+      openapiDir,
+      path.join(openapiDir, 'webhooks'),
+      componentsFiles,
+      'webhook_'
+    );
+
+    expect(openapiCore.slash).toHaveBeenCalledWith('webhooks/test.yaml');
+    expect(path.relative).toHaveBeenCalledWith('test', 'test/webhooks/test.yaml');
+  });
+
+  it('should create correct folder name for code samples', async () => {
+    const openapi = require('./fixtures/samples.json');
+
+    const fs = require('fs');
+    jest.spyOn(fs, 'writeFileSync').mockImplementation(() => {});
+
+    jest.spyOn(utils, 'escapeLanguageName');
+    iteratePathItems(
+      openapi.paths,
+      openapiDir,
+      path.join(openapiDir, 'paths'),
+      componentsFiles,
+      '_'
+    );
+
+    expect(utils.escapeLanguageName).nthCalledWith(1, 'C#');
+    expect(utils.escapeLanguageName).nthReturnedWith(1, 'C_sharp');
+
+    expect(utils.escapeLanguageName).nthCalledWith(2, 'C/AL');
+    expect(utils.escapeLanguageName).nthReturnedWith(2, 'C_AL');
+
+    expect(utils.escapeLanguageName).nthCalledWith(3, 'Visual Basic');
+    expect(utils.escapeLanguageName).nthReturnedWith(3, 'VisualBasic');
+
+    expect(utils.escapeLanguageName).toBeCalledTimes(3);
+
+    utils.escapeLanguageName.mockRestore();
+  });
+});

package/src/commands/split/index.ts

@@ -0,0 +1,385 @@
+import { red, blue, yellow, green } from 'colorette';
+import * as fs from 'fs';
+import { parseYaml, slash, isRef, isTruthy } from '@redocly/openapi-core';
+import type { OasRef } 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,
+  escapeLanguageName,
+  langToExt,
+} 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 type SplitOptions = {
+  api: string;
+  outDir: string;
+  separator: string;
+  config?: string;
+};
+
+export async function handleSplit(argv: SplitOptions) {
+  const startedAt = performance.now();
+  const { api, outDir, separator } = argv;
+  validateDefinitionFileName(api!);
+  const openapi = readYaml(api!) as Oas3Definition | Oas3_1Definition;
+  splitDefinition(openapi, outDir, separator);
+  process.stderr.write(
+    `🪓 Document: ${blue(api!)} ${green('is successfully split')}
+    and all related files are saved to the directory: ${blue(outDir)} \n`
+  );
+  printExecutionTime('split', startedAt, api!);
+}
+
+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 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: string[] = [];
+  if (componentType === OPENAPI3_COMPONENT.Schemas) {
+    inherits = ((components?.[componentType]?.[componentName] as Oas3Schema)?.allOf || [])
+      .map(({ $ref }) => $ref)
+      .filter(isTruthy);
+  }
+  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 unknown as OasRef).$ref) continue;
+        const sampleFileName = path.join(
+          openapiDir,
+          'code_samples',
+          escapeLanguageName(sample.lang),
+          codeSamplesPathPrefix + pathToFilename(pathName, pathSeparator),
+          method + langToExt(sample.lang)
+        );
+
+        fs.mkdirSync(path.dirname(sampleFileName), { recursive: true });
+        fs.writeFileSync(sampleFileName, sample.source);
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @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);
+
+    // eslint-disable-next-line no-inner-declarations
+    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);
+      }
+    }
+
+    // eslint-disable-next-line no-inner-declarations
+    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,85 @@
+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}/`;
+
+export 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,
+];