feat: experiment with a decorator to hide commands from the help scre…

…en (#574) * feat: experiment with a decorator to hide commands from the help screen * fix: updating test snapshots * fix: how the isHidden decorator works so it actually works everywhere * feat: hiding the `oas` command from help screens * fix: silencing eslint
readmeio · Aug 20, 2022 · 486a8b0 · 486a8b0
1 parent 0b2750d
commit 486a8b0
Show file tree

Hide file tree

Showing 10 changed files with 51 additions and 5 deletions.
diff --git a/__tests__/__snapshots__/index.test.ts.snap b/__tests__/__snapshots__/index.test.ts.snap
@@ -24,7 +24,6 @@ Related commands
 
   $ rdme validate         Validate your OpenAPI/Swagger definition.           
   $ rdme openapi:reduce   Reduce an OpenAPI definition into a smaller subset. 
-  $ rdme swagger          Alias for \`rdme openapi\`. [deprecated]              
 "
 `;
 
@@ -52,7 +51,6 @@ Related commands
 
   $ rdme validate         Validate your OpenAPI/Swagger definition.           
   $ rdme openapi:reduce   Reduce an OpenAPI definition into a smaller subset. 
-  $ rdme swagger          Alias for \`rdme openapi\`. [deprecated]              
 "
 `;
 
@@ -80,7 +78,6 @@ Related commands
 
   $ rdme validate         Validate your OpenAPI/Swagger definition.           
   $ rdme openapi:reduce   Reduce an OpenAPI definition into a smaller subset. 
-  $ rdme swagger          Alias for \`rdme openapi\`. [deprecated]              
 "
 `;
 

diff --git a/__tests__/lib/__snapshots__/commands.test.ts.snap b/__tests__/lib/__snapshots__/commands.test.ts.snap
@@ -6,16 +6,19 @@ Object {
     "commands": Array [
       Object {
         "description": "Login to a ReadMe project.",
+        "hidden": false,
         "name": "login",
         "position": 1,
       },
       Object {
         "description": "Logs the currently authenticated user out of ReadMe.",
+        "hidden": false,
         "name": "logout",
         "position": 2,
       },
       Object {
         "description": "Displays the current user and project authenticated with ReadMe.",
+        "hidden": false,
         "name": "whoami",
         "position": 3,
       },
@@ -26,21 +29,25 @@ Object {
     "commands": Array [
       Object {
         "description": "Upload, or resync, your OpenAPI/Swagger definition to ReadMe.",
+        "hidden": false,
         "name": "openapi",
         "position": 1,
       },
       Object {
         "description": "Reduce an OpenAPI definition into a smaller subset.",
+        "hidden": false,
         "name": "openapi:reduce",
         "position": 3,
       },
       Object {
         "description": "Alias for \`rdme openapi\`. [deprecated]",
+        "hidden": true,
         "name": "swagger",
         "position": 4,
       },
       Object {
         "description": "Validate your OpenAPI/Swagger definition.",
+        "hidden": false,
         "name": "validate",
         "position": 2,
       },
@@ -51,11 +58,13 @@ Object {
     "commands": Array [
       Object {
         "description": "Get all categories in your ReadMe project.",
+        "hidden": false,
         "name": "categories",
         "position": 1,
       },
       Object {
         "description": "Create a category with the specified title and guide in your ReadMe project.",
+        "hidden": false,
         "name": "categories:create",
         "position": 2,
       },
@@ -66,11 +75,13 @@ Object {
     "commands": Array [
       Object {
         "description": "Sync a folder of Markdown files to your ReadMe project as Changelog posts.",
+        "hidden": false,
         "name": "changelogs",
         "position": 1,
       },
       Object {
         "description": "Sync a single Markdown file to your ReadMe project as a Changelog post.",
+        "hidden": false,
         "name": "changelogs:single",
         "position": 2,
       },
@@ -81,11 +92,13 @@ Object {
     "commands": Array [
       Object {
         "description": "Sync a folder of Markdown files to your ReadMe project as Custom Pages.",
+        "hidden": false,
         "name": "custompages",
         "position": 1,
       },
       Object {
         "description": "Sync a single Markdown file to your ReadMe project as a Custom Page.",
+        "hidden": false,
         "name": "custompages:single",
         "position": 2,
       },
@@ -96,16 +109,19 @@ Object {
     "commands": Array [
       Object {
         "description": "Sync a folder of Markdown files to your ReadMe project.",
+        "hidden": false,
         "name": "docs",
         "position": 1,
       },
       Object {
         "description": "Edit a single file from your ReadMe project without saving locally.",
+        "hidden": false,
         "name": "docs:edit",
         "position": 2,
       },
       Object {
         "description": "Sync a single Markdown file to your ReadMe project.",
+        "hidden": false,
         "name": "docs:single",
         "position": 3,
       },
@@ -116,11 +132,13 @@ Object {
     "commands": Array [
       Object {
         "description": "Helpful OpenAPI generation tooling. [inactive]",
+        "hidden": true,
         "name": "oas",
         "position": 2,
       },
       Object {
         "description": "Open your current ReadMe project in the browser.",
+        "hidden": false,
         "name": "open",
         "position": 1,
       },
@@ -131,21 +149,25 @@ Object {
     "commands": Array [
       Object {
         "description": "List versions available in your project or get a version by SemVer (https://semver.org/).",
+        "hidden": false,
         "name": "versions",
         "position": 1,
       },
       Object {
         "description": "Create a new version for your project.",
+        "hidden": false,
         "name": "versions:create",
         "position": 2,
       },
       Object {
         "description": "Delete a version associated with your ReadMe project.",
+        "hidden": false,
         "name": "versions:delete",
         "position": 4,
       },
       Object {
         "description": "Update an existing version for your project.",
+        "hidden": false,
         "name": "versions:update",
         "position": 3,
       },

diff --git a/__tests__/lib/commands.test.ts b/__tests__/lib/commands.test.ts
@@ -95,11 +95,13 @@ 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/oas.ts b/src/cmds/oas.ts
@@ -1,7 +1,9 @@
 import type { CommandOptions } from '../lib/baseCommand';
 
 import Command, { CommandCategories } from '../lib/baseCommand';
+import isHidden from '../lib/decorators/isHidden';
 
+@isHidden
 export default class OASCommand extends Command {
   constructor() {
     super();

diff --git a/src/cmds/swagger.ts b/src/cmds/swagger.ts
@@ -2,9 +2,11 @@ import type { CommandOptions } from '../lib/baseCommand';
 import type { Options } from './openapi';
 
 import Command from '../lib/baseCommand';
+import isHidden from '../lib/decorators/isHidden';
 
 import OpenAPICommand from './openapi';
 
+@isHidden
 export default class SwaggerCommand extends OpenAPICommand {
   constructor() {
     super();

diff --git a/src/lib/baseCommand.ts b/src/lib/baseCommand.ts
@@ -58,6 +58,11 @@ export default class Command {
    */
   position: number;
 
+  /**
+   * Should the command be hidden from our `--help` screens?
+   */
+  hidden = false;
+
   /**
    * Arguments to hide from the individual command help screen
    * (typically used for hiding default arguments)

diff --git a/src/lib/commands.ts b/src/lib/commands.ts
@@ -10,6 +10,7 @@ export function getCategories(): Record<
       name: string;
       description: string;
       position: number;
+      hidden: boolean;
     }[];
   }
 > {
@@ -74,6 +75,7 @@ export function listByCategory() {
       name: c.command.command,
       description: c.command.description,
       position: c.command.position,
+      hidden: c.command.hidden,
     });
   });
 
@@ -82,5 +84,5 @@ export function listByCategory() {
 
 export function getSimilar(cmdCategory: CommandCategories, excludeCommand: string) {
   const categories = listByCategory();
-  return categories[cmdCategory].commands.filter(cmd => cmd.name !== excludeCommand);
+  return categories[cmdCategory].commands.filter(cmd => cmd.name !== excludeCommand && !cmd.hidden);
 }
diff --git a/src/lib/decorators/isHidden.ts b/src/lib/decorators/isHidden.ts
@@ -0,0 +1,12 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * This TypeScript decorator will cause the decorated command to be hidden from all help and
+ * "Related commands" screens.
+ *
+ * @see {@link https://www.typescriptlang.org/docs/handbook/decorators.html#class-decorators}
+ */
+export default function isHidden<T extends { new (...args: any[]): {} }>(constructor: T) {
+  return class extends constructor {
+    hidden = true;
+  };
+}
diff --git a/src/lib/help.ts b/src/lib/help.ts
@@ -7,9 +7,10 @@ import config from 'config';
 
 import * as commands from './commands';
 
-function formatCommands(cmds: { name: string; description: string; position: number }[]) {
+function formatCommands(cmds: { name: string; description: string; hidden: boolean; position: number }[]) {
   return cmds
     .sort((a, b) => (a.position > b.position ? 1 : -1))
+    .filter(command => !command.hidden)
     .map(command => {
       return {
         name: `${chalk.grey('$')} ${config.get('cli')} ${command.name}`,

diff --git a/tsconfig.json b/tsconfig.json
@@ -4,6 +4,7 @@
     "baseUrl": "./src",
     "downlevelIteration": true,
     "esModuleInterop": true,
+    "experimentalDecorators": true,
     "lib": ["es2020"],
     "noImplicitAny": true,
     "outDir": "dist/",