feat!: switch topic separator to space (#1100)

## 🧰 Changes

BREAKING CHANGE: the topic separator (i.e., what separates a command
from its subcommand) has changed from a colon to a space by default. For
example, `rdme openapi:validate` is now `rdme openapi validate`. The
colon topic separator will continue to be supported so there is no need
to change any existing commands, but all documentation and help screens
will reflect the space topic separator.

## 🧬 QA & Testing

Do tests still pass?

.github/workflows/ci.yml

@@ -73,22 +73,27 @@ jobs:
         run: npm ci && npm run build:gha
         working-directory: rdme-repo
 
-      - name: Run `openapi:validate` command
+      - name: Run `openapi validate` command
+        uses: ./rdme-repo/
+        with:
+          rdme: openapi validate oas-examples-repo/3.1/json/petstore.json
+
+      - name: Run `openapi validate` command (legacy topic separator)
         uses: ./rdme-repo/
         with:
           rdme: openapi:validate oas-examples-repo/3.1/json/petstore.json
 
-      - name: Run `openapi:validate` with filename in quotes
+      - name: Run `openapi validate` with filename in quotes
         uses: ./rdme-repo/
         with:
-          rdme: openapi:validate "oas-examples-repo/3.1/json/petstore.json"
+          rdme: openapi validate "oas-examples-repo/3.1/json/petstore.json"
 
-      - name: Run `openapi:validate` on an invalid file
+      - name: Run `openapi validate` on an invalid file
         uses: ./rdme-repo/
         id: openapi-validate-fail
         continue-on-error: true
         with:
-          rdme: openapi:validate rdme-repo/__tests__/__fixtures__/invalid-oas.json
+          rdme: openapi validate rdme-repo/__tests__/__fixtures__/invalid-oas.json
 
       - name: Assert that previous validation step failed
         if: ${{ steps.openapi-validate-fail.outcome == 'failure' }}

CONTRIBUTING.md

@@ -12,10 +12,10 @@ 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
+rdme openapi validate __tests__/__fixtures__/ref-oas/petstore.json
 
 # ... your local test command will look like this:
-bin/dev.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
+bin/dev.js openapi validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
 The `bin/dev.js` file has a few features that are useful for local development:
@@ -27,7 +27,7 @@ The `bin/dev.js` file has a few features that are useful for local development:
 
 ```sh
 npm run build
-bin/run.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
+bin/run.js openapi validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
 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).

README.md

@@ -81,7 +81,7 @@ npm install rdme --save-dev
 Once installed in your project, you can use the `npx` prefix (which is included if you have `npm` installed) to run your CLI commands locally. For example:
 
 ```sh
-npx rdme openapi:validate [file]
+npx rdme openapi validate [file]
 ```
 
 To ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date.

__tests__/commands/categories/create.test.ts

@@ -8,7 +8,7 @@ import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 const key = 'API_KEY';
 const version = '1.0.0';
 
-describe('rdme categories:create', () => {
+describe('rdme categories create', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {

__tests__/commands/docs/prune.test.ts

@@ -11,7 +11,7 @@ const fixturesBaseDir = '__fixtures__/docs';
 const key = 'API_KEY';
 const version = '1.0.0';
 
-describe('rdme docs:prune', () => {
+describe('rdme docs prune', () => {
   const folder = `./__tests__/${fixturesBaseDir}/delete-docs`;
   let run: (args?: string[]) => Promise<string>;
 
@@ -162,10 +162,10 @@ describe('rdme docs:prune', () => {
     versionMock.done();
   });
 
-  describe('rdme guides:prune', () => {
+  describe('rdme guides prune', () => {
     it('should error if no folder provided', async () => {
       return expect(
-        (await runCommandWithHooks(['guides:prune', '--key', key, '--version', version])).error.message,
+        (await runCommandWithHooks(['guides', 'prune', '--key', key, '--version', version])).error.message,
       ).toContain('Missing 1 required arg:\nfolder');
     });
   });

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

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`rdme openapi:inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/readme.…' (w/ [ 'polymorphism' ]) 1`] = `
+exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/readme.…' (w/ [ 'polymorphism' ]) 1`] = `
 "
 polymorphism:
  · #/components/responses/authForbidden/content/application~1json/schema
@@ -50,7 +50,7 @@ polymorphism:
  · #/paths/~1version/post/responses/400/content/application~1json/schema"
 `;
 
-exports[`rdme openapi:inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/readme-…' (w/ [ 'readme' ]) 1`] = `
+exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/readme-…' (w/ [ 'readme' ]) 1`] = `
 "
 x-default: You do not use this.
 x-readme.code-samples:
@@ -76,7 +76,7 @@ x-readme.samples-languages:
  · swift"
 `;
 
-exports[`rdme openapi:inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'additionalProperties', …(1) ]) 1`] = `
+exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'additionalProperties', …(1) ]) 1`] = `
 "
 additionalProperties:
  · #/components/schemas/BodyPart/properties/headers/additionalProperties
@@ -97,7 +97,7 @@ circularRefs:
  · #/components/schemas/ZoneOffset/properties/rules"
 `;
 
-exports[`rdme openapi:inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'additionalProperties', …(2) ]) 1`] = `
+exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'additionalProperties', …(2) ]) 1`] = `
 "
 additionalProperties:
  · #/components/schemas/BodyPart/properties/headers/additionalProperties
@@ -125,7 +125,7 @@ x-readme.proxy-enabled: You do not use this.
 x-readme.samples-languages: You do not use this."
 `;
 
-exports[`rdme openapi:inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'circularRefs', 'readme' ]) 1`] = `
+exports[`rdme openapi inspect > feature reports > should generate a report for '@readme/oas-examples/3.0/json/schema-…' (w/ [ 'circularRefs', 'readme' ]) 1`] = `
 "
 circularRefs:
  · #/components/schemas/MultiPart/properties/parent
@@ -139,7 +139,7 @@ x-readme.proxy-enabled: You do not use this.
 x-readme.samples-languages: You do not use this."
 `;
 
-exports[`rdme openapi:inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/petstore.json 1`] = `
+exports[`rdme openapi inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/petstore.json 1`] = `
 "Here are some interesting things we found in your API definition. 🕵️
 
  · You are using 4 Media Types throughout your API: application/json, application/x-www-form-urlencoded, application/xml, and multipart/form-data
@@ -249,7 +249,7 @@ ReadMe-Specific Features and Extensions
 "
 `;
 
-exports[`rdme openapi:inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/readme.json 1`] = `
+exports[`rdme openapi inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/readme.json 1`] = `
 "Here are some interesting things we found in your API definition. 🕵️
 
  · You are using 2 Media Types throughout your API: application/json and multipart/form-data
@@ -359,7 +359,7 @@ ReadMe-Specific Features and Extensions
 "
 `;
 
-exports[`rdme openapi:inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/readme-extensions.json 1`] = `
+exports[`rdme openapi inspect > full reports > should generate a report for @readme/oas-examples/3.0/json/readme-extensions.json 1`] = `
 "Here are some interesting things we found in your API definition. 🕵️
 
  · You are using a single Media Type throughout your API: application/json

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

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`rdme openapi:validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (github flag enabled) 1`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (github flag enabled) 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -10,7 +10,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 (github flag enabled) 2`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt (github flag enabled) 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 🦉
@@ -30,14 +30,14 @@ jobs:
       - name: Check out repo 📚
         uses: actions/checkout@v4
 
-      - name: Run \`openapi:validate\` command 🚀
+      - name: Run \`openapi validate\` command 🚀
         uses: readmeio/rdme@v7
         with:
-          rdme: openapi:validate __tests__/__fixtures__/petstore-simple-weird-version.json
+          rdme: openapi validate __tests__/__fixtures__/petstore-simple-weird-version.json
 "
 `;
 
-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 workingDirectory) 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -47,7 +47,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 workingDirectory) 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 🦉
@@ -67,14 +67,14 @@ jobs:
       - name: Check out repo 📚
         uses: actions/checkout@v4
 
-      - name: Run \`openapi:validate\` command 🚀
+      - 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 --workingDirectory=./__tests__/__fixtures__/relative-ref-oas
 "
 `;
 
-exports[`rdme openapi:validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt 1`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -84,7 +84,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 2`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via opt 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 🦉
@@ -104,14 +104,14 @@ jobs:
       - name: Check out repo 📚
         uses: actions/checkout@v4
 
-      - name: Run \`openapi:validate\` command 🚀
+      - name: Run \`openapi validate\` command 🚀
         uses: readmeio/rdme@v7
         with:
-          rdme: openapi:validate __tests__/__fixtures__/petstore-simple-weird-version.json
+          rdme: openapi validate __tests__/__fixtures__/petstore-simple-weird-version.json
 "
 `;
 
-exports[`rdme openapi:validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via prompts 1`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via prompts 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -121,7 +121,7 @@ Almost done! Push your newly created file (.github/workflows/validate-test-file.
 "
 `;
 
-exports[`rdme openapi:validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via prompts 2`] = `
+exports[`rdme openapi validate > GHA onboarding E2E tests > should create GHA workflow if user passes in spec via prompts 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 🦉
@@ -141,14 +141,14 @@ jobs:
       - name: Check out repo 📚
         uses: actions/checkout@v4
 
-      - name: Run \`openapi:validate\` command 🚀
+      - name: Run \`openapi validate\` command 🚀
         uses: readmeio/rdme@v7
         with:
-          rdme: openapi:validate __tests__/__fixtures__/petstore-simple-weird-version.json
+          rdme: openapi validate __tests__/__fixtures__/petstore-simple-weird-version.json
 "
 `;
 
-exports[`rdme openapi:validate > error handling > should throw an error if an invalid API definition has many errors 1`] = `
+exports[`rdme openapi validate > error handling > should throw an error if an invalid API definition has many errors 1`] = `
 [SyntaxError: OpenAPI schema validation failed.
 
 REQUIRED must have required property 'url'
@@ -172,9 +172,9 @@ ADDITIONAL PROPERTY must NOT have additional properties
   29 |         "summary": "Finds Pets by status",]
 `;
 
-exports[`rdme openapi:validate > error handling > should throw an error if an invalid OpenAPI 3.0 definition is supplied 1`] = `[MissingPointerError: Token "Error" does not exist.]`;
+exports[`rdme openapi validate > error handling > should throw an error if an invalid OpenAPI 3.0 definition is supplied 1`] = `[MissingPointerError: Token "Error" does not exist.]`;
 
-exports[`rdme openapi:validate > error handling > should throw an error if an invalid OpenAPI 3.1 definition is supplied 1`] = `
+exports[`rdme openapi validate > error handling > should throw an error if an invalid OpenAPI 3.1 definition is supplied 1`] = `
 [SyntaxError: OpenAPI schema validation failed.
 
 REQUIRED must have required property 'name'
@@ -188,7 +188,7 @@ REQUIRED must have required property 'name'
   29 |     }]
 `;
 
-exports[`rdme openapi:validate > error handling > should throw an error if an invalid Swagger definition is supplied 1`] = `
+exports[`rdme openapi validate > error handling > should throw an error if an invalid Swagger definition is supplied 1`] = `
 [SyntaxError: Swagger schema validation failed.
 
 ADDITIONAL PROPERTY must NOT have additional properties

__tests__/commands/openapi/convert.test.ts

@@ -8,7 +8,7 @@ import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
 const successfulConversion = () => 'Your API definition has been converted and bundled and saved to output.json!';
 
-describe('rdme openapi:convert', () => {
+describe('rdme openapi convert', () => {
   let run: (args?: string[]) => Promise<string>;
   let testWorkingDir: string;
 

__tests__/commands/openapi/inspect.test.ts

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

__tests__/commands/openapi/reduce.test.ts

@@ -13,7 +13,7 @@ const successfulReduction = () => 'Your reduced API definition has been saved to
 let consoleInfoSpy: MockInstance;
 const getCommandOutput = () => consoleInfoSpy.mock.calls.join('\n\n');
 
-describe('rdme openapi:reduce', () => {
+describe('rdme openapi reduce', () => {
   let run: (args?: string[]) => Promise<unknown>;
   let testWorkingDir: string;
 

__tests__/commands/openapi/validate.test.ts

@@ -16,7 +16,7 @@ const getCommandOutput = () => {
   return [consoleInfoSpy.mock.calls.join('\n\n')].filter(Boolean).join('\n\n');
 };
 
-describe('rdme openapi:validate', () => {
+describe('rdme openapi validate', () => {
   let run: (args?: string[]) => Promise<string>;
   let testWorkingDir: string;
 
@@ -122,7 +122,7 @@ describe('rdme openapi:validate', () => {
       return expect(
         (
           await runCommandWithHooks([
-            'openapi:validate',
+            'openapi validate',
             '__tests__/__fixtures__/petstore-simple-weird-version.json',
             '--github',
           ])

__tests__/commands/versions/create.test.ts

@@ -10,7 +10,7 @@ import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 const key = 'API_KEY';
 const version = '1.0.0';
 
-describe('rdme versions:create', () => {
+describe('rdme versions create', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {
@@ -26,7 +26,7 @@ describe('rdme versions:create', () => {
 
   it('should error if invalid version provided', () => {
     return expect(run(['--key', key, 'test'])).rejects.toStrictEqual(
-      new Error('Please specify a semantic version. See `rdme help versions:create` for help.'),
+      new Error('Please specify a semantic version. See `rdme help versions create` for help.'),
     );
   });
 

__tests__/commands/versions/delete.test.ts

@@ -9,7 +9,7 @@ import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 const key = 'API_KEY';
 const version = '1.0.0';
 
-describe('rdme versions:delete', () => {
+describe('rdme versions delete', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {

__tests__/commands/versions/update.test.ts

@@ -10,7 +10,7 @@ import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 const key = 'API_KEY';
 const version = '1.0.0';
 
-describe('rdme versions:update', () => {
+describe('rdme versions update', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {

__tests__/lib/createGHA.test.ts

@@ -55,6 +55,8 @@ describe('#createGHA', () => {
       label: string;
       opts: Record<string, string>;
     }>([
+      // `openapi:validate` is the ID we define in src/index.ts for backwards compatibility,
+      // hence we're using this command ID here
       { cmd: 'openapi:validate', opts: { spec: 'petstore.json' }, label: '' },
       { cmd: 'openapi', opts: { key, spec: 'petstore.json', id: 'spec_id' }, label: '' },
       { cmd: 'docs', opts: { key, path: './docs', version: '1.0.0' }, label: '' },