fix(openapi/upload): restore --working-directory (#1369)

| 🚥 Resolves #1350, CX-2286 |
| :------------------- |

## 🧰 Changes

restores the `--working-directory` (formerly known as
`--workingDirectory`) flag for `openapi upload`. more chatter about this
can be found
[here](https://linear.app/readme-io/issue/CX-2286/cli-openapi-upload-command-not-respecting-relative-working-directory#comment-ee239f54).

## 🧬 QA & Testing

do tests pass?

Author: kanadgupta

__tests__/commands/openapi/__snapshots__/validate.test.ts.snap

@@ -65,7 +65,7 @@ jobs:
 "
 `;
 
-exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (including workingDirectory) 1`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (including working directory) 1`] = `
 {
   "result": "
 Your GitHub Actions workflow file has been created! ✨
@@ -88,7 +88,7 @@ Almost done! Push your newly created file (.github/workflows/validate-test-opt-s
 }
 `;
 
-exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (including workingDirectory) 2`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (including working directory) 2`] = `
 "# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
 # You can view our full documentation here: https://docs.readme.com/docs/rdme
 name: ReadMe GitHub Action 🦉
@@ -111,7 +111,7 @@ jobs:
       - name: Run \`openapi validate\` command 🚀
         uses: readmeio/rdme@v7
         with:
-          rdme: openapi validate petstore.json --workingDirectory=./__tests__/__fixtures__/relative-ref-oas
+          rdme: openapi validate petstore.json --working-directory=./__tests__/__fixtures__/relative-ref-oas
 "
 `;
 
@@ -348,6 +348,17 @@ exports[`rdme openapi validate > should discover and upload an API definition if
 }
 `;
 
+exports[`rdme openapi validate > should use specified working directory (legacy flag) 1`] = `
+{
+  "result": "petstore.json is a valid OpenAPI API definition!",
+  "stderr": " ›   Warning: The "--workingDirectory" flag has been deprecated. Use 
+ ›   "--working-directory" instead.
+- Validating the API definition located at petstore.json...
+",
+  "stdout": "",
+}
+`;
+
 exports[`rdme openapi validate > should use specified working directory 1`] = `
 {
   "result": "petstore.json is a valid OpenAPI API definition!",

__tests__/commands/openapi/convert.test.ts

@@ -58,7 +58,7 @@ describe('rdme openapi convert', () => {
     await expect(
       run([
         spec,
-        '--workingDirectory',
+        '--working-directory',
         require.resolve(`@readme/oas-examples/2.0/json/${spec}`).replace(spec, ''),
         '--out',
         'output.json',
@@ -79,7 +79,7 @@ describe('rdme openapi convert', () => {
       await expect(
         run([
           spec,
-          '--workingDirectory',
+          '--working-directory',
           require.resolve(`@readme/oas-examples/3.0/${format}/${spec}`).replace(spec, ''),
         ]),
       ).resolves.toMatchSnapshot();

__tests__/commands/openapi/reduce.test.ts

@@ -62,7 +62,7 @@ describe('rdme openapi reduce', () => {
         prompts.inject(['tags', ['user'], 'output.json']);
 
         await expect(
-          run(['--workingDirectory', './__tests__/__fixtures__/relative-ref-oas']),
+          run(['--working-directory', './__tests__/__fixtures__/relative-ref-oas']),
         ).resolves.toMatchSnapshot();
 
         expect(Object.keys(reducedSpec.paths)).toStrictEqual(['/user']);
@@ -71,7 +71,7 @@ describe('rdme openapi reduce', () => {
       it('should reduce with no prompts via opts', async () => {
         await expect(
           run([
-            '--workingDirectory',
+            '--working-directory',
             './__tests__/__fixtures__/relative-ref-oas',
             '--tag',
             'user',
@@ -108,7 +108,7 @@ describe('rdme openapi reduce', () => {
       it('should reduce with no prompts via opts', async () => {
         await expect(
           run([
-            '--workingDirectory',
+            '--working-directory',
             './__tests__/__fixtures__/relative-ref-oas',
             '--path',
             '/pet',
@@ -134,7 +134,7 @@ describe('rdme openapi reduce', () => {
 
         await expect(
           run([
-            '--workingDirectory',
+            '--working-directory',
             './__tests__/__fixtures__/relative-ref-oas',
             '--path',
             '/pet',

__tests__/commands/openapi/validate.test.ts

@@ -40,11 +40,16 @@ describe('rdme openapi validate', () => {
   });
 
   it('should discover and upload an API definition if none is provided', async () => {
-    const result = await run(['--workingDirectory', './__tests__/__fixtures__/relative-ref-oas']);
+    const result = await run(['--working-directory', './__tests__/__fixtures__/relative-ref-oas']);
     expect(result).toMatchSnapshot();
   });
 
   it('should use specified working directory', async () => {
+    const result = await run(['petstore.json', '--working-directory', './__tests__/__fixtures__/relative-ref-oas']);
+    expect(result).toMatchSnapshot();
+  });
+
+  it('should use specified working directory (legacy flag)', async () => {
     const result = await run(['petstore.json', '--workingDirectory', './__tests__/__fixtures__/relative-ref-oas']);
     expect(result).toMatchSnapshot();
   });
@@ -55,7 +60,7 @@ describe('rdme openapi validate', () => {
       './__tests__/__fixtures__/nested-gitignored-oas/nest/petstore-ignored.json',
     );
 
-    const result = await run(['--workingDirectory', './__tests__/__fixtures__/nested-gitignored-oas']);
+    const result = await run(['--working-directory', './__tests__/__fixtures__/nested-gitignored-oas']);
     expect(result).toMatchSnapshot();
   });
 
@@ -138,13 +143,13 @@ describe('rdme openapi validate', () => {
       expect(fs.writeFileSync).toHaveBeenCalledWith(`.github/workflows/${fileName}.yml`, expect.any(String));
     });
 
-    it('should create GHA workflow if user passes in spec via opt (including workingDirectory)', async () => {
+    it('should create GHA workflow if user passes in spec via opt (including working directory)', async () => {
       const spec = 'petstore.json';
       const fileName = 'validate-test-opt-spec-workdir-file';
       prompts.inject([true, 'validate-test-opt-spec-github-branch', fileName]);
 
       await expect(
-        run([spec, '--workingDirectory', './__tests__/__fixtures__/relative-ref-oas']),
+        run([spec, '--working-directory', './__tests__/__fixtures__/relative-ref-oas']),
       ).resolves.toMatchSnapshot();
 
       expect(yamlOutput).toMatchSnapshot();

documentation/commands/openapi.md

@@ -16,16 +16,16 @@ Converts an API definition to OpenAPI and bundles any external references.
 
 ```
 USAGE
-  $ rdme openapi convert [SPEC] [--out <value>] [--title <value>] [--workingDirectory <value>]
+  $ rdme openapi convert [SPEC] [--out <value>] [--title <value>] [--working-directory <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 converted 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)
+  --out=<value>                Output file path to write converted file to
+  --title=<value>              An override value for the `info.title` field in the API definition
+  --working-directory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
   Converts an API definition to OpenAPI and bundles any external references.
@@ -54,7 +54,7 @@ Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usa
 USAGE
   $ rdme openapi inspect [SPEC] [--feature
     additionalProperties|callbacks|circularRefs|commonParameters|discriminators|links|style|polymorphism|serverVariables
-    |webhooks|xml|xmlRequests|xmlResponses|xmlSchemas|readme...] [--workingDirectory <value>]
+    |webhooks|xml|xmlRequests|xmlResponses|xmlSchemas|readme...] [--working-directory <value>]
 
 ARGUMENTS
   SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
@@ -67,7 +67,7 @@ FLAGS
       <options: additionalProperties|callbacks|circularRefs|commonParameters|discriminators|links|style|polymorphism|serve
       rVariables|webhooks|xml|xmlRequests|xmlResponses|xmlSchemas|readme>
 
-  --workingDirectory=<value>
+  --working-directory=<value>
       Working directory (for usage with relative external references)
 
 DESCRIPTION
@@ -102,19 +102,19 @@ Reduce an OpenAPI definition into a smaller subset.
 ```
 USAGE
   $ rdme openapi reduce [SPEC] [--method <value>...] [--out <value>] [--path <value>...] [--tag <value>...] [--title
-    <value>] [--workingDirectory <value>]
+    <value>] [--working-directory <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
-  --method=<value>...         Methods to reduce by (can only be used alongside the `path` option)
-  --out=<value>               Output file path to write reduced file to
-  --path=<value>...           Paths to reduce by
-  --tag=<value>...            Tags to reduce by
-  --title=<value>             An override value for the `info.title` field in the API definition
-  --workingDirectory=<value>  Working directory (for usage with relative external references)
+  --method=<value>...          Methods to reduce by (can only be used alongside the `path` option)
+  --out=<value>                Output file path to write reduced file to
+  --path=<value>...            Paths to reduce by
+  --tag=<value>...             Tags to reduce by
+  --title=<value>              An override value for the `info.title` field in the API definition
+  --working-directory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
   Reduce an OpenAPI definition into a smaller subset.
@@ -143,16 +143,16 @@ Resolves circular and recursive references in OpenAPI by replacing them with obj
 
 ```
 USAGE
-  $ rdme openapi resolve [SPEC] [--out <value>] [--title <value>] [--workingDirectory <value>]
+  $ rdme openapi resolve [SPEC] [--out <value>] [--title <value>] [--working-directory <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)
+  --out=<value>                Output file path to write resolved file to
+  --title=<value>              An override value for the `info.title` field in the API definition
+  --working-directory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
   Resolves circular and recursive references in OpenAPI by replacing them with object schemas.
@@ -186,20 +186,21 @@ Upload (or re-upload) your API definition to ReadMe.
 ```
 USAGE
   $ rdme openapi upload [SPEC] --key <value> [--confirm-overwrite] [--slug <value>] [--title <value>]
-    [--useSpecVersion | --branch <value>]
+    [--useSpecVersion | --branch <value>] [--working-directory <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
-  --key=<value>        (required) ReadMe project API key
-  --branch=<value>     [default: stable] ReadMe project version
-  --confirm-overwrite  If set, file overwrites will be made without a confirmation prompt. This flag can be a useful in
-                       automated environments where prompts cannot be responded to.
-  --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
+  --key=<value>                (required) ReadMe project API key
+  --branch=<value>             [default: stable] ReadMe project version
+  --confirm-overwrite          If set, file overwrites will be made without a confirmation prompt. This flag can be a
+                               useful in automated environments where prompts cannot be responded to.
+  --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
+  --working-directory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
   Upload (or re-upload) your API definition to ReadMe.
@@ -266,15 +267,15 @@ Validate your OpenAPI/Swagger definition.
 
 ```
 USAGE
-  $ rdme openapi validate [SPEC] [--github] [--workingDirectory <value>]
+  $ rdme openapi validate [SPEC] [--github] [--working-directory <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
-  --github                    Create a new GitHub Actions workflow for this command.
-  --workingDirectory=<value>  Working directory (for usage with relative external references)
+  --github                     Create a new GitHub Actions workflow for this command.
+  --working-directory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
   Validate your OpenAPI/Swagger definition.

src/commands/openapi/convert.ts

@@ -28,7 +28,7 @@ export default class OpenAPIConvertCommand extends BaseCommand<typeof OpenAPICon
   static flags = {
     out: Flags.string({ description: 'Output file path to write converted file to' }),
     title: titleFlag,
-    workingDirectory: workingDirectoryFlag,
+    'working-directory': workingDirectoryFlag,
   };
 
   static examples = [
@@ -45,13 +45,7 @@ export default class OpenAPIConvertCommand extends BaseCommand<typeof OpenAPICon
   ];
 
   async run() {
-    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 { out } = this.flags;
 
     const { preparedSpec, specPath, specType } = await prepareOas.call(this);
     const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);

src/commands/openapi/inspect.ts

@@ -216,7 +216,7 @@ export default class OpenAPIInspectCommand extends BaseCommand<typeof OpenAPIIns
       multiple: true,
       options: getSupportedFeatures(),
     }),
-    workingDirectory: workingDirectoryFlag,
+    'working-directory': workingDirectoryFlag,
   };
 
   static examples = [
@@ -239,19 +239,13 @@ export default class OpenAPIInspectCommand extends BaseCommand<typeof OpenAPIIns
   ];
 
   async run() {
-    const { workingDirectory, feature: features } = this.flags;
+    const { feature: features } = this.flags;
 
     const tableBorder = Object.entries(getBorderCharacters('norc'))
       .map(([border, char]) => ({ [border]: chalk.gray(char) }))
       // biome-ignore lint/performance/noAccumulatingSpread: @todo can this be improved?
       .reduce((prev, next) => Object.assign(prev, next));
 
-    if (workingDirectory) {
-      const previousWorkingDirectory = process.cwd();
-      process.chdir(workingDirectory);
-      this.debug(`switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
-    }
-
     const { preparedSpec, definitionVersion } = await prepareOas.call(this);
     const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);
 

src/commands/openapi/reduce.ts

@@ -38,7 +38,7 @@ export default class OpenAPIReduceCommand extends BaseCommand<typeof OpenAPIRedu
     path: Flags.string({ description: 'Paths to reduce by', multiple: true }),
     tag: Flags.string({ description: 'Tags to reduce by', multiple: true }),
     title: titleFlag,
-    workingDirectory: workingDirectoryFlag,
+    'working-directory': workingDirectoryFlag,
   };
 
   static examples = [
@@ -61,13 +61,6 @@ export default class OpenAPIReduceCommand extends BaseCommand<typeof OpenAPIRedu
 
   async run() {
     const opts = this.flags;
-    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.call(this);
     const parsedPreparedSpec: OASDocument = JSON.parse(preparedSpec);

src/commands/openapi/resolve.ts

@@ -53,7 +53,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,
+    'working-directory': workingDirectoryFlag,
   };
 
   /**
@@ -345,13 +345,7 @@ export default class OpenAPIResolveCommand extends BaseCommand<typeof OpenAPIRes
   }
 
   async run() {
-    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 { out } = this.flags;
 
     const { preparedSpec, specPath, specType } = await prepareOas.call(this);
     if (specType !== 'OpenAPI') {

src/commands/openapi/upload.ts

@@ -14,7 +14,7 @@ import prompts from 'prompts';
 import slugify from 'slugify';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { branchFlag, keyFlag, specArg, titleFlag } from '../../lib/flags.js';
+import { branchFlag, keyFlag, specArg, titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
 import isCI, { isTest } from '../../lib/isCI.js';
 import { oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
@@ -66,6 +66,7 @@ export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUplo
         'If included, use the version specified in the `info.version` field in your OpenAPI definition for your ReadMe project version. This flag is mutually exclusive with `--branch`.',
       exclusive: ['branch'],
     }),
+    'working-directory': workingDirectoryFlag,
   };
 
   static examples = [