refactor(openapi): cleaner approach to prepareOas helper (#1312)

## 🧰 Changes

as part of the work in #1313, this
PR refactors our `prepareOas` helper (and by extension, the entire
`openapi` family of commands) to be a little bit more conformant to the
oclif command class pattern. this will clean up our debug logs a bit and
should make it a bit easier to add new `openapi` commands going forward.

## 🧬 QA & Testing

no end user changes — if tests continue to pass we should be in good
shape!

Author: kanadgupta

documentation/commands/openapi.md

@@ -143,14 +143,15 @@ Resolves circular and recursive references in OpenAPI by replacing them with obj
 
 ```
 USAGE
-  $ rdme openapi resolve [SPEC] [--out <value>] [--workingDirectory <value>]
+  $ rdme openapi resolve [SPEC] [--out <value>] [--title <value>] [--workingDirectory <value>]
 
 ARGUMENTS
   SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
         subdirectories contain a single OpenAPI file, you can omit the path.
 
 FLAGS
   --out=<value>               Output file path to write resolved file to
+  --title=<value>             An override value for the `info.title` field in the API definition
   --workingDirectory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
@@ -184,7 +185,7 @@ Upload (or re-upload) your API definition to ReadMe.
 
 ```
 USAGE
-  $ rdme openapi upload [SPEC] --key <value> [--slug <value>] [--useSpecVersion | --branch <value>]
+  $ rdme openapi upload [SPEC] --key <value> [--slug <value>] [--title <value>] [--useSpecVersion | --branch <value>]
 
 ARGUMENTS
   SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
@@ -194,6 +195,7 @@ FLAGS
   --key=<value>     (required) ReadMe project API key
   --branch=<value>  [default: stable] ReadMe project version
   --slug=<value>    Override the slug (i.e., the unique identifier) for your API definition.
+  --title=<value>   An override value for the `info.title` field in the API definition
   --useSpecVersion  Use the OpenAPI `info.version` field for your ReadMe project version
 
 DESCRIPTION

src/commands/openapi/convert.ts

@@ -14,6 +14,8 @@ import promptTerminal from '../../lib/promptWrapper.js';
 import { validateFilePath } from '../../lib/validatePromptInput.js';
 
 export default class OpenAPIConvertCommand extends BaseCommand<typeof OpenAPIConvertCommand> {
+  id = 'openapi convert' as const;
+
   static summary = 'Converts an API definition to OpenAPI and bundles any external references.';
 
   static description =
@@ -43,18 +45,15 @@ export default class OpenAPIConvertCommand extends BaseCommand<typeof OpenAPICon
   ];
 
   async run() {
-    const { spec } = this.args;
-    const { out, title, workingDirectory } = this.flags;
+    const { out, workingDirectory } = this.flags;
 
     if (workingDirectory) {
       const previousWorkingDirectory = process.cwd();
       process.chdir(workingDirectory);
       this.debug(`switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
     }
 
-    const { preparedSpec, specPath, specType } = await prepareOas(spec, 'openapi convert', {
-      title,
-    });
+    const { preparedSpec, specPath, specType } = await prepareOas.call(this);
     const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);
 
     if (specType === 'OpenAPI') {

src/commands/openapi/inspect.ts

@@ -198,6 +198,8 @@ function buildFullReport(analysis: Analysis, definitionVersion: string, tableBor
 }
 
 export default class OpenAPIInspectCommand extends BaseCommand<typeof OpenAPIInspectCommand> {
+  id = 'openapi inspect' as const;
+
   static summary = 'Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage.';
 
   static description =
@@ -251,7 +253,7 @@ export default class OpenAPIInspectCommand extends BaseCommand<typeof OpenAPIIns
       this.debug(`switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
     }
 
-    const { preparedSpec, definitionVersion } = await prepareOas(spec, 'openapi inspect');
+    const { preparedSpec, definitionVersion } = await prepareOas.call(this);
     const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);
 
     const spinner = ora({ ...oraOptions() });

src/commands/openapi/reduce.ts

@@ -18,6 +18,8 @@ import promptTerminal from '../../lib/promptWrapper.js';
 import { validateFilePath } from '../../lib/validatePromptInput.js';
 
 export default class OpenAPIReduceCommand extends BaseCommand<typeof OpenAPIReduceCommand> {
+  id = 'openapi reduce' as const;
+
   static summary = 'Reduce an OpenAPI definition into a smaller subset.';
 
   static description =
@@ -58,17 +60,16 @@ export default class OpenAPIReduceCommand extends BaseCommand<typeof OpenAPIRedu
   ];
 
   async run() {
-    const { spec } = this.args;
     const opts = this.flags;
-    const { title, workingDirectory } = opts;
+    const { workingDirectory } = opts;
 
     if (workingDirectory) {
       const previousWorkingDirectory = process.cwd();
       process.chdir(workingDirectory);
       this.debug(`switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
     }
 
-    const { preparedSpec, specPath, specType } = await prepareOas(spec, 'openapi reduce', { title });
+    const { preparedSpec, specPath, specType } = await prepareOas.call(this);
     const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);
 
     if (specType !== 'OpenAPI') {

src/commands/openapi/resolve.ts

@@ -11,7 +11,7 @@ import prompts from 'prompts';
 
 import analyzeOas from '../../lib/analyzeOas.js';
 import BaseCommand from '../../lib/baseCommand.js';
-import { specArg, workingDirectoryFlag } from '../../lib/flags.js';
+import { specArg, titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
 import { oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import promptTerminal from '../../lib/promptWrapper.js';
@@ -22,6 +22,8 @@ type Schema = OpenAPIV31.ReferenceObject | OpenAPIV31.SchemaObject;
 type SchemaCollection = Record<string, Schema>;
 
 export default class OpenAPIResolveCommand extends BaseCommand<typeof OpenAPIResolveCommand> {
+  id = 'openapi resolve' as const;
+
   static summary = 'Resolves circular and recursive references in OpenAPI by replacing them with object schemas.';
 
   static description =
@@ -50,6 +52,7 @@ export default class OpenAPIResolveCommand extends BaseCommand<typeof OpenAPIRes
 
   static flags = {
     out: Flags.string({ description: 'Output file path to write resolved file to' }),
+    title: titleFlag,
     workingDirectory: workingDirectoryFlag,
   };
 
@@ -349,7 +352,7 @@ export default class OpenAPIResolveCommand extends BaseCommand<typeof OpenAPIRes
       this.debug(`Switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
     }
 
-    const { preparedSpec, specPath, specType } = await prepareOas(spec, 'openapi resolve');
+    const { preparedSpec, specPath, specType } = await prepareOas.call(this);
     if (specType !== 'OpenAPI') {
       throw new Error('Sorry, this command only supports OpenAPI 3.0+ definitions.');
     }

src/commands/openapi/upload.ts

@@ -14,13 +14,15 @@ import prompts from 'prompts';
 import slugify from 'slugify';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { branchFlag, keyFlag, specArg } from '../../lib/flags.js';
+import { branchFlag, keyFlag, specArg, titleFlag } from '../../lib/flags.js';
 import isCI, { isTest } from '../../lib/isCI.js';
 import { oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import promptTerminal from '../../lib/promptWrapper.js';
 
 export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUploadCommand> {
+  id = 'openapi upload' as const;
+
   static summary = 'Upload (or re-upload) your API definition to ReadMe.';
 
   static description = [
@@ -56,6 +58,7 @@ export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUplo
         "You do not need to include a file extension (i.e., either `custom-slug.json` or `custom-slug` will work). If you do, it must match the file extension of the file you're uploading.",
       ].join('\n\n'),
     }),
+    title: titleFlag,
     useSpecVersion: Flags.boolean({
       summary: 'Use the OpenAPI `info.version` field for your ReadMe project version',
       description:
@@ -119,9 +122,7 @@ export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUplo
   }
 
   async run() {
-    const { spec } = this.args;
-
-    const { preparedSpec, specFileType, specType, specPath, specVersion } = await prepareOas(spec, 'openapi upload');
+    const { preparedSpec, specFileType, specType, specPath, specVersion } = await prepareOas.call(this);
 
     const branch = this.flags.useSpecVersion ? specVersion : this.flags.branch;
 

src/commands/openapi/validate.ts

@@ -5,6 +5,8 @@ import { githubFlag, specArg, workingDirectoryFlag } from '../../lib/flags.js';
 import prepareOas from '../../lib/prepareOas.js';
 
 export default class OpenAPIValidateCommand extends BaseCommand<typeof OpenAPIValidateCommand> {
+  id = 'openapi validate' as const;
+
   static summary = 'Validate your OpenAPI/Swagger definition.';
 
   static description =
@@ -41,7 +43,7 @@ export default class OpenAPIValidateCommand extends BaseCommand<typeof OpenAPIVa
       this.debug(`switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
     }
 
-    const { specPath, specType } = await prepareOas(this.args.spec, OpenAPIValidateCommand.id);
+    const { specPath, specType } = await prepareOas.call(this);
 
     return this.runCreateGHAHook({
       parsedOpts: { ...this.flags, spec: specPath },

src/index.ts

@@ -92,3 +92,14 @@ export type APIv2PageUploadCommands =
  * These commands can do more than just upload pages, but they are all backed by the APIv2 representations.
  */
 export type APIv2PageCommands = APIv2PageUploadCommands | DocsMigrateCommand;
+
+/**
+ * Every command that deals with OpenAPI definitions.
+ */
+export type OpenAPICommands =
+  | OpenAPIConvertCommand
+  | OpenAPIInspectCommand
+  | OpenAPIReduceCommand
+  | OpenAPIResolveCommand
+  | OpenAPIUploadCommand
+  | OpenAPIValidateCommand;

src/lib/baseCommand.ts

@@ -53,7 +53,7 @@ export default abstract class BaseCommand<T extends typeof OclifCommand> extends
   // protected property in the base oclif class
   declare debug: (...args: unknown[]) => void;
 
-  protected info(input: Parameters<typeof info>[0], opts: Parameters<typeof info>[1]): void {
+  public info(input: Parameters<typeof info>[0], opts?: Parameters<typeof info>[1]): void {
     if (!this.jsonEnabled()) {
       info(input, opts);
     }

src/lib/prepareOas.ts

@@ -1,13 +1,13 @@
 import type { OpenAPI } from 'openapi-types';
-import type { CommandIdForTopic } from '../index.js';
+import type { CommandIdForTopic, OpenAPICommands } from '../index.js';
 
 import chalk from 'chalk';
 import OASNormalize from 'oas-normalize';
 import { getAPIDefinitionType } from 'oas-normalize/lib/utils';
 import ora from 'ora';
 
 import isCI from './isCI.js';
-import { debug, info, oraOptions } from './logger.js';
+import { oraOptions } from './logger.js';
 import promptTerminal from './promptWrapper.js';
 import readdirRecursive from './readdirRecursive.js';
 
@@ -49,26 +49,9 @@ function capitalizeSpecType<T extends 'openapi' | 'postman' | 'swagger' | 'unkno
 /**
  * Normalizes, validates, and (optionally) bundles an OpenAPI definition.
  */
-export default async function prepareOas(
-  /**
-   * Path to a spec file. If this is missing, the current directory is searched for
-   * certain file names.
-   */
-  path: string | undefined,
-  /**
-   * The command context in which this is being run within (uploading a spec,
-   * validation, or reducing one).
-   */
-  command: `openapi ${OpenAPIAction}`,
-  opts: {
-    /**
-     * An optional title to replace the value in the `info.title` field.
-     * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#info-object}
-     */
-    title?: string;
-  } = {},
-) {
-  let specPath = path;
+export default async function prepareOas(this: OpenAPICommands) {
+  let specPath = this.args.spec;
+  const command = this.id satisfies `openapi ${OpenAPIAction}`;
 
   if (!specPath) {
     /**
@@ -97,31 +80,31 @@ export default async function prepareOas(
         file.toLowerCase().endsWith('.yml'),
     );
 
-    debug(`number of JSON or YAML files found: ${jsonAndYamlFiles.length}`);
+    this.debug(`number of JSON or YAML files found: ${jsonAndYamlFiles.length}`);
 
     const possibleSpecFiles: FoundSpecFile[] = (
       await Promise.all(
         jsonAndYamlFiles.map(file => {
-          debug(`attempting to oas-normalize ${file}`);
+          this.debug(`attempting to oas-normalize ${file}`);
           const oas = new OASNormalize(file, { enablePaths: true });
           return oas
             .version()
             .then(({ specification, version }) => {
-              debug(`specification type for ${file}: ${specification}`);
-              debug(`version for ${file}: ${version}`);
+              this.debug(`specification type for ${file}: ${specification}`);
+              this.debug(`version for ${file}: ${version}`);
               return ['openapi', 'swagger', 'postman'].includes(specification)
                 ? { filePath: file, specType: capitalizeSpecType(specification) as SpecType, version }
                 : null;
             })
             .catch(e => {
-              debug(`error extracting API definition specification version for ${file}: ${e.message}`);
+              this.debug(`error extracting API definition specification version for ${file}: ${e.message}`);
               return null;
             });
         }),
       )
     ).filter(truthy);
 
-    debug(`number of possible OpenAPI/Swagger files found: ${possibleSpecFiles.length}`);
+    this.debug(`number of possible OpenAPI/Swagger files found: ${possibleSpecFiles.length}`);
 
     if (!possibleSpecFiles.length) {
       fileFindingSpinner.fail();
@@ -134,7 +117,7 @@ export default async function prepareOas(
 
     if (possibleSpecFiles.length === 1) {
       fileFindingSpinner.stop();
-      info(chalk.yellow(`We found ${specPath} and are attempting to ${action} it.`));
+      this.info(chalk.yellow(`We found ${specPath} and are attempting to ${action} it.`));
     } else if (possibleSpecFiles.length > 1) {
       if (isCI()) {
         fileFindingSpinner.fail();
@@ -160,9 +143,9 @@ export default async function prepareOas(
 
   const spinner = ora({ text: `Validating the API definition located at ${specPath}...`, ...oraOptions() }).start();
 
-  debug(`about to normalize spec located at ${specPath}`);
+  this.debug(`about to normalize spec located at ${specPath}`);
   const oas = new OASNormalize(specPath, { colorizeErrors: true, enablePaths: true });
-  debug('spec normalized');
+  this.debug('spec normalized');
 
   // We're retrieving the original specification type here instead of after validation because if
   // they give us a Postman collection we should tell them that we handled a Postman collection, not
@@ -182,42 +165,42 @@ export default async function prepareOas(
     })
     .catch((err: Error) => {
       spinner.fail();
-      debug(`raw oas load error object: ${JSON.stringify(err)}`);
+      this.debug(`raw oas load error object: ${JSON.stringify(err)}`);
       throw err;
     });
 
   let api: OpenAPI.Document;
   await oas.validate().catch((err: Error) => {
     spinner.fail();
-    debug(`raw validation error object: ${JSON.stringify(err)}`);
+    this.debug(`raw validation error object: ${JSON.stringify(err)}`);
     throw err;
   });
 
   // If we were supplied a Postman collection this will **always** convert it to OpenAPI 3.0.
-  debug('converting the spec to OpenAPI 3.0 (if necessary)');
+  this.debug('converting the spec to OpenAPI 3.0 (if necessary)');
   api = await oas.convert().catch((err: Error) => {
     spinner.fail();
-    debug(`raw openapi conversion error object: ${JSON.stringify(err)}`);
+    this.debug(`raw openapi conversion error object: ${JSON.stringify(err)}`);
     throw err;
   });
 
   spinner.stop();
 
-  debug('👇👇👇👇👇 spec validated! logging spec below 👇👇👇👇👇');
-  debug(api);
-  debug('👆👆👆👆👆 finished logging spec 👆👆👆👆👆');
-  debug(`spec type: ${specType}`);
+  this.debug('👇👇👇👇👇 spec validated! logging spec below 👇👇👇👇👇');
+  this.debug(api);
+  this.debug('👆👆👆👆👆 finished logging spec 👆👆👆👆👆');
+  this.debug(`spec type: ${specType}`);
 
-  if (opts.title) {
-    debug(`renaming title field to ${opts.title}`);
-    api.info.title = opts.title;
+  if (this.flags.title) {
+    this.debug(`renaming title field to ${this.flags.title}`);
+    api.info.title = this.flags.title;
   }
 
   const specFileType = oas.type;
 
   // No need to optional chain here since `info.version` is required to pass validation
   const specVersion: string = api.info.version;
-  debug(`version in spec: ${specVersion}`);
+  this.debug(`version in spec: ${specVersion}`);
 
   const commandsThatBundle: (typeof command)[] = [
     'openapi inspect',
@@ -229,7 +212,7 @@ export default async function prepareOas(
   if (commandsThatBundle.includes(command)) {
     api = await oas.bundle();
 
-    debug('spec bundled');
+    this.debug('spec bundled');
   }
 
   return {