Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

…rity-and-recursiveness

CONTRIBUTING.md

@@ -8,15 +8,13 @@ To get started, run the `build` script to create a symlink with `package.json` (
 npm run build
 ```
 
-To run test commands, use `./bin/dev.js` instead of `rdme`. For example, if the command you're testing looks like this...
+To run test commands, swap out `rdme` for `bin/dev.js`. For example:
 
 ```sh
+# if the production command you're testing looks like this...
 rdme openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
-```
-
-... your local command will look like this:
 
-```sh
+# ... your local test command will look like this:
 bin/dev.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
@@ -32,7 +30,7 @@ npm run build
 bin/run.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
-Your changes to the command code may make changes to [the command reference document](./documentation/commands.md) — it is up to you whether you include those changes in your PR or if you let the release process take care of it. More information on that can be found in [MAINTAINERS.md](./MAINTAINERS.md).
+Your changes to the command code may make changes to [the command reference documents](./documentation/commands) — it is up to you whether you include those changes in your PR or if you let the release process take care of it. More information on that can be found in [`MAINTAINERS.md`](./MAINTAINERS.md).
 
 ## Running GitHub Actions Locally 🐳
 

MAINTAINERS.md

@@ -15,7 +15,7 @@ When code is merged into the `main` or `next` branches, a release workflow (powe
 - Based on the changes, the version is bumped in [`package.json`](./package.json) 🥊 For example, say the current version is `8.5.1` and the commit history includes a new feature. This would result in a minor semver bump, which would produce the following tags:
   - A release tag like `v8.6.0` if on the `main` branch
   - A prerelease tag like `v8.6.0-next.1` if on the `next` branch
-- A few other files, such as [`CHANGELOG.md`](./CHANGELOG.md), [the command reference page](./documentation/commands.md), and our GitHub Actions bundle files, are updated based on this code 🪵
+- A few other files, such as [`CHANGELOG.md`](./CHANGELOG.md), [the command reference pages](./documentation/commands), and our GitHub Actions bundle files, are updated based on this code 🪵
 - A build commit (like [this](https://github.com/readmeio/rdme/commit/533a2db50b39c3b6130b3af07bebaed38218db4c)) is created with all of the updated files (e.g., `package.json`, `CHANGELOG.md`, etc.) 🆕
 - A couple duplicated tags are created for the current commit so our users can refer to them differently in their GitHub Actions (e.g., `8.6.0`, `v8`) 🔖
 - The new commit and tags are pushed to GitHub 📌

__tests__/commands/categories/create.test.ts

@@ -3,7 +3,7 @@ import { describe, beforeAll, afterEach, it, expect } from 'vitest';
 
 import Command from '../../../src/commands/categories/create.js';
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const key = 'API_KEY';
 const version = '1.0.0';
@@ -12,8 +12,8 @@ describe('rdme categories:create', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {
-    run = runCommand(Command);
     nock.disableNetConnect();
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => nock.cleanAll());

__tests__/commands/categories/index.test.ts

@@ -3,7 +3,7 @@ import { describe, beforeAll, afterEach, it, expect } from 'vitest';
 
 import Command from '../../../src/commands/categories/index.js';
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const key = 'API_KEY';
 const version = '1.0.0';
@@ -13,7 +13,7 @@ describe('rdme categories', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => nock.cleanAll());

__tests__/commands/changelogs/index.test.ts

@@ -10,7 +10,7 @@ import Command from '../../../src/commands/changelogs.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock } from '../../helpers/get-api-mock.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const fixturesBaseDir = '__fixtures__/changelogs';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -21,7 +21,7 @@ describe('rdme changelogs', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/changelogs/single.test.ts

@@ -10,7 +10,7 @@ import Command from '../../../src/commands/changelogs.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock } from '../../helpers/get-api-mock.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const fixturesBaseDir = '__fixtures__/changelogs';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -21,7 +21,7 @@ describe('rdme changelogs (single)', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/custompages/index.test.ts

@@ -10,7 +10,7 @@ import Command from '../../../src/commands/custompages.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock } from '../../helpers/get-api-mock.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const fixturesBaseDir = '__fixtures__/custompages';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -21,7 +21,7 @@ describe('rdme custompages', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/custompages/single.test.ts

@@ -10,7 +10,7 @@ import Command from '../../../src/commands/custompages.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock } from '../../helpers/get-api-mock.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const fixturesBaseDir = '__fixtures__/custompages';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -21,7 +21,7 @@ describe('rdme custompages (single)', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/docs/index.test.ts

@@ -14,8 +14,8 @@ import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
 import { after, before } from '../../helpers/get-gha-setup.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
+import { runCommandAndReturnResult, runCommandWithHooks } from '../../helpers/oclif.js';
 import { after as afterGHAEnv, before as beforeGHAEnv } from '../../helpers/setup-gha-env.js';
-import { runCommand, runCommandWithHooks } from '../../helpers/setup-oclif-config.js';
 
 const fixturesBaseDir = '__fixtures__/docs';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -29,7 +29,7 @@ describe('rdme docs', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/docs/multiple.test.ts

@@ -8,7 +8,7 @@ import { describe, beforeAll, afterAll, it, expect } from 'vitest';
 import Command from '../../../src/commands/docs/index.js';
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const fixturesBaseDir = '__fixtures__/docs';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -21,7 +21,7 @@ describe('rdme docs (multiple)', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/docs/prune.test.ts

@@ -4,7 +4,7 @@ import { describe, beforeAll, afterAll, it, expect } from 'vitest';
 
 import Command from '../../../src/commands/docs/prune.js';
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
-import { runCommand, runCommandWithHooks } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult, runCommandWithHooks } from '../../helpers/oclif.js';
 
 const fixturesBaseDir = '__fixtures__/docs';
 
@@ -17,7 +17,7 @@ describe('rdme docs:prune', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/docs/single.test.ts

@@ -10,8 +10,8 @@ import Command from '../../../src/commands/docs/index.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
 import hashFileContents from '../../helpers/hash-file-contents.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 import { after as afterGHAEnv, before as beforeGHAEnv } from '../../helpers/setup-gha-env.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
 
 const fixturesBaseDir = '__fixtures__/docs';
 const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
@@ -25,7 +25,7 @@ describe('rdme docs (single)', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterAll(() => nock.cleanAll());

__tests__/commands/login.test.ts

@@ -6,7 +6,7 @@ import Command from '../../src/commands/login.js';
 import { APIv1Error } from '../../src/lib/apiError.js';
 import configStore from '../../src/lib/configstore.js';
 import { getAPIV1Mock } from '../helpers/get-api-mock.js';
-import { runCommand } from '../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../helpers/oclif.js';
 
 const apiKey = 'abcdefg';
 const email = '[email protected]';
@@ -19,7 +19,7 @@ describe('rdme login', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => configStore.clear());

__tests__/commands/logout.test.ts

@@ -3,13 +3,13 @@ import { describe, afterEach, beforeAll, it, expect } from 'vitest';
 import pkg from '../../package.json';
 import Command from '../../src/commands/logout.js';
 import configStore from '../../src/lib/configstore.js';
-import { runCommand } from '../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../helpers/oclif.js';
 
 describe('rdme logout', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => {

__tests__/commands/open.test.ts

@@ -7,15 +7,15 @@ import pkg from '../../package.json';
 import Command from '../../src/commands/open.js';
 import configStore from '../../src/lib/configstore.js';
 import { getAPIV1Mock } from '../helpers/get-api-mock.js';
-import { runCommand } from '../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../helpers/oclif.js';
 
 const mockArg = ['--mock'];
 
 describe('rdme open', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => {

__tests__/commands/openapi/convert.test.ts

@@ -4,7 +4,7 @@ import prompts from 'prompts';
 import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from 'vitest';
 
 import Command from '../../../src/commands/openapi/convert.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const successfulConversion = () => 'Your API definition has been converted and bundled and saved to output.json!';
 
@@ -13,7 +13,7 @@ describe('rdme openapi:convert', () => {
   let testWorkingDir: string;
 
   beforeAll(() => {
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   beforeEach(() => {

__tests__/commands/openapi/index.test.ts

@@ -13,8 +13,8 @@ import config from '../../../src/lib/config.js';
 import petstoreWeird from '../../__fixtures__/petstore-simple-weird-version.json' with { type: 'json' };
 import { getAPIV1Mock, getAPIV1MockWithVersionHeader } from '../../helpers/get-api-mock.js';
 import { after, before } from '../../helpers/get-gha-setup.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 import { after as afterGHAEnv, before as beforeGHAEnv } from '../../helpers/setup-gha-env.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
 
 let consoleInfoSpy: MockInstance;
 let consoleWarnSpy: MockInstance;
@@ -55,7 +55,7 @@ describe('rdme openapi', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   beforeEach(() => {

__tests__/commands/openapi/inspect.test.ts

@@ -5,13 +5,13 @@ import assert from 'node:assert';
 import { describe, it, expect, beforeAll } from 'vitest';
 
 import Command from '../../../src/commands/openapi/inspect.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 describe('rdme openapi:inspect', () => {
   let run: (args?: string[]) => Promise<unknown>;
 
   beforeAll(() => {
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   describe('full reports', () => {

__tests__/commands/openapi/reduce.test.ts

@@ -6,7 +6,7 @@ import prompts from 'prompts';
 import { describe, beforeAll, beforeEach, afterEach, it, expect, vi, type MockInstance } from 'vitest';
 
 import Command from '../../../src/commands/openapi/reduce.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const successfulReduction = () => 'Your reduced API definition has been saved to output.json! 🤏';
 
@@ -18,7 +18,7 @@ describe('rdme openapi:reduce', () => {
   let testWorkingDir: string;
 
   beforeAll(() => {
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   beforeEach(() => {

__tests__/commands/openapi/validate.test.ts

@@ -8,7 +8,7 @@ import { describe, beforeAll, beforeEach, afterEach, it, expect, vi, type MockIn
 
 import Command from '../../../src/commands/openapi/validate.js';
 import { after, before } from '../../helpers/get-gha-setup.js';
-import { runCommand, runCommandWithHooks } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult, runCommandWithHooks } from '../../helpers/oclif.js';
 
 let consoleInfoSpy: MockInstance;
 
@@ -21,7 +21,7 @@ describe('rdme openapi:validate', () => {
   let testWorkingDir: string;
 
   beforeAll(() => {
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   beforeEach(() => {

__tests__/commands/versions/create.test.ts

@@ -5,7 +5,7 @@ import { describe, beforeAll, afterEach, it, expect } from 'vitest';
 import Command from '../../../src/commands/versions/create.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock } from '../../helpers/get-api-mock.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const key = 'API_KEY';
 const version = '1.0.0';
@@ -15,7 +15,7 @@ describe('rdme versions:create', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => nock.cleanAll());

__tests__/commands/versions/delete.test.ts

@@ -4,7 +4,7 @@ import { describe, beforeAll, afterEach, it, expect } from 'vitest';
 import Command from '../../../src/commands/versions/delete.js';
 import { APIv1Error } from '../../../src/lib/apiError.js';
 import { getAPIV1Mock } from '../../helpers/get-api-mock.js';
-import { runCommand } from '../../helpers/setup-oclif-config.js';
+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const key = 'API_KEY';
 const version = '1.0.0';
@@ -14,7 +14,7 @@ describe('rdme versions:delete', () => {
 
   beforeAll(() => {
     nock.disableNetConnect();
-    run = runCommand(Command);
+    run = runCommandAndReturnResult(Command);
   });
 
   afterEach(() => nock.cleanAll());