@qraft/plugin 1.0.0-beta.0

package/src/lib/QraftCommand.ts

@@ -0,0 +1,381 @@
+import { sep } from 'node:path';
+import process from 'node:process';
+import { pathToFileURL, URL } from 'node:url';
+import c from 'ansi-colors';
+import { Command, Option, ParseOptions } from 'commander';
+import ora, { Ora } from 'ora';
+import { GeneratorFile } from './GeneratorFile.js';
+import { OutputOptions } from './OutputOptions.js';
+import { writeGeneratorFiles } from './writeGeneratorFiles.js';
+
+export interface QraftCommandOptions {
+  defaultFileHeader?: string;
+}
+
+export class QraftCommand<
+  TActionOptions extends QraftCommandActionOptions = QraftCommandActionOptions,
+> extends Command {
+  static spinner = ora();
+
+  protected readonly cwd: URL;
+  protected registeredPluginActions: QraftCommandActionCallback<TActionOptions>[] =
+    [];
+
+  constructor(name?: string, options?: QraftCommandOptions) {
+    super(name);
+    this.cwd = pathToFileURL(`${process.cwd()}/`);
+
+    this.option(
+      '-o, --output-dir <path>',
+      'Output directory for generated files'
+    )
+      .addOption(
+        new Option(
+          '-c, --clean',
+          'Clean output directory before generating files'
+        )
+      )
+      .addOption(
+        new Option(
+          '--file-header <string>',
+          'Header to be added to the generated file (eg: /* eslint-disable */)'
+        ).default(options?.defaultFileHeader ?? '')
+      );
+  }
+
+  action(callback: QraftCommandActionCallback<TActionOptions>): this {
+    this.registerPluginAction(callback);
+    return super.action(this.actionCallback.bind(this));
+  }
+
+  async actionCallback(...actionArgs: any[]): Promise<void> {
+    const inputs = actionArgs.filter(
+      (arg) => typeof arg === 'string'
+    ) as string[];
+    const args = actionArgs.find(
+      (arg) => arg && typeof arg === 'object'
+    ) as Record<string, any>;
+
+    if (!args) throw new Error('Arguments object not found');
+
+    const spinner = QraftCommand.spinner;
+
+    spinner.start('Initializing process...');
+
+    const actionOptions = await this.prepareActionOptions(inputs, args);
+
+    spinner.text = 'Generating code...';
+
+    for (const pluginAction of this.registeredPluginActions) {
+      const fileItems = await new Promise<GeneratorFile[]>(
+        (resolve, reject) => {
+          pluginAction(actionOptions, resolve).catch(reject);
+        }
+      );
+
+      try {
+        if (this.registeredPluginActions.indexOf(pluginAction) === 0) {
+          await writeGeneratorFiles({
+            fileItems: [
+              { directory: actionOptions.output.dir, clean: false },
+              ...fileItems,
+            ],
+            spinner,
+          });
+        } else {
+          await writeGeneratorFiles({ fileItems, spinner });
+        }
+      } catch (error) {
+        spinner.fail(
+          c.red('An error occurred during the code generation process.')
+        );
+
+        if (error instanceof Error) {
+          console.error(c.red(error.message), c.red(error.stack ?? ''));
+        }
+
+        throw error;
+      }
+    }
+
+    spinner.succeed(c.green('Qraft process completed successfully'));
+  }
+
+  protected async prepareActionOptions(
+    inputs: string[],
+    args: Record<string, any>
+  ): Promise<TActionOptions> {
+    const outputDir = normalizeOutputDirPath(args.outputDir);
+
+    return {
+      inputs,
+      args,
+      spinner: QraftCommand.spinner,
+      output: {
+        dir: outputDir,
+        clean: args.clean,
+      },
+    } as TActionOptions;
+  }
+
+  protected registerPluginAction(
+    callback: QraftCommandActionCallback<TActionOptions>
+  ) {
+    this.registeredPluginActions.push(callback);
+  }
+
+  option(
+    flags: string,
+    description?: string,
+    defaultValue?: string | boolean | string[]
+  ): this;
+  option<T>(
+    flags: string,
+    description: string,
+    parseArg: (value: string, previous: T) => T,
+    defaultValue?: T
+  ): this;
+  /** @deprecated since v7, instead use choices or a custom function */
+  option(
+    flags: string,
+    description: string,
+    regexp: RegExp,
+    defaultValue?: string | boolean | string[]
+  ): this;
+  option<T>(
+    flags: string,
+    description?: string,
+    parseArg?:
+      | ((value: string, previous: T) => T)
+      | string
+      | boolean
+      | string[]
+      | RegExp,
+    defaultValue?: T
+  ): this {
+    if (
+      this.findSimilarOption({
+        flags,
+        mandatory: false,
+      })
+    ) {
+      return this;
+    }
+
+    return super.option(
+      flags,
+      // @ts-expect-error - Issues with overloading
+      description,
+      parseArg,
+      defaultValue
+    );
+  }
+
+  requiredOption(
+    flags: string,
+    description?: string,
+    defaultValue?: string | boolean | string[]
+  ): this;
+  requiredOption<T>(
+    flags: string,
+    description: string,
+    parseArg: (value: string, previous: T) => T,
+    defaultValue?: T
+  ): this;
+  /** @deprecated since v7, instead use choices or a custom function */
+  requiredOption(
+    flags: string,
+    description: string,
+    regexp: RegExp,
+    defaultValue?: string | boolean | string[]
+  ): this;
+  requiredOption<T>(
+    flags: string,
+    description?: string,
+    regexpOrDefaultValue?:
+      | string
+      | boolean
+      | string[]
+      | RegExp
+      | ((value: string, previous: T) => T),
+    defaultValue?: string | boolean | string[]
+  ): this {
+    if (
+      this.findSimilarOption({
+        flags,
+        mandatory: true,
+      })
+    ) {
+      return this;
+    }
+
+    return super.requiredOption(
+      flags,
+      // @ts-expect-error - Issues with overloading
+      description,
+      regexpOrDefaultValue,
+      defaultValue
+    );
+  }
+
+  addOption(option: Option): this {
+    if (
+      this.findSimilarOption({
+        flags: option.flags,
+        mandatory: option.mandatory,
+      })
+    ) {
+      return this;
+    }
+
+    return super.addOption(option);
+  }
+
+  parseAsync(argv?: readonly string[], options?: ParseOptions): Promise<this> {
+    if (options?.from !== 'user') this.logVersion();
+    return super.parseAsync(argv, options);
+  }
+
+  parse(argv?: readonly string[], options?: ParseOptions): this {
+    if (options?.from !== 'user') this.logVersion();
+    return super.parse(argv, options);
+  }
+
+  protected logVersion() {
+    QraftCommand.spinner.info(`✨ ${c.bold('Qraft')}`);
+  }
+
+  protected findSimilarOption(option: { flags: string; mandatory: boolean }) {
+    try {
+      return findSimilarOption(option, this.options);
+    } catch (error) {
+      console.error(
+        c.red(
+          error instanceof Error
+            ? error.message
+            : 'An error occurred during command option setup'
+        )
+      );
+
+      throw error;
+    }
+  }
+}
+
+export function normalizeOutputDirPath(outputDir: string): URL {
+  return pathToFileURL(
+    outputDir.endsWith(sep) ? outputDir : `${outputDir}${sep}`
+  );
+}
+
+export interface QraftCommandActionOptions {
+  inputs: string[];
+  args: Record<string, any>;
+  spinner: Ora;
+  output: OutputOptions;
+}
+
+export type QraftCommandActionCallback<
+  TActionOptions extends QraftCommandActionOptions = QraftCommandActionOptions,
+> = (
+  options: TActionOptions,
+  resolve: (files: GeneratorFile[]) => void
+) => Promise<void>;
+
+function findSimilarOption(
+  {
+    flags,
+    mandatory,
+  }: {
+    flags: string;
+    mandatory: boolean;
+  },
+  options: readonly Option[]
+) {
+  const newOptionParsedFlags = splitOptionFlags(flags);
+  const optional = flags.includes('[');
+  const required = flags.includes('<');
+  const variadic = /\w\.\.\.[>\]]$/.test(flags);
+
+  return options.find((existingOption) => {
+    const existingOptionParsedFlags = splitOptionFlags(existingOption.flags);
+
+    if (
+      !(
+        (existingOptionParsedFlags.longFlag !== undefined &&
+          existingOptionParsedFlags.longFlag ===
+            newOptionParsedFlags.longFlag) ||
+        (existingOptionParsedFlags.shortFlag !== undefined &&
+          existingOptionParsedFlags.shortFlag ===
+            newOptionParsedFlags.shortFlag)
+      )
+    ) {
+      return false;
+    }
+
+    if (
+      existingOptionParsedFlags.longFlag !== undefined &&
+      newOptionParsedFlags.longFlag !== undefined &&
+      existingOptionParsedFlags.longFlag !== newOptionParsedFlags.longFlag
+    ) {
+      throw new Error(
+        `Long flag ${flags} already exists in the option list with flags: "${existingOption.flags}" and description: "${existingOption.description}"`
+      );
+    }
+
+    if (
+      existingOptionParsedFlags.shortFlag !== undefined &&
+      newOptionParsedFlags.shortFlag !== undefined &&
+      existingOptionParsedFlags.shortFlag !== newOptionParsedFlags.shortFlag
+    ) {
+      throw new Error(
+        `Short flag ${flags} already exists in the option list with flags: "${existingOption.flags}" and description: "${existingOption.description}"`
+      );
+    }
+
+    if (required !== existingOption.required) {
+      throw new Error(
+        `Flag ${flags} already exists in the option list with flags: "${existingOption.flags}" and description: "${existingOption.description}" but with different required status`
+      );
+    }
+
+    if (optional !== existingOption.optional) {
+      throw new Error(
+        `Flag ${flags} already exists in the option list with flags: "${existingOption.flags}" and description: "${existingOption.description}" but with different optional status`
+      );
+    }
+
+    if (mandatory !== existingOption.mandatory) {
+      throw new Error(
+        `Flag ${flags} already exists in the option list with flags: "${existingOption.flags}" and description: "${existingOption.description}" but with different mandatory status`
+      );
+    }
+
+    if (variadic !== existingOption.variadic) {
+      throw new Error(
+        `Flag ${flags} already exists in the option list with flags: "${existingOption.flags}" and description: "${existingOption.description}" but with different variadic status`
+      );
+    }
+
+    return existingOption;
+  });
+}
+
+export function splitOptionFlags(flags: string) {
+  let shortFlag;
+  let longFlag;
+
+  const flagParts = flags.split(/[ |,]+/);
+
+  if (flagParts.length > 1 && !/^[[<]/.test(flagParts[1]))
+    shortFlag = flagParts.shift();
+
+  longFlag = flagParts.shift();
+
+  if (!shortFlag && /^-[^-]$/.test(longFlag ?? '')) {
+    shortFlag = longFlag;
+    longFlag = undefined;
+  }
+
+  return { shortFlag, longFlag };
+}

package/src/lib/QraftCommandPlugin.ts

@@ -0,0 +1,9 @@
+import { QraftCommand, QraftCommandActionOptions } from './QraftCommand.js';
+
+export interface QraftCommandPlugin<
+  TCommand extends QraftCommand<any> = QraftCommand<QraftCommandActionOptions>,
+> {
+  setupCommand(command: TCommand): void | Promise<void>;
+
+  postSetupCommand?(command: TCommand, plugins: string[]): void | Promise<void>;
+}

package/src/lib/RedoclyConfigCommand.ts

@@ -0,0 +1,290 @@
+import { relative } from 'node:path';
+import { fileURLToPath, pathToFileURL, URL } from 'node:url';
+import { CONFIG_FILE_NAMES } from '@redocly/openapi-core';
+import c from 'ansi-colors';
+import { Command, CommanderError, Option, ParseOptions } from 'commander';
+import {
+  ASYNCAPI_QRAFT_REDOC_CONFIG_KEY,
+  getRedocAPIsToQraft,
+  OPENAPI_QRAFT_REDOC_CONFIG_KEY,
+} from './getRedocAPIsToQraft.js';
+import { loadRedoclyConfig } from './loadRedoclyConfig.js';
+import { maybeEscapeShellArg } from './maybeEscapeShellArg.js';
+import { parseConfigToArgs } from './parseConfigToArgs.js';
+import { QraftCommand } from './QraftCommand.js';
+
+export { ASYNCAPI_QRAFT_REDOC_CONFIG_KEY, OPENAPI_QRAFT_REDOC_CONFIG_KEY };
+
+export const redoclyOption = createRedoclyOption();
+
+export function createRedoclyOption() {
+  const bin = c.gray.underline('bin');
+  const __redocly = c.yellow('--redocly');
+
+  const examples = [
+    `${bin} ${__redocly}`,
+    `${bin} ${c.green('my-api')} ${__redocly}`,
+    `${bin} ${c.green('my-api@v1 my-api@v2')} ${__redocly}`,
+    `${bin} ${__redocly} ${c.yellow.underline('./my-redocly-config.yaml')}`,
+  ].map((example) => `${c.italic.yellow(example)}`);
+
+  return new Option(
+    '--redocly [config]',
+    [
+      c.bold(`Use the Redocly configuration to generate multiple API clients`),
+      `If the [config] parameter is not specified, the default Redocly configuration will be used: [${CONFIG_FILE_NAMES.join(' | ')}].`,
+      `For more information about this option, use the command: ${c.yellow.italic('--redocly-help')}`,
+      `${c.underline('Examples:')}`,
+      ...examples.map((example) => `${c.gray('$')} ${example}`),
+    ].join('\n')
+  );
+}
+
+export type ConfigKeyCallbacks<T> = {
+  [configKey: string]: CallbackFn<T>;
+};
+
+export class RedoclyConfigCommand extends Command {
+  protected readonly cwd: URL;
+  protected configKeys: string[] = [];
+
+  /**
+   * Redocly API grouped by configKey
+   * { [configKey]: { [apiName]: argv[] } }
+   */
+  protected parsedAPIsByConfigKey: RedoclyQraftAPIsByConfigKey = {};
+
+  constructor(name?: string) {
+    super(name);
+    this.cwd = pathToFileURL(`${process.cwd()}/`);
+
+    this.usage(c.green('[apis...] --redocly <config>'))
+      .argument(
+        '[apis...]',
+        'Optional list of Redocly APIs for which to generate API clients. If not specified, clients for all APIs will be generated.'
+      )
+      .allowUnknownOption(true)
+      .helpOption('--redocly-help', 'Display help for the `--redocly` option')
+      .addOption(redoclyOption)
+      .action(async (apis: string[] = [], args) => {
+        const redocly = args.redocly;
+
+        if (!redocly) return;
+
+        const spinner = QraftCommand.spinner;
+
+        spinner.start('Loading Redocly configuration ⚙︎');
+
+        const redoc = await loadRedoclyConfig(redocly || true, this.cwd);
+
+        const redocConfigFile = redoc.configFile;
+
+        if (!redocConfigFile) {
+          spinner.fail(
+            'No "configFile" found in the Redocly configuration. Please specify the correct path to the Redocly configuration file.'
+          );
+          process.exit(1);
+        }
+
+        type RawApisMap = ReturnType<typeof getRedocAPIsToQraft>;
+        const allRawApisByConfigKey: Record<string, RawApisMap> = {};
+
+        for (const configKey of this.configKeys) {
+          const apisForKey = getRedocAPIsToQraft(
+            redoc,
+            this.cwd,
+            spinner,
+            configKey
+          );
+          if (Object.keys(apisForKey).length > 0) {
+            allRawApisByConfigKey[configKey] = apisForKey;
+          }
+        }
+
+        const allApiNames = new Set(
+          Object.values(allRawApisByConfigKey).flatMap((apis) =>
+            Object.keys(apis)
+          )
+        );
+
+        if (apis.length) {
+          const notFoundAPIs = apis.filter(
+            (inputAPIName) => !allApiNames.has(inputAPIName)
+          );
+
+          if (notFoundAPIs.length) {
+            spinner.fail(
+              `The specified API${
+                notFoundAPIs.length > 1 ? 's' : ''
+              } ${notFoundAPIs.map(c.red).join(', ')} ${notFoundAPIs.length > 1 ? 'were' : 'was'} not found in the Redocly configuration.`
+            );
+
+            throw new CommanderError(
+              1,
+              'ERR_API_NOT_FOUND',
+              `The specified API${
+                notFoundAPIs.length > 1 ? 's' : ''
+              } ${c.red(notFoundAPIs.join(', '))} ${notFoundAPIs.length > 1 ? 'were' : 'was'} not found in the Redocly configuration.`
+            );
+          }
+        }
+
+        for (const [configKey, apisForKey] of Object.entries(
+          allRawApisByConfigKey
+        )) {
+          const filteredEntries = Object.entries(apisForKey).filter(
+            ([apiName]) => !apis.length || apis.includes(apiName)
+          );
+
+          if (filteredEntries.length === 0) continue;
+
+          this.parsedAPIsByConfigKey[configKey] = {};
+
+          for (const [apiName, api] of filteredEntries) {
+            const globalQraftConfig =
+              configKey in redoc.rawConfig
+                ? (redoc.rawConfig as Record<string, unknown>)[configKey]
+                : undefined;
+
+            const apiQraftConfigWithOutput = (
+              api as unknown as Record<string, unknown>
+            )[configKey] as { ['output-dir']: string };
+            const { ['output-dir']: outputDir, ...apiQraftConfig } =
+              apiQraftConfigWithOutput;
+
+            const cwd = fileURLToPath(this.cwd);
+
+            this.parsedAPIsByConfigKey[configKey][apiName] = [
+              apiName,
+              ...parseConfigToArgs({
+                redocly: relative(cwd, redocConfigFile),
+                'output-dir': relative(cwd, outputDir),
+                ...(globalQraftConfig && typeof globalQraftConfig === 'object'
+                  ? globalQraftConfig
+                  : undefined),
+                ...apiQraftConfig,
+              }),
+            ];
+          }
+        }
+
+        spinner.stop();
+      });
+  }
+
+  async parseConfig<T>(
+    callbacks: ConfigKeyCallbacks<T>,
+    argv: readonly string[],
+    options?: ParseOptions
+  ): Promise<T[] | undefined> {
+    this.configKeys = Object.keys(callbacks);
+
+    await this.parseAsync(argv, options);
+
+    const hasAnyAPIs = Object.values(this.parsedAPIsByConfigKey).some(
+      (apis) => Object.keys(apis).length > 0
+    );
+
+    if (!hasAnyAPIs) return; // todo::improve error reporting
+
+    return RedoclyConfigCommand.forEachRedoclyAPIEntry(
+      this.parsedAPIsByConfigKey,
+      callbacks
+    );
+  }
+
+  static async forEachRedoclyAPIEntry<T>(
+    apisByConfigKey: RedoclyQraftAPIsByConfigKey,
+    callbacks: ConfigKeyCallbacks<T>
+  ) {
+    const spinner = QraftCommand.spinner;
+
+    spinner.info('Loading Redocly configuration...');
+
+    const allResults: T[] = [];
+    const allErrors: unknown[] = [];
+
+    for (const [configKey, apis] of Object.entries(apisByConfigKey)) {
+      const callback = callbacks[configKey];
+      if (!callback) continue;
+
+      const apiEntries = Object.entries(apis);
+
+      const { errors, results } = await Promise.allSettled(
+        apiEntries.map(
+          async ([apiName, [openAPIDocument, ...apiProcessArgv]]) => {
+            spinner.info(
+              `Generating API client for ${c.magenta(apiName)} with the following parameters:\n` +
+                c.gray.italic('bin ') +
+                `${c.green.italic(openAPIDocument)} ` +
+                apiProcessArgv
+                  .map((arg) =>
+                    arg.startsWith('--')
+                      ? c.yellow.italic(arg)
+                      : c.yellow.italic.underline(maybeEscapeShellArg(arg))
+                  )
+                  .join(' ')
+            );
+            spinner.text = '';
+            spinner.start();
+
+            return await callback([openAPIDocument, ...apiProcessArgv], {
+              from: 'user',
+            });
+          }
+        )
+      ).then((results) =>
+        results.reduce<{ errors: unknown[]; results: T[] }>(
+          (acc, result) => {
+            if (result.status === 'rejected') acc.errors.push(result.reason);
+            else acc.results.push(result.value);
+
+            return acc;
+          },
+          { errors: [], results: [] }
+        )
+      );
+
+      allResults.push(...results);
+      allErrors.push(...errors);
+    }
+
+    if (allErrors.length) {
+      throw new CommanderError(
+        1,
+        'ERROR',
+        'The following errors occurred during API client generation:\n' +
+          allErrors
+            .map((error) =>
+              error instanceof Error
+                ? error.message + '\n' + error.stack
+                : JSON.stringify(error, null, 2)
+            )
+            .join('\n\n')
+      );
+    }
+
+    const allApiNames = Object.values(apisByConfigKey).flatMap((apis) =>
+      Object.keys(apis)
+    );
+
+    spinner.succeed(
+      c.green(`API clients successfully generated for: `) +
+        allApiNames.map((apiName) => `"${c.magenta(apiName)}"`).join(', ') +
+        '.'
+    );
+
+    return allResults;
+  }
+}
+
+type CallbackFn<T> = (
+  processArgv: string[],
+  processArgvParseOptions?: ParseOptions
+) => T | Promise<T>;
+
+type RedoclyQraftAPIsByConfigKey = {
+  [configKey: string]: {
+    [apiName: string]: string[];
+  };
+};

package/src/lib/formatFileHeader.ts

@@ -0,0 +1,4 @@
+export const formatFileHeader = (fileHeader: string | undefined) => {
+  if (!fileHeader) return '';
+  return `${fileHeader}${fileHeader.endsWith('\n') ? '' : '\n'}`;
+};