@redocly/cli 1.0.0-beta.96

package/src/index.ts

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+
+import './assert-node-version';
+import * as yargs from 'yargs';
+import { outputExtensions, regionChoices } from './types';
+import { RedoclyClient, OutputFormat } from '@redocly/openapi-core';
+import { previewDocs } from './commands/preview-docs';
+import { handleStats } from './commands/stats';
+import { handleSplit } from './commands/split';
+import { handleJoin } from './commands/join';
+import { handlePush, transformPush } from './commands/push';
+import { handleLint } from './commands/lint';
+import { handleBundle } from './commands/bundle';
+import { handleLogin } from './commands/login';
+const version = require('../package.json').version;
+
+yargs
+  .version('version', 'Show version number.', version)
+  .help('help', 'Show help.')
+  .command(
+    'stats [entrypoint]',
+    'Gathering statistics for a document.',
+    (yargs) =>
+      yargs.positional('entrypoint', { type: 'string' }).option({
+        config: { description: 'Specify path to the config file.', type: 'string' },
+        format: {
+          description: 'Use a specific output format.',
+          choices: ['stylish', 'json'] as ReadonlyArray<OutputFormat>,
+          default: 'stylish' as OutputFormat,
+        },
+      }),
+    handleStats,
+  )
+  .command(
+    'split [entrypoint]',
+    'Split definition into a multi-file structure.',
+    (yargs) =>
+      yargs
+        .positional('entrypoint', {
+          description: 'API definition file that you want to split',
+          type: 'string',
+        })
+        .option({
+          outDir: {
+            description: 'Output directory where files will be saved.',
+            required: true,
+            type: 'string',
+          },
+          separator: {
+            description: 'File path separator used while splitting.',
+            required: false,
+            type: 'string',
+            default: '_',
+          },
+        })
+        .demandOption('entrypoint'),
+    handleSplit,
+  )
+  .command(
+    'join [entrypoints...]',
+    'Join definitions [experimental].',
+    (yargs) =>
+      yargs
+        .positional('entrypoints', {
+          array: true,
+          type: 'string',
+          demandOption: true,
+        })
+        .option({
+          lint: { description: 'Lint definitions', type: 'boolean', default: false },
+          'prefix-tags-with-info-prop': {
+            description: 'Prefix tags with property value from info object.',
+            requiresArg: true,
+            type: 'string',
+          },
+          'prefix-tags-with-filename': {
+            description: 'Prefix tags with property value from file name.',
+            type: 'boolean',
+            default: false,
+          },
+          'prefix-components-with-info-prop': {
+            description: 'Prefix components with property value from info object.',
+            requiresArg: true,
+            type: 'string',
+          },
+        }),
+    (argv) => {
+      handleJoin(argv, version);
+    },
+  )
+  .command(
+    'push [maybeEntrypointOrAliasOrDestination] [maybeDestination] [maybeBranchName]',
+    'Push an API definition to the Redocly API registry.',
+    (yargs) =>
+      yargs
+        .positional('maybeEntrypointOrAliasOrDestination', { type: 'string' })
+        .positional('maybeDestination', { type: 'string' })
+        .positional('maybeBranchName', { type: 'string' })
+        .option({
+          branch: { type: 'string', alias: 'b' },
+          upsert: { type: 'boolean', alias: 'u' },
+          'run-id': { type: 'string', requiresArg: true },
+          region: { description: 'Specify a region.', alias: 'r', choices: regionChoices },
+          'skip-decorator': {
+            description: 'Ignore certain decorators.',
+            array: true,
+            type: 'string',
+          },
+        }),
+    transformPush(handlePush),
+  )
+  .command(
+    'lint [entrypoints...]',
+    'Lint definition.',
+    (yargs) =>
+      yargs.positional('entrypoints', { array: true, type: 'string', demandOption: true }).option({
+        format: {
+          description: 'Use a specific output format.',
+          choices: [
+            'stylish',
+            'codeframe',
+            'json',
+            'checkstyle',
+            'codeclimate',
+          ] as ReadonlyArray<OutputFormat>,
+          default: 'codeframe' as OutputFormat,
+        },
+        'max-problems': {
+          requiresArg: true,
+          description: 'Reduce output to max N problems.',
+          type: 'number',
+          default: 100,
+        },
+        'generate-ignore-file': {
+          description: 'Generate ignore file.',
+          type: 'boolean',
+        },
+        'skip-rule': {
+          description: 'Ignore certain rules.',
+          array: true,
+          type: 'string',
+        },
+        'skip-preprocessor': {
+          description: 'Ignore certain preprocessors.',
+          array: true,
+          type: 'string',
+        },
+        config: {
+          description: 'Specify path to the config file.',
+          requiresArg: true,
+          type: 'string',
+        },
+        extends: {
+          description: 'Override extends configurations (defaults or config file settings).',
+          requiresArg: true,
+          array: true,
+          type: 'string',
+        },
+      }),
+    (argv) => {
+      handleLint(argv, version);
+    },
+  )
+  .command(
+    'bundle [entrypoints...]',
+    'Bundle definition.',
+    (yargs) =>
+      yargs.positional('entrypoints', { array: true, type: 'string', demandOption: true }).options({
+        output: { type: 'string', alias: 'o' },
+        format: {
+          description: 'Use a specific output format.',
+          choices: ['stylish', 'codeframe', 'json', 'checkstyle'] as ReadonlyArray<OutputFormat>,
+          default: 'codeframe' as OutputFormat,
+        },
+        'max-problems': {
+          requiresArg: true,
+          description: 'Reduce output to max N problems.',
+          type: 'number',
+          default: 100,
+        },
+        ext: {
+          description: 'Bundle file extension.',
+          requiresArg: true,
+          choices: outputExtensions,
+        },
+        'skip-rule': {
+          description: 'Ignore certain rules.',
+          array: true,
+          type: 'string',
+        },
+        'skip-preprocessor': {
+          description: 'Ignore certain preprocessors.',
+          array: true,
+          type: 'string',
+        },
+        'skip-decorator': {
+          description: 'Ignore certain decorators.',
+          array: true,
+          type: 'string',
+        },
+        dereferenced: {
+          alias: 'd',
+          type: 'boolean',
+          description: 'Produce fully dereferenced bundle.',
+        },
+        force: {
+          alias: 'f',
+          type: 'boolean',
+          description: 'Produce bundle output even when errors occur.',
+        },
+        config: {
+          description: 'Specify path to the config file.',
+          type: 'string',
+        },
+        lint: {
+          description: 'Lint definitions',
+          type: 'boolean',
+          default: false,
+        },
+        metafile: {
+          description: 'Produce metadata about the bundle',
+          type: 'string',
+        },
+        extends: {
+          description: 'Override extends configurations (defaults or config file settings).',
+          requiresArg: true,
+          array: true,
+          type: 'string',
+        },
+        'remove-unused-components': {
+          description: 'Remove unused components.',
+          type: 'boolean',
+          default: false,
+        },
+      }),
+    (argv) => {
+      handleBundle(argv, version);
+    },
+  )
+  .command(
+    'login',
+    'Login to the Redocly API registry with an access token.',
+    async (yargs) =>
+      yargs.options({
+        verbose: {
+          description: 'Include additional output.',
+          type: 'boolean',
+        },
+        region: {
+          description: 'Specify a region.',
+          alias: 'r',
+          choices: regionChoices,
+        },
+      }),
+    handleLogin,
+  )
+  .command(
+    'logout',
+    'Clear your stored credentials for the Redocly API registry.',
+    (yargs) => yargs,
+    async () => {
+      const client = new RedoclyClient();
+      client.logout();
+    },
+  )
+  .command(
+    'preview-docs [entrypoint]',
+    'Preview API reference docs for the specified definition.',
+    (yargs) =>
+      yargs.positional('entrypoint', { type: 'string' }).options({
+        port: {
+          alias: 'p',
+          type: 'number',
+          default: 8080,
+          description: 'Preview port.',
+        },
+        host: {
+          alias: 'h',
+          type: 'string',
+          default: '127.0.0.1',
+          description: 'Preview host.',
+        },
+        'skip-preprocessor': {
+          description: 'Ignore certain preprocessors.',
+          array: true,
+          type: 'string',
+        },
+        'skip-decorator': {
+          description: 'Ignore certain decorators.',
+          array: true,
+          type: 'string',
+        },
+        'use-community-edition': {
+          description: 'Force using Redoc CE for docs preview.',
+          type: 'boolean',
+        },
+        force: {
+          alias: 'f',
+          type: 'boolean',
+          description: 'Produce bundle output even when errors occur.',
+        },
+        config: {
+          description: 'Specify path to the config file.',
+          type: 'string',
+        },
+      }),
+    previewDocs,
+  )
+  .completion('completion', 'Generate completion script.')
+  .demandCommand(1)
+  .strict().argv;

package/src/js-utils.ts

@@ -0,0 +1,12 @@
+export function isObject(obj: any) {
+  const type = typeof obj;
+  return type === 'function' || type === 'object' && !!obj;
+}
+
+export function isEmptyObject(obj: any) {
+  return !!obj && Object.keys(obj).length === 0;
+}
+
+export function isString(str: string) {
+  return Object.prototype.toString.call(str) === "[object String]";
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+import { BundleOutputFormat, Region } from '@redocly/openapi-core';
+export type Totals = {
+  errors: number;
+  warnings: number;
+  ignored: number;
+};
+export type Entrypoint = {
+  path: string;
+  alias?: string;
+};
+export const outputExtensions = ['json', 'yaml', 'yml'] as ReadonlyArray<BundleOutputFormat>;
+export type OutputExtensions = 'json' | 'yaml' | 'yml' | undefined;
+export const regionChoices = ['us', 'eu'] as ReadonlyArray<Region>;

package/src/utils.ts

@@ -0,0 +1,300 @@
+import { basename, dirname, extname, join, resolve } from 'path';
+import { blue, gray, green, red, yellow } from 'colorette';
+import { performance } from "perf_hooks";
+import * as glob from 'glob-promise';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { Writable } from 'stream';
+import {
+  BundleOutputFormat,
+  Config,
+  LintConfig,
+  ResolveError,
+  YamlParseError,
+  parseYaml,
+  stringifyYaml
+} from '@redocly/openapi-core';
+import { Totals, outputExtensions, Entrypoint } from './types';
+
+export async function getFallbackEntryPointsOrExit(argsEntrypoints: string[] | undefined, config: Config): Promise<Entrypoint[]> {
+  const  { apis } = config;
+  const shouldFallbackToAllDefinitions = !isNotEmptyArray(argsEntrypoints) && apis && Object.keys(apis).length > 0;
+  const res = shouldFallbackToAllDefinitions
+    ? Object.entries(apis).map(([alias, { root }]) => ({
+        path: resolve(getConfigDirectory(config), root),
+        alias,
+      }))
+    : (await expandGlobsInEntrypoints(argsEntrypoints!, config));
+  if (!isNotEmptyArray(res)) {
+    process.stderr.write('error: missing required argument `entrypoints`.\n');
+    process.exit(1);
+  }
+  return res;
+}
+
+function getConfigDirectory(config: Config) {
+  return config.configFile ? dirname(config.configFile) : process.cwd();
+}
+
+function isNotEmptyArray<T>(args?: T[]): boolean {
+  return Array.isArray(args) && !!args.length;
+}
+
+function getAliasOrPath(config: Config, aliasOrPath: string): Entrypoint {
+  return config.apis[aliasOrPath]
+    ? { path: config.apis[aliasOrPath]?.root, alias: aliasOrPath }
+    : { path: aliasOrPath };
+}
+
+async function expandGlobsInEntrypoints(args: string[], config: Config) {
+  return (await Promise.all((args as string[]).map(async aliasOrPath => {
+    return glob.hasMagic(aliasOrPath)
+      ? (await glob(aliasOrPath)).map((g: string) => getAliasOrPath(config, g))
+      : getAliasOrPath(config, aliasOrPath);
+  }))).flat();
+}
+
+export function getExecutionTime(startedAt: number) {
+  return process.env.NODE_ENV === 'test'
+    ? '<test>ms'
+    : `${Math.ceil(performance.now() - startedAt)}ms`;
+}
+
+export function printExecutionTime(commandName: string, startedAt: number, entrypoint: string) {
+  const elapsed = getExecutionTime(startedAt);
+  process.stderr.write(gray(`\n${entrypoint}: ${commandName} processed in ${elapsed}\n\n`));
+}
+
+export function pathToFilename(path: string, pathSeparator: string) {
+  return path
+    .replace(/~1/g, '/')
+    .replace(/~0/g, '~')
+    .replace(/^\//, '')
+    .replace(/\//g, pathSeparator);
+}
+
+export class CircularJSONNotSupportedError extends Error {
+  constructor(public originalError: Error) {
+    super(originalError.message);
+    // Set the prototype explicitly.
+    Object.setPrototypeOf(this, CircularJSONNotSupportedError.prototype);
+  }
+}
+
+export function dumpBundle(obj: any, format: BundleOutputFormat, dereference?: boolean): string {
+  if (format === 'json') {
+    try {
+      return JSON.stringify(obj, null, 2);
+    } catch (e) {
+      if (e.message.indexOf('circular') > -1) {
+        throw new CircularJSONNotSupportedError(e);
+      }
+      throw e;
+    }
+  } else {
+    return stringifyYaml(obj, {
+      noRefs: !dereference,
+    });
+  }
+}
+
+export function saveBundle(filename: string, output: string) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  fs.writeFileSync(filename, output);
+}
+
+export async function promptUser(query: string, hideUserInput = false): Promise<string> {
+  return new Promise((resolve) => {
+    let output: Writable = process.stdout;
+    let isOutputMuted = false;
+
+    if (hideUserInput) {
+      output = new Writable({
+        write: (chunk, encoding, callback) => {
+          if (!isOutputMuted) {
+            process.stdout.write(chunk, encoding);
+          }
+          callback();
+        },
+      });
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output,
+      terminal: true,
+      historySize: hideUserInput ? 0 : 30,
+    });
+
+    rl.question(`${query}:\n\n  `, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+
+    isOutputMuted = hideUserInput;
+  });
+}
+
+export function readYaml(filename: string) {
+  return parseYaml(fs.readFileSync(filename, 'utf-8'), { filename });
+}
+
+export function writeYaml(data: any, filename: string, noRefs = false) {
+  const content = stringifyYaml(data, { noRefs });
+
+  if (process.env.NODE_ENV === 'test') {
+    process.stderr.write(content);
+    return;
+  }
+  fs.writeFileSync(filename, content);
+}
+
+export function pluralize(label: string, num: number) {
+  if (label.endsWith('is')) {
+    [label] = label.split(' ');
+    return num === 1 ? `${label} is` : `${label}s are`;
+  }
+  return num === 1 ? `${label}` : `${label}s`;
+}
+
+export function handleError(e: Error, ref: string) {
+  if (e instanceof ResolveError) {
+    process.stderr.write(
+      `Failed to resolve entrypoint definition at ${ref}:\n\n  - ${e.message}.\n\n`,
+    );
+  } else if (e instanceof YamlParseError) {
+    process.stderr.write(
+      `Failed to parse entrypoint definition at ${ref}:\n\n  - ${e.message}.\n\n`,
+    );
+    // TODO: codeframe
+  } else { // @ts-ignore
+    if (e instanceof CircularJSONNotSupportedError) {
+      process.stderr.write(
+        red(`Detected circular reference which can't be converted to JSON.\n`) +
+        `Try to use ${blue('yaml')} output or remove ${blue('--dereferenced')}.\n\n`,
+      );
+    } else {
+      process.stderr.write(`Something went wrong when processing ${ref}:\n\n  - ${e.message}.\n\n`);
+      throw e;
+    }
+  }
+}
+
+export function printLintTotals(totals: Totals, definitionsCount: number) {
+  const ignored = totals.ignored
+    ? yellow(`${totals.ignored} ${pluralize('problem is', totals.ignored)} explicitly ignored.\n\n`)
+    : '';
+
+  if (totals.errors > 0) {
+    process.stderr.write(
+      red(
+        `❌ Validation failed with ${totals.errors} ${pluralize('error', totals.errors)}${
+          totals.warnings > 0
+            ? ` and ${totals.warnings} ${pluralize('warning', totals.warnings)}`
+            : ''
+        }.\n${ignored}`,
+      ),
+    );
+  } else if (totals.warnings > 0) {
+    process.stderr.write(
+      green(`Woohoo! Your OpenAPI ${pluralize('definition is', definitionsCount)} valid. 🎉\n`),
+    );
+    process.stderr.write(
+      yellow(`You have ${totals.warnings} ${pluralize('warning', totals.warnings)}.\n${ignored}`),
+    );
+  } else {
+    process.stderr.write(
+      green(
+        `Woohoo! Your OpenAPI ${pluralize(
+          'definition is',
+          definitionsCount,
+        )} valid. 🎉\n${ignored}`,
+      ),
+    );
+  }
+
+  if (totals.errors > 0) {
+    process.stderr.write(
+      gray(`run \`openapi lint --generate-ignore-file\` to add all problems to the ignore file.\n`),
+    );
+  }
+
+  process.stderr.write('\n');
+}
+
+export function getOutputFileName(
+  entrypoint: string,
+  entries: number,
+  output?: string,
+  ext?: BundleOutputFormat,
+) {
+  if (!output) {
+    return { outputFile: 'stdout', ext: ext || 'yaml' };
+  }
+
+  let outputFile = output;
+  if (entries > 1) {
+    ext = ext || (extname(entrypoint).substring(1) as BundleOutputFormat);
+    if (!outputExtensions.includes(ext as any)) {
+      throw new Error(`Invalid file extension: ${ext}.`);
+    }
+    outputFile = join(output, basename(entrypoint, extname(entrypoint))) + '.' + ext;
+  } else {
+    if (output) {
+      ext = ext || (extname(output).substring(1) as BundleOutputFormat);
+    }
+    ext = ext || (extname(entrypoint).substring(1) as BundleOutputFormat);
+    if (!outputExtensions.includes(ext as any)) {
+      throw new Error(`Invalid file extension: ${ext}.`);
+    }
+    outputFile = join(dirname(outputFile), basename(outputFile, extname(outputFile))) + '.' + ext;
+  }
+  return { outputFile, ext };
+}
+
+export function printUnusedWarnings(config: LintConfig) {
+  const { preprocessors, rules, decorators } = config.getUnusedRules();
+  if (rules.length) {
+    process.stderr.write(
+      yellow(
+        `[WARNING] Unused rules found in ${blue(config.configFile || '')}: ${rules.join(', ')}.\n`,
+      ),
+    );
+  }
+  if (preprocessors.length) {
+    process.stderr.write(
+      yellow(
+        `[WARNING] Unused preprocessors found in ${blue(
+          config.configFile || '',
+        )}: ${preprocessors.join(', ')}.\n`,
+      ),
+    );
+  }
+  if (decorators.length) {
+    process.stderr.write(
+      yellow(
+        `[WARNING] Unused decorators found in ${blue(config.configFile || '')}: ${decorators.join(
+          ', ',
+        )}.\n`,
+      ),
+    );
+  }
+
+  if (rules.length || preprocessors.length) {
+    process.stderr.write(`Check the spelling and verify you added plugin prefix.\n`);
+  }
+}
+
+export function exitWithError(message: string) {
+  process.stderr.write(red(message)+ '\n\n');
+  process.exit(1);
+}
+
+/**
+ * Checks if dir is subdir of parent
+ */
+export function isSubdir(parent: string, dir: string): boolean {
+  const relative = path.relative(parent, dir);
+  return !!relative && !/^..($|\/)/.test(relative) && !path.isAbsolute(relative);
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "references": [{ "path": "../core" }],
+  "exclude": ["lib"]
+}