@openapi-qraft/plugin 2.3.2 → 2.4.0

package/src/lib/RedoclyConfigCommand.ts

@@ -0,0 +1,221 @@
+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 { getRedocAPIsToQraft } from './getRedocAPIsToQraft.js';
+import { loadRedoclyConfig } from './loadRedoclyConfig.js';
+import { maybeEscapeShellArg } from './maybeEscapeShellArg.js';
+import { parseConfigToArgs } from './parseConfigToArgs.js';
+import { QraftCommand } from './QraftCommand.js';
+
+export const redoclyOption = (() => {
+  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')
+  );
+})();
+/**
+ * @param name - not used
+ */
+export class RedoclyConfigCommand extends Command {
+  protected readonly cwd: URL;
+
+  /**
+   * Redocly API item and QraftCommand arguments
+   */
+  protected parsedAPIs: RedoclyQraftAPIs = {};
+
+  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 = [], 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);
+        }
+
+        const redocAPIsToQraftEntries = Object.entries(
+          getRedocAPIsToQraft(redoc, this.cwd, spinner)
+        ).filter(([apiName]) => !apis.length || apis.includes(apiName));
+
+        if (apis.length) {
+          const notFoundAPIs = apis.filter(
+            (inputAPIName: string) =>
+              !redocAPIsToQraftEntries.some(
+                ([apiName]) => apiName === 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.`
+            );
+          }
+        }
+
+        redocAPIsToQraftEntries.forEach(([apiName, api]) => {
+          const {
+            ['x-openapi-qraft']: { ['output-dir']: outputDir, ...qraftConfig },
+          } = api;
+
+          const cwd = fileURLToPath(this.cwd);
+
+          this.parsedAPIs[apiName] = [
+            apiName,
+            ...parseConfigToArgs({
+              redocly: relative(cwd, redocConfigFile),
+              'output-dir': relative(cwd, outputDir),
+              ...qraftConfig,
+            }),
+          ];
+        });
+
+        spinner.stop();
+      });
+  }
+
+  async parseConfig<T>(
+    callbackFn: CallbackFn<T>,
+    argv: readonly string[],
+    options?: ParseOptions
+  ): Promise<T[] | undefined> {
+    await this.parseAsync(argv, options);
+
+    if (!Object.entries(this.parsedAPIs).length) return;
+
+    return RedoclyConfigCommand.forEachRedoclyAPIEntry(
+      this.parsedAPIs,
+      callbackFn
+    );
+  }
+
+  static async forEachRedoclyAPIEntry<T>(
+    redoclyAPIs: RedoclyQraftAPIs,
+    callbackFn: CallbackFn<T>
+  ) {
+    const redoclyAPIsEntries = Object.entries(redoclyAPIs);
+
+    const spinner = QraftCommand.spinner;
+
+    spinner.info('Loading Redocly configuration...');
+
+    const { errors, results } = await Promise.allSettled(
+      redoclyAPIsEntries.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 callbackFn([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: [] }
+      )
+    );
+
+    if (errors.length) {
+      throw new CommanderError(
+        1,
+        'ERROR',
+        'The following errors occurred during API client generation:\n' +
+          errors
+            .map((error) =>
+              error instanceof Error
+                ? error.message + '\n' + error.stack
+                : JSON.stringify(error, null, 2)
+            )
+            .join('\n\n')
+      );
+    }
+
+    spinner.succeed(
+      c.green(`API clients successfully generated for: `) +
+        redoclyAPIsEntries
+          .map(([apiName]) => `"${c.magenta(apiName)}"`)
+          .join(', ') +
+        '.'
+    );
+
+    return results;
+  }
+}
+
+type CallbackFn<T> = (
+  processArgv: string[],
+  processArgvParseOptions?: ParseOptions
+) => T;
+
+type RedoclyQraftAPIs = {
+  [apiName: string]: string[];
+};

package/src/lib/getRedocAPIsToQraft.ts

@@ -0,0 +1,87 @@
+import type { Config } from '@redocly/openapi-core';
+import { isAbsolute } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { CommanderError } from 'commander';
+import { Ora } from 'ora';
+
+export const QRAFT_REDOC_CONFIG_KEY = 'x-openapi-qraft';
+
+export function getRedocAPIsToQraft(
+  redoc: Config,
+  cwd: URL,
+  spinner: Ora,
+  apiName?: string
+) {
+  const hasRedoclyApis = Object.keys(redoc?.apis ?? {}).length > 0;
+  if (!hasRedoclyApis) {
+    throw new CommanderError(
+      1,
+      'ERR_MISSING_APIS',
+      'No "apis" found in Redocly config. Please specify the APIs to be generated.'
+    );
+  }
+  if (!redoc.configFile) {
+    throw new CommanderError(
+      1,
+      'ERR_MISSING_CONFIG_FILE',
+      'No "configFile" found in Redocly config. Please specify the path to the Redocly config file.'
+    );
+  }
+
+  const configRoot = isAbsolute(redoc.configFile)
+    ? new URL(pathToFileURL(redoc.configFile))
+    : new URL(redoc.configFile, cwd);
+
+  const apisToQraftEntries = Object.entries(redoc.apis)
+    .map(([itemPpiName, api]) => {
+      if (apiName && apiName !== itemPpiName) return;
+
+      const qraftConfig =
+        QRAFT_REDOC_CONFIG_KEY in api ? api[QRAFT_REDOC_CONFIG_KEY] : undefined;
+
+      if (!qraftConfig) {
+        return void spinner.warn(
+          `API ${itemPpiName} is missing an \`${QRAFT_REDOC_CONFIG_KEY}\` key. Skipping...`
+        );
+      }
+
+      if (typeof qraftConfig !== 'object') {
+        throw new CommanderError(
+          1,
+          'ERR_MISSING_API_CONFIG',
+          `API ${itemPpiName} is missing an \`${QRAFT_REDOC_CONFIG_KEY}\` key. See https://openapi-qraft.github.io/openapi-qraft/docs/codegen/CLI/redocly-config.`
+        );
+      }
+
+      const {
+        o,
+        ['output-dir']: outputPath = o,
+        ...qraftConfigRest
+      } = qraftConfig as {
+        ['output-dir']?: string;
+        o?: string;
+      };
+
+      if (!outputPath) {
+        throw new CommanderError(
+          1,
+          'ERR_MISSING_API_OUTPUT',
+          `API ${itemPpiName} is missing an "output-dir" key. See https://openapi-qraft.github.io/openapi-qraft/docs/codegen/CLI/redocly-config.`
+        );
+      }
+
+      return [
+        itemPpiName,
+        {
+          ...api,
+          [QRAFT_REDOC_CONFIG_KEY]: {
+            ...qraftConfigRest,
+            ['output-dir']: fileURLToPath(new URL(outputPath, configRoot)),
+          },
+        },
+      ] as const;
+    })
+    .filter((api) => !!api);
+
+  return Object.fromEntries(apisToQraftEntries);
+}

package/src/lib/handleSchemaInput.ts

@@ -17,7 +17,7 @@ export function handleSchemaInput(input: unknown, cwd: URL, spinner: Ora) {
      */
     if (process.stdin.isTTY) {
       spinner.fail(
-        'Input file not found or stdin is empty. Please specify `--input` option or pipe OpenAPI Schema to stdin.'
+        'Input file not found or stdin is empty. Please specify `input` argument or pipe OpenAPI Schema to stdin.'
       );
 
       throw new Error('Invalid input.');

package/src/lib/loadRedoclyConfig.ts

@@ -0,0 +1,47 @@
+import { fileURLToPath, URL } from 'node:url';
+import {
+  Config,
+  CONFIG_FILE_NAMES,
+  findConfig,
+  loadConfig,
+} from '@redocly/openapi-core';
+import { CommanderError } from 'commander';
+
+/**
+ * Loads Redocly config from the default config file:
+ * 'redocly.yaml', 'redocly.yml', '.redocly.yaml', '.redocly.yml'
+ */
+export async function loadRedoclyConfig(
+  configPath: null | undefined | true,
+  cwd: URL
+): Promise<Config>;
+/**
+ * Loads Redocly config from the specified path or from the default config file.
+ */
+export async function loadRedoclyConfig(
+  configPath: string,
+  cwd: URL
+): Promise<Config>;
+export async function loadRedoclyConfig(
+  configPath: string | null | undefined | true,
+  cwd: URL
+): Promise<Config> {
+  const normalizedConfigPath =
+    typeof configPath === 'string'
+      ? configPath
+      : findConfig(fileURLToPath(cwd));
+
+  if (!normalizedConfigPath) {
+    throw new CommanderError(
+      1,
+      'INVALID_REDOCLY_CONFIG_PATH',
+      typeof configPath === 'string'
+        ? `Could not find Redocly config file at ${configPath}`
+        : `Could not find Redocly config file in ${cwd}. Searched in: ${CONFIG_FILE_NAMES.join(', ')}`
+    );
+  }
+
+  return await loadConfig({
+    configPath: normalizedConfigPath,
+  });
+}

package/src/lib/maybeEscapeShellArg.ts

@@ -0,0 +1,10 @@
+import { shouldQuoteCommandLineArg } from './shouldQuoteCommandLineArg.js';
+
+export function maybeEscapeShellArg(arg: string): string {
+  if (shouldQuoteCommandLineArg(arg)) {
+    // bash-safe single-quote escaping
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+  }
+
+  return arg;
+}

package/src/lib/open-api/readSchema.ts

@@ -1,20 +1,12 @@
 import type { Readable } from 'node:stream';
+import type { Config } from '@redocly/openapi-core';
 import type { OpenAPI3 } from 'openapi-typescript';
-import { createConfig } from '@redocly/openapi-core';
 import { validateAndBundle } from 'openapi-typescript/dist/lib/redoc.js';
 
 export const readSchema = async (
-  source: string | URL | OpenAPI3 | Readable | Buffer
+  source: string | URL | OpenAPI3 | Readable | Buffer,
+  redoc: Config
 ) => {
-  const redoc = await createConfig(
-    {
-      rules: {
-        'operation-operationId-unique': { severity: 'error' }, // throw error on duplicate operationIDs
-      },
-    },
-    { extends: ['minimal'] }
-  );
-
   const parsed = await validateAndBundle(source, {
     redoc,
     silent: false,

package/src/lib/parseConfigToArgs.ts

@@ -0,0 +1,134 @@
+/**
+ * Converts a parsed YAML configuration into command line arguments
+ * @param config The parsed YAML configuration object
+ * @returns Array of command line arguments
+ */
+export function parseConfigToArgs(config: Record<string, unknown>): string[] {
+  const args: string[] = [];
+
+  const isPrimitive = (val: any): val is string | number | boolean =>
+    typeof val === 'string' ||
+    typeof val === 'number' ||
+    typeof val === 'boolean';
+
+  function flattenMapping(node: any, prefixKeys: string[]): string[] {
+    const results: string[] = [];
+
+    if (isPrimitive(node)) {
+      if (typeof node === 'boolean') {
+        if (node) {
+          results.push(prefixKeys.join(':'));
+        }
+      } else {
+        results.push(`${prefixKeys.join(':')}:${node.toString()}`);
+      }
+      return results;
+    }
+
+    if (Array.isArray(node)) {
+      if (node.every((el) => isPrimitive(el))) {
+        const primitives = node.filter(
+          (el) => el !== null && el !== undefined
+        ) as (string | number | boolean)[];
+        const joined = primitives.map((el) => el.toString()).join(',');
+        if (joined) {
+          results.push(`${prefixKeys.join(':')}:${joined}`);
+        }
+        return results;
+      }
+
+      for (const el of node) {
+        if (el == null) {
+          continue;
+        }
+        results.push(...flattenMapping(el, prefixKeys));
+      }
+      return results;
+    }
+
+    if (typeof node === 'object' && node !== null) {
+      for (const [key, value] of Object.entries(node)) {
+        results.push(...flattenMapping(value, [...prefixKeys, key]));
+      }
+      return results;
+    }
+
+    return results;
+  }
+
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value === 'string' || typeof value === 'number') {
+      args.push(`--${key}`, value.toString());
+    } else if (typeof value === 'boolean') {
+      if (value) {
+        args.push(`--${key}`);
+      }
+    } else if (value == null) {
+      continue;
+    } else if (Array.isArray(value)) {
+      if (value.every((el) => isPrimitive(el))) {
+        const primitives = value.filter(
+          (el) => el !== null && el !== undefined
+        ) as (string | number | boolean)[];
+        args.push(`--${key}`, ...primitives.map((el) => el.toString()));
+      } else {
+        for (const el of value) {
+          if (el == null) {
+            continue;
+          }
+          if (typeof el === 'object') {
+            const mappingPaths = flattenMapping(el, []);
+            if (mappingPaths.length) {
+              args.push(`--${key}`, ...mappingPaths);
+            }
+          } else if (isPrimitive(el)) {
+            args.push(`--${key}`, el.toString());
+          }
+        }
+      }
+    } else if (typeof value === 'object') {
+      for (const [childKey, childValue] of Object.entries(
+        value as Record<string, unknown>
+      )) {
+        if (typeof childValue === 'string' || typeof childValue === 'number') {
+          args.push(`--${key}`, childKey, childValue.toString());
+        } else if (typeof childValue === 'boolean') {
+          if (childValue) {
+            args.push(`--${key}`, childKey);
+          }
+        } else if (childValue == null) {
+          continue;
+        } else if (Array.isArray(childValue)) {
+          if (childValue.every((el) => isPrimitive(el))) {
+            const primitives = childValue.filter(
+              (el) => el !== null && el !== undefined
+            ) as (string | number | boolean)[];
+            const joined = primitives.map((el) => el.toString()).join(',');
+            args.push(`--${key}`, childKey, joined);
+          } else {
+            for (const el of childValue) {
+              if (el == null) {
+                continue;
+              }
+              if (typeof el === 'object') {
+                const mappingPaths = flattenMapping(el, [childKey]);
+                if (mappingPaths.length) {
+                  args.push(`--${key}`, ...mappingPaths);
+                }
+              } else if (isPrimitive(el)) {
+                args.push(`--${key}`, childKey, el.toString());
+              }
+            }
+          }
+        } else if (typeof childValue === 'object') {
+          const mappingPaths = flattenMapping(childValue, []);
+          if (mappingPaths.length) {
+            args.push(`--${key}`, childKey, ...mappingPaths);
+          }
+        }
+      }
+    }
+  }
+
+  return args;
+}

package/src/lib/shouldQuoteCommandLineArg.ts

@@ -0,0 +1,32 @@
+/**
+ * Checks if a command-line argument needs to be quoted when used in a command line.
+ *
+ * Arguments containing special characters like spaces, quotes, or shell metacharacters
+ * need to be wrapped in quotes to be properly interpreted by the shell.
+ *
+ * @param arg The command-line argument to check
+ * @returns True if the argument needs quotes, false otherwise
+ */
+export function shouldQuoteCommandLineArg(arg: string): boolean {
+  if (!arg) return false;
+
+  // Check for spaces
+  if (arg.includes(' ')) return true;
+
+  // Check for quotes
+  if (arg.includes('"') || arg.includes("'")) return true;
+
+  // Check for shell metacharacters and special characters
+  const shellSpecialChars = /[&|<>(){}[\]$;!*?~`\n\r\t#]/;
+  if (shellSpecialChars.test(arg)) return true;
+
+  // Check for control characters
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1F\x7F]/.test(arg)) return true;
+
+  // Check if argument starts with a dash (to avoid confusion with options)
+  if (arg.startsWith('-') && !arg.startsWith('--')) return true;
+
+  // Check for wildcards
+  return arg.includes('*') || arg.includes('?');
+}

package/src/packageVersion.ts

@@ -1,2 +1,2 @@
 // This file was generated automatically
-export const packageVersion = '2.3.2';
+export const packageVersion = '2.4.0';