From 75aaba287f5752c7ac4ee3d705e381c6bb90466c Mon Sep 17 00:00:00 2001 From: Jon Ursenbach Date: Thu, 8 Dec 2022 16:07:11 -0800 Subject: [PATCH] feat: dropping our `position` system for ordering commands in `--help` (#707) --- __tests__/__snapshots__/index.test.ts.snap | 14 +++++------ .../lib/__snapshots__/commands.test.ts.snap | 24 ------------------- __tests__/lib/commands.test.ts | 5 +--- src/cmds/categories/create.ts | 1 - src/cmds/categories/index.ts | 1 - src/cmds/changelogs.ts | 1 - src/cmds/custompages.ts | 1 - src/cmds/docs/edit.ts | 1 - src/cmds/docs/index.ts | 1 - src/cmds/docs/prune.ts | 1 - src/cmds/guides/index.ts | 1 - src/cmds/guides/prune.ts | 1 - src/cmds/login.ts | 1 - src/cmds/logout.ts | 1 - src/cmds/oas.ts | 1 - src/cmds/open.ts | 1 - src/cmds/openapi/index.ts | 1 - src/cmds/openapi/inspect.ts | 1 - src/cmds/openapi/reduce.ts | 1 - src/cmds/openapi/validate.ts | 1 - src/cmds/swagger.ts | 1 - src/cmds/validate.ts | 1 - src/cmds/versions/create.ts | 1 - src/cmds/versions/delete.ts | 1 - src/cmds/versions/index.ts | 1 - src/cmds/versions/update.ts | 1 - src/cmds/whoami.ts | 1 - src/lib/baseCommand.ts | 7 ------ src/lib/commands.ts | 2 -- src/lib/help.ts | 4 ++-- 30 files changed, 10 insertions(+), 70 deletions(-) diff --git a/__tests__/__snapshots__/index.test.ts.snap b/__tests__/__snapshots__/index.test.ts.snap index b99b587a4..524461b6b 100644 --- a/__tests__/__snapshots__/index.test.ts.snap +++ b/__tests__/__snapshots__/index.test.ts.snap @@ -30,10 +30,10 @@ Options Related commands - $ rdme openapi:reduce Reduce an OpenAPI definition into a smaller subset. - $ rdme openapi:validate Validate your OpenAPI/Swagger definition. $ rdme openapi:inspect Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage. + $ rdme openapi:reduce Reduce an OpenAPI definition into a smaller subset. + $ rdme openapi:validate Validate your OpenAPI/Swagger definition. " `; @@ -67,10 +67,10 @@ Options Related commands - $ rdme openapi:reduce Reduce an OpenAPI definition into a smaller subset. - $ rdme openapi:validate Validate your OpenAPI/Swagger definition. $ rdme openapi:inspect Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage. + $ rdme openapi:reduce Reduce an OpenAPI definition into a smaller subset. + $ rdme openapi:validate Validate your OpenAPI/Swagger definition. " `; @@ -104,10 +104,10 @@ Options Related commands - $ rdme openapi:reduce Reduce an OpenAPI definition into a smaller subset. - $ rdme openapi:validate Validate your OpenAPI/Swagger definition. $ rdme openapi:inspect Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage. + $ rdme openapi:reduce Reduce an OpenAPI definition into a smaller subset. + $ rdme openapi:validate Validate your OpenAPI/Swagger definition. " `; @@ -128,7 +128,7 @@ Options Related commands $ rdme versions:create Create a new version for your project. - $ rdme versions:update Update an existing version for your project. $ rdme versions:delete Delete a version associated with your ReadMe project. + $ rdme versions:update Update an existing version for your project. " `; diff --git a/__tests__/lib/__snapshots__/commands.test.ts.snap b/__tests__/lib/__snapshots__/commands.test.ts.snap index 987d70135..68cb4d75b 100644 --- a/__tests__/lib/__snapshots__/commands.test.ts.snap +++ b/__tests__/lib/__snapshots__/commands.test.ts.snap @@ -8,19 +8,16 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Login to a ReadMe project.", "hidden": false, "name": "login", - "position": 1, }, { "description": "Logs the currently authenticated user out of ReadMe.", "hidden": false, "name": "logout", - "position": 2, }, { "description": "Displays the current user and project authenticated with ReadMe.", "hidden": false, "name": "whoami", - "position": 3, }, ], "description": "Administration", @@ -31,37 +28,31 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Upload, or resync, your OpenAPI/Swagger definition to ReadMe.", "hidden": false, "name": "openapi", - "position": 1, }, { "description": "Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage.", "hidden": false, "name": "openapi:inspect", - "position": 4, }, { "description": "Reduce an OpenAPI definition into a smaller subset.", "hidden": false, "name": "openapi:reduce", - "position": 2, }, { "description": "Validate your OpenAPI/Swagger definition.", "hidden": false, "name": "openapi:validate", - "position": 3, }, { "description": "Alias for \`rdme openapi\`. [deprecated]", "hidden": true, "name": "swagger", - "position": 4, }, { "description": "Alias for \`rdme openapi:validate\` [deprecated].", "hidden": true, "name": "validate", - "position": 5, }, ], "description": "OpenAPI / Swagger", @@ -72,13 +63,11 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Get all categories in your ReadMe project.", "hidden": false, "name": "categories", - "position": 1, }, { "description": "Create a category with the specified title and guide in your ReadMe project.", "hidden": false, "name": "categories:create", - "position": 2, }, ], "description": "Categories", @@ -89,7 +78,6 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Sync Markdown files to your ReadMe project as Changelog posts. Can either be a path to a directory or a single Markdown file.", "hidden": false, "name": "changelogs", - "position": 1, }, ], "description": "Changelog", @@ -100,7 +88,6 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Sync Markdown/HTML files to your ReadMe project as Custom Pages. Can either be a path to a directory or a single Markdown/HTML file.", "hidden": false, "name": "custompages", - "position": 1, }, ], "description": "Custom Pages", @@ -111,31 +98,26 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Sync Markdown files to your ReadMe project as Guides. Can either be a path to a directory or a single Markdown file.", "hidden": false, "name": "docs", - "position": 1, }, { "description": "Delete any docs from ReadMe if their slugs are not found in the target folder.", "hidden": false, "name": "docs:prune", - "position": 2, }, { "description": "Edit a single file from your ReadMe project without saving locally. [deprecated]", "hidden": true, "name": "docs:edit", - "position": 3, }, { "description": "Alias for \`rdme docs\`.", "hidden": false, "name": "guides", - "position": 3, }, { "description": "Alias for \`rdme docs:prune\`.", "hidden": false, "name": "guides:prune", - "position": 4, }, ], "description": "Docs (a.k.a. Guides)", @@ -146,13 +128,11 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "Helpful OpenAPI generation tooling. [inactive]", "hidden": true, "name": "oas", - "position": 2, }, { "description": "Open your current ReadMe project in the browser.", "hidden": false, "name": "open", - "position": 1, }, ], "description": "Other useful commands", @@ -163,25 +143,21 @@ exports[`utils #listByCategory should list commands by category 1`] = ` "description": "List versions available in your project or get a version by SemVer (https://semver.org/).", "hidden": false, "name": "versions", - "position": 1, }, { "description": "Create a new version for your project.", "hidden": false, "name": "versions:create", - "position": 2, }, { "description": "Delete a version associated with your ReadMe project.", "hidden": false, "name": "versions:delete", - "position": 4, }, { "description": "Update an existing version for your project.", "hidden": false, "name": "versions:update", - "position": 3, }, ], "description": "Versions", diff --git a/__tests__/lib/commands.test.ts b/__tests__/lib/commands.test.ts index d43c6b2ca..394f684ad 100644 --- a/__tests__/lib/commands.test.ts +++ b/__tests__/lib/commands.test.ts @@ -22,7 +22,6 @@ describe('utils', () => { expect(cmd.usage).toStartWith(cmd.command); expect(cmd.description).not.toBeEmpty(); expect(cmd.cmdCategory).not.toBeEmpty(); - expect(cmd.position).toBeNumber(); expect(cmd.args).toBeArray(); expect(cmd.run).toBeFunction(); @@ -36,7 +35,7 @@ describe('utils', () => { }); describe('cli standards', () => { - describe.each<[string, Command]>(commands.list().map(cmd => [cmd.command.command, cmd.command]))( + describe.each<[string, Command]>(commands.list().map(cmd => [cmd.command.command, cmd.command as Command]))( '%s', (_, command) => { it('should have a description that ends with punctuation', () => { @@ -94,13 +93,11 @@ describe('utils', () => { { name: 'logout', description: 'Logs the currently authenticated user out of ReadMe.', - position: 2, hidden: false, }, { name: 'whoami', description: 'Displays the current user and project authenticated with ReadMe.', - position: 3, hidden: false, }, ]); diff --git a/src/cmds/categories/create.ts b/src/cmds/categories/create.ts index 4f6bf4f44..fcda65a62 100644 --- a/src/cmds/categories/create.ts +++ b/src/cmds/categories/create.ts @@ -28,7 +28,6 @@ export default class CategoriesCreateCommand extends Command { this.usage = 'categories:create [options]'; this.description = 'Create a category with the specified title and guide in your ReadMe project.'; this.cmdCategory = CommandCategories.CATEGORIES; - this.position = 2; this.hiddenArgs = ['title']; this.args = [ diff --git a/src/cmds/categories/index.ts b/src/cmds/categories/index.ts index cb572ed4f..8cf829ec0 100644 --- a/src/cmds/categories/index.ts +++ b/src/cmds/categories/index.ts @@ -12,7 +12,6 @@ export default class CategoriesCommand extends Command { this.usage = 'categories [options]'; this.description = 'Get all categories in your ReadMe project.'; this.cmdCategory = CommandCategories.CATEGORIES; - this.position = 1; this.args = [this.getKeyArg(), this.getVersionArg()]; } diff --git a/src/cmds/changelogs.ts b/src/cmds/changelogs.ts index 04cc272da..cb743233d 100644 --- a/src/cmds/changelogs.ts +++ b/src/cmds/changelogs.ts @@ -19,7 +19,6 @@ export default class ChangelogsCommand extends Command { this.description = 'Sync Markdown files to your ReadMe project as Changelog posts. Can either be a path to a directory or a single Markdown file.'; this.cmdCategory = CommandCategories.CHANGELOGS; - this.position = 1; this.hiddenArgs = ['filePath']; this.args = [ diff --git a/src/cmds/custompages.ts b/src/cmds/custompages.ts index f3859fabc..723f85f43 100644 --- a/src/cmds/custompages.ts +++ b/src/cmds/custompages.ts @@ -19,7 +19,6 @@ export default class CustomPagesCommand extends Command { this.description = 'Sync Markdown/HTML files to your ReadMe project as Custom Pages. Can either be a path to a directory or a single Markdown/HTML file.'; this.cmdCategory = CommandCategories.CUSTOM_PAGES; - this.position = 1; this.hiddenArgs = ['filePath']; this.args = [ diff --git a/src/cmds/docs/edit.ts b/src/cmds/docs/edit.ts index 4af25a2f6..783d69033 100644 --- a/src/cmds/docs/edit.ts +++ b/src/cmds/docs/edit.ts @@ -32,7 +32,6 @@ export default class DocsEditCommand extends Command { this.usage = 'docs:edit <slug> [options]'; this.description = 'Edit a single file from your ReadMe project without saving locally. [deprecated]'; this.cmdCategory = CommandCategories.DOCS; - this.position = 3; this.hiddenArgs = ['slug']; this.args = [ diff --git a/src/cmds/docs/index.ts b/src/cmds/docs/index.ts index 1d05c2a10..9aa682dbd 100644 --- a/src/cmds/docs/index.ts +++ b/src/cmds/docs/index.ts @@ -19,7 +19,6 @@ export default class DocsCommand extends Command { this.description = 'Sync Markdown files to your ReadMe project as Guides. Can either be a path to a directory or a single Markdown file.'; this.cmdCategory = CommandCategories.DOCS; - this.position = 1; this.hiddenArgs = ['filePath']; this.args = [ diff --git a/src/cmds/docs/prune.ts b/src/cmds/docs/prune.ts index 9ccd5171f..cb527ab2b 100644 --- a/src/cmds/docs/prune.ts +++ b/src/cmds/docs/prune.ts @@ -32,7 +32,6 @@ export default class DocsPruneCommand extends Command { this.usage = 'docs:prune <folder> [options]'; this.description = 'Delete any docs from ReadMe if their slugs are not found in the target folder.'; this.cmdCategory = CommandCategories.DOCS; - this.position = 2; this.hiddenArgs = ['folder']; this.args = [ diff --git a/src/cmds/guides/index.ts b/src/cmds/guides/index.ts index f07293d1e..43ad6679f 100644 --- a/src/cmds/guides/index.ts +++ b/src/cmds/guides/index.ts @@ -10,7 +10,6 @@ export default class GuidesCommand extends DocsCommand { this.command = 'guides'; this.usage = 'guides <path> [options]'; this.description = 'Alias for `rdme docs`.'; - this.position = 3; } async run(opts: CommandOptions<Options>) { diff --git a/src/cmds/guides/prune.ts b/src/cmds/guides/prune.ts index 8a867d93b..b38bfc1e2 100644 --- a/src/cmds/guides/prune.ts +++ b/src/cmds/guides/prune.ts @@ -10,7 +10,6 @@ export default class GuidesPruneCommand extends DocsPruneCommand { this.command = 'guides:prune'; this.usage = 'guides:prune <folder> [options]'; this.description = 'Alias for `rdme docs:prune`.'; - this.position = 4; } async run(opts: CommandOptions<Options>) { diff --git a/src/cmds/login.ts b/src/cmds/login.ts index be57e60f7..93c31f18e 100644 --- a/src/cmds/login.ts +++ b/src/cmds/login.ts @@ -17,7 +17,6 @@ export default class LoginCommand extends Command { this.usage = 'login [options]'; this.description = 'Login to a ReadMe project.'; this.cmdCategory = CommandCategories.ADMIN; - this.position = 1; this.args = [ { diff --git a/src/cmds/logout.ts b/src/cmds/logout.ts index 3ff0709e8..ee0c68fb6 100644 --- a/src/cmds/logout.ts +++ b/src/cmds/logout.ts @@ -13,7 +13,6 @@ export default class LogoutCommand extends Command { this.usage = 'logout'; this.description = 'Logs the currently authenticated user out of ReadMe.'; this.cmdCategory = CommandCategories.ADMIN; - this.position = 2; this.args = []; } diff --git a/src/cmds/oas.ts b/src/cmds/oas.ts index 4d676b649..26fd6e96d 100644 --- a/src/cmds/oas.ts +++ b/src/cmds/oas.ts @@ -12,7 +12,6 @@ export default class OASCommand extends Command { this.usage = 'oas'; this.description = 'Helpful OpenAPI generation tooling. [inactive]'; this.cmdCategory = CommandCategories.UTILITIES; - this.position = 2; this.args = []; } diff --git a/src/cmds/open.ts b/src/cmds/open.ts index c3ab56391..131f83c45 100644 --- a/src/cmds/open.ts +++ b/src/cmds/open.ts @@ -21,7 +21,6 @@ export default class OpenCommand extends Command { this.usage = 'open'; this.description = 'Open your current ReadMe project in the browser.'; this.cmdCategory = CommandCategories.UTILITIES; - this.position = 1; this.args = [ { diff --git a/src/cmds/openapi/index.ts b/src/cmds/openapi/index.ts index 9e82f82cb..bfb920174 100644 --- a/src/cmds/openapi/index.ts +++ b/src/cmds/openapi/index.ts @@ -37,7 +37,6 @@ export default class OpenAPICommand extends Command { this.usage = 'openapi [file|url] [options]'; this.description = 'Upload, or resync, your OpenAPI/Swagger definition to ReadMe.'; this.cmdCategory = CommandCategories.APIS; - this.position = 1; this.hiddenArgs = ['spec']; this.args = [ diff --git a/src/cmds/openapi/inspect.ts b/src/cmds/openapi/inspect.ts index 5954b4303..13557c581 100644 --- a/src/cmds/openapi/inspect.ts +++ b/src/cmds/openapi/inspect.ts @@ -31,7 +31,6 @@ export default class OpenAPIInspectCommand extends Command { this.usage = 'openapi:inspect [file|url] [options]'; this.description = 'Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage.'; this.cmdCategory = CommandCategories.APIS; - this.position = 4; this.hiddenArgs = ['spec']; this.args = [ diff --git a/src/cmds/openapi/reduce.ts b/src/cmds/openapi/reduce.ts index e4edbb52a..de213e972 100644 --- a/src/cmds/openapi/reduce.ts +++ b/src/cmds/openapi/reduce.ts @@ -32,7 +32,6 @@ export default class OpenAPIReduceCommand extends Command { this.usage = 'openapi:reduce [file|url] [options]'; this.description = 'Reduce an OpenAPI definition into a smaller subset.'; this.cmdCategory = CommandCategories.APIS; - this.position = 2; this.hiddenArgs = ['spec']; this.args = [ diff --git a/src/cmds/openapi/validate.ts b/src/cmds/openapi/validate.ts index a3b20f512..0f0b1fd92 100644 --- a/src/cmds/openapi/validate.ts +++ b/src/cmds/openapi/validate.ts @@ -19,7 +19,6 @@ export default class OpenAPIValidateCommand extends Command { this.usage = 'openapi:validate [file|url] [options]'; this.description = 'Validate your OpenAPI/Swagger definition.'; this.cmdCategory = CommandCategories.APIS; - this.position = 3; this.hiddenArgs = ['spec']; this.args = [ diff --git a/src/cmds/swagger.ts b/src/cmds/swagger.ts index b5345de25..d7fe40276 100644 --- a/src/cmds/swagger.ts +++ b/src/cmds/swagger.ts @@ -14,7 +14,6 @@ export default class SwaggerCommand extends OpenAPICommand { this.command = 'swagger'; this.usage = 'swagger [file] [options]'; this.description = 'Alias for `rdme openapi`. [deprecated]'; - this.position = 4; } async run(opts: CommandOptions<Options>) { diff --git a/src/cmds/validate.ts b/src/cmds/validate.ts index c68a72987..ec4aa9971 100644 --- a/src/cmds/validate.ts +++ b/src/cmds/validate.ts @@ -14,7 +14,6 @@ export default class ValidateAliasCommand extends OpenAPIValidateCommand { this.command = 'validate'; this.usage = 'validate [file] [options]'; this.description = 'Alias for `rdme openapi:validate` [deprecated].'; - this.position = 5; } async run(opts: CommandOptions<Options>) { diff --git a/src/cmds/versions/create.ts b/src/cmds/versions/create.ts index 730ead903..ca3f3eb91 100644 --- a/src/cmds/versions/create.ts +++ b/src/cmds/versions/create.ts @@ -29,7 +29,6 @@ export default class CreateVersionCommand extends Command { this.usage = 'versions:create <version> [options]'; this.description = 'Create a new version for your project.'; this.cmdCategory = CommandCategories.VERSIONS; - this.position = 2; this.hiddenArgs = ['version']; this.args = [ diff --git a/src/cmds/versions/delete.ts b/src/cmds/versions/delete.ts index cb97fecdc..72f5b075b 100644 --- a/src/cmds/versions/delete.ts +++ b/src/cmds/versions/delete.ts @@ -14,7 +14,6 @@ export default class DeleteVersionCommand extends Command { this.usage = 'versions:delete <version> [options]'; this.description = 'Delete a version associated with your ReadMe project.'; this.cmdCategory = CommandCategories.VERSIONS; - this.position = 4; this.hiddenArgs = ['version']; this.args = [ diff --git a/src/cmds/versions/index.ts b/src/cmds/versions/index.ts index cd22a51fd..76a27cee3 100644 --- a/src/cmds/versions/index.ts +++ b/src/cmds/versions/index.ts @@ -24,7 +24,6 @@ export default class VersionsCommand extends Command { this.usage = 'versions [options]'; this.description = 'List versions available in your project or get a version by SemVer (https://semver.org/).'; this.cmdCategory = CommandCategories.VERSIONS; - this.position = 1; this.args = [ this.getKeyArg(), diff --git a/src/cmds/versions/update.ts b/src/cmds/versions/update.ts index 4f1fdd09f..b574c17be 100644 --- a/src/cmds/versions/update.ts +++ b/src/cmds/versions/update.ts @@ -24,7 +24,6 @@ export default class UpdateVersionCommand extends Command { this.usage = 'versions:update <version> [options]'; this.description = 'Update an existing version for your project.'; this.cmdCategory = CommandCategories.VERSIONS; - this.position = 3; this.hiddenArgs = ['version']; this.args = [ diff --git a/src/cmds/whoami.ts b/src/cmds/whoami.ts index d1d075fbd..ebf2588fa 100644 --- a/src/cmds/whoami.ts +++ b/src/cmds/whoami.ts @@ -14,7 +14,6 @@ export default class WhoAmICommand extends Command { this.usage = 'whoami'; this.description = 'Displays the current user and project authenticated with ReadMe.'; this.cmdCategory = CommandCategories.ADMIN; - this.position = 3; this.args = []; } diff --git a/src/lib/baseCommand.ts b/src/lib/baseCommand.ts index 2b361ce71..b766c6e06 100644 --- a/src/lib/baseCommand.ts +++ b/src/lib/baseCommand.ts @@ -59,13 +59,6 @@ export default class Command { */ cmdCategory: CommandCategories; - /** - * The order in which to display the command within the `cmdCategory` - * - * @example 1 - */ - position: number; - /** * Should the command be hidden from our `--help` screens? */ diff --git a/src/lib/commands.ts b/src/lib/commands.ts index 370fc09b8..fab788937 100644 --- a/src/lib/commands.ts +++ b/src/lib/commands.ts @@ -9,7 +9,6 @@ export function getCategories(): Record< commands: { name: string; description: string; - position: number; hidden: boolean; }[]; } @@ -74,7 +73,6 @@ export function listByCategory() { categories[c.command.cmdCategory].commands.push({ name: c.command.command, description: c.command.description, - position: c.command.position, hidden: c.command.hidden, }); }); diff --git a/src/lib/help.ts b/src/lib/help.ts index 2dab5a286..a8a92542f 100644 --- a/src/lib/help.ts +++ b/src/lib/help.ts @@ -7,9 +7,9 @@ import config from 'config'; import * as commands from './commands'; -function formatCommands(cmds: { name: string; description: string; hidden: boolean; position: number }[]) { +function formatCommands(cmds: { name: string; description: string; hidden: boolean }[]) { return cmds - .sort((a, b) => (a.position > b.position ? 1 : -1)) + .sort((a, b) => (a.name > b.name ? 1 : -1)) .filter(command => !command.hidden) .map(command => { return {