feat(plugin-help): print available subcommands

Author: so1ve

packages/plugin-help/src/index.ts

@@ -142,6 +142,28 @@ export const helpPlugin = ({
 				console.log(s);
 			}
 
+			const renderer = new HelpRenderer(
+				mergedFormatters,
+				cli,
+				cli._globalFlags,
+				effectiveNotes,
+				effectiveExamples,
+				groups,
+			);
+
+			function tryPrintSubcommandsHelp(commandName: string) {
+				const subcommandsOutput =
+					renderer.renderAvailableSubcommands(commandName);
+
+				if (subcommandsOutput) {
+					printHelp(subcommandsOutput);
+
+					return true;
+				}
+
+				return false;
+			}
+
 			if (command) {
 				cli
 					.command("help", "Show help", {
@@ -158,19 +180,18 @@ export const helpPlugin = ({
 							[command] = resolveCommand(cli._commands, commandName);
 
 							if (!command) {
-								throw new NoSuchCommandError(commandName.join(" "));
+								const parentCommandName = commandName.join(" ");
+
+								if (tryPrintSubcommandsHelp(parentCommandName)) {
+									return;
+								}
+
+								// No subcommands, throw error
+								throw new NoSuchCommandError(parentCommandName);
 							}
 						}
 
-						const renderer = new HelpRenderer(
-							mergedFormatters,
-							cli,
-							cli._globalFlags,
-							command,
-							command ? command.help?.notes : effectiveNotes,
-							command ? command.help?.examples : effectiveExamples,
-							groups,
-						);
+						renderer.setCommand(command);
 						printHelp(renderer.render());
 					});
 			}
@@ -190,18 +211,16 @@ export const helpPlugin = ({
 						const command = ctx.command;
 						// If no command resolved, but parameters are present, just let the next interceptor handle it
 						if (!command && ctx.rawParsed.parameters.length > 0) {
+							const parentCommandName = ctx.rawParsed.parameters.join(" ");
+
+							if (tryPrintSubcommandsHelp(parentCommandName)) {
+								return;
+							}
+
 							await next();
 						}
 
-						const renderer = new HelpRenderer(
-							mergedFormatters,
-							cli,
-							cli._globalFlags,
-							command,
-							command ? command.help?.notes : effectiveNotes,
-							command ? command.help?.examples : effectiveExamples,
-							groups,
-						);
+						renderer.setCommand(command);
 						printHelp(renderer.render());
 					} else {
 						const shouldShowHelp =
@@ -210,15 +229,6 @@ export const helpPlugin = ({
 							ctx.rawParsed.parameters.length === 0; // and no command supplied, means no root command defined
 
 						if (shouldShowHelp) {
-							const renderer = new HelpRenderer(
-								mergedFormatters,
-								cli,
-								cli._globalFlags,
-								undefined,
-								effectiveNotes,
-								effectiveExamples,
-								groups,
-							);
 							printHelp(renderer.render());
 						} else {
 							await next();

packages/plugin-help/src/renderer.ts

@@ -70,12 +70,12 @@ export class HelpRenderer {
 	private _commandGroups: Map<string, string>;
 	private _flagGroups: Map<string, string>;
 	private _globalFlagGroups: Map<string, string>;
+	private _command: Command | undefined;
 
 	constructor(
 		private _formatters: Formatters,
 		private _cli: Clerc,
 		private _globalFlags: ClercFlagsDefinition,
-		private _command: Command | undefined,
 		private _notes?: string[],
 		private _examples?: [string, string][],
 		groups?: GroupsOptions,
@@ -85,21 +85,17 @@ export class HelpRenderer {
 		this._globalFlagGroups = groupDefinitionsToMap(groups?.globalFlags);
 	}
 
-	public render(): string {
-		const sections: Section[] = [
-			this.renderHeader(),
-			this.renderUsage(),
-			this.renderParameters(),
-			this.renderCommandFlags(),
-			this.renderGlobalFlags(),
-			this.renderCommands(),
-			this.renderExamples(),
-			this.renderNotes(),
-		];
+	public setCommand(command: Command | undefined): void {
+		if (command) {
+			this._command = command;
+			this._notes = command?.help?.notes;
+			this._examples = command?.help?.examples;
+		}
+	}
 
+	private renderSections(sections: Section[]): string {
 		return sections
 			.filter(isTruthy)
-			.filter((section) => section.body.length > 0)
 			.map((section) => {
 				const body = Array.isArray(section.body)
 					? section.body.filter((s) => s !== undefined).join("\n")
@@ -117,6 +113,21 @@ export class HelpRenderer {
 			.join("\n\n");
 	}
 
+	public render(): string {
+		const sections: Section[] = [
+			this.renderHeader(),
+			this.renderUsage(),
+			this.renderParameters(),
+			this.renderCommandFlags(),
+			this.renderGlobalFlags(),
+			this.renderCommands(),
+			this.renderExamples(),
+			this.renderNotes(),
+		];
+
+		return this.renderSections(sections);
+	}
+
 	private renderHeader() {
 		const { _name, _version, _description } = this._cli;
 		const command = this._command;
@@ -201,14 +212,14 @@ export class HelpRenderer {
 	private getSubcommands(parentCommandName: string): CommandsMap {
 		const subcommands = new Map<string, Command>();
 
-		if (!parentCommandName) {
+		if (parentCommandName === "") {
 			return subcommands;
 		}
 
 		const prefix = `${parentCommandName} `;
 
 		for (const [name, command] of this._cli._commands) {
-			if (name.startsWith(prefix) && name !== parentCommandName) {
+			if (name.startsWith(prefix)) {
 				const subcommandName = name.slice(prefix.length);
 				subcommands.set(subcommandName, command);
 			}
@@ -217,31 +228,10 @@ export class HelpRenderer {
 		return subcommands;
 	}
 
-	private renderCommands() {
-		const commands = this._cli._commands;
-
-		// If a command is selected, show its subcommands
-		let commandsToShow: CommandsMap;
-		let title = "Commands";
-		let prefix = "";
-
-		if (this._command) {
-			prefix = this._command.name ? `${this._command.name} ` : "";
-			title = "Subcommands";
-			commandsToShow = this.getSubcommands(this._command.name);
-
-			if (commandsToShow.size === 0) {
-				return;
-			}
-		} else {
-			commandsToShow = commands;
-		}
-
-		if (commandsToShow.size === 0) {
-			return;
-		}
-
-		// Group commands
+	private buildGroupedCommandsBody(
+		commandsToShow: CommandsMap,
+		prefix: string,
+	): string[] {
 		const groupedCommands = new Map<string, string[][]>();
 		const defaultCommands: string[][] = [];
 		let rootCommand: string[] = [];
@@ -265,7 +255,6 @@ export class HelpRenderer {
 			);
 
 			if (command.name === "") {
-				// Root command
 				rootCommand = item;
 			} else if (group && group !== DEFAULT_GROUP_KEY) {
 				const groupItems = groupedCommands.get(group) ?? [];
@@ -276,7 +265,6 @@ export class HelpRenderer {
 			}
 		}
 
-		// Build body with groups
 		const body: string[] = [];
 
 		const defaultGroup: string[][] = [];
@@ -306,6 +294,62 @@ export class HelpRenderer {
 			}
 		}
 
+		return body;
+	}
+
+	public renderAvailableSubcommands(parentCommandName: string): string {
+		const subcommands = this.getSubcommands(parentCommandName);
+
+		if (subcommands.size === 0) {
+			return "";
+		}
+
+		const prefix = `${parentCommandName} `;
+		const body = this.buildGroupedCommandsBody(subcommands, prefix);
+
+		if (body.length === 0) {
+			return "";
+		}
+
+		const sections: Section[] = [
+			{
+				body: `${yc.green(this._cli._name)} ${yc.cyan(parentCommandName)} not found`,
+			},
+			{
+				title: "Available Subcommands",
+				body,
+			},
+		];
+
+		return this.renderSections(sections);
+	}
+
+	private renderCommands() {
+		const commands = this._cli._commands;
+
+		// If a command is selected, show its subcommands
+		let commandsToShow: CommandsMap;
+		let title = "Commands";
+		let prefix = "";
+
+		if (this._command) {
+			prefix = this._command.name ? `${this._command.name} ` : "";
+			title = "Subcommands";
+			commandsToShow = this.getSubcommands(this._command.name);
+
+			if (commandsToShow.size === 0) {
+				return;
+			}
+		} else {
+			commandsToShow = commands;
+		}
+
+		if (commandsToShow.size === 0) {
+			return;
+		}
+
+		const body = this.buildGroupedCommandsBody(commandsToShow, prefix);
+
 		return {
 			title,
 			body,

packages/plugin-help/test/__snapshots__/plugin-help.test.ts.snap

@@ -254,6 +254,30 @@ exports[`plugin-help > should show --help 1`] = `
 ]
 `;
 
+exports[`plugin-help > should show available subcommands when parent command does not exist (using --help) 1`] = `
+[
+  [
+    "test completions not found
+
+Available Subcommands
+  install    Install shell completions
+  uninstall  Uninstall shell completions",
+  ],
+]
+`;
+
+exports[`plugin-help > should show available subcommands when parent command does not exist 1`] = `
+[
+  [
+    "test completions not found
+
+Available Subcommands
+  install    Install shell completions
+  uninstall  Uninstall shell completions",
+  ],
+]
+`;
+
 exports[`plugin-help > should show help 1`] = `
 [
   [

packages/plugin-help/test/plugin-help.test.ts

@@ -300,6 +300,35 @@ describe("plugin-help", () => {
 		}).rejects.toThrow(NoSuchCommandError);
 	});
 
+	it("should show available subcommands when parent command does not exist", () => {
+		TestBaseCli()
+			.use(helpPlugin())
+			.command("completions install", "Install shell completions")
+			.command("completions uninstall", "Uninstall shell completions")
+			.parse(["help", "completions"]);
+
+		expect(getConsoleMock("log").mock.calls).toMatchSnapshot();
+	});
+
+	it("should show available subcommands when parent command does not exist (using --help)", () => {
+		TestBaseCli()
+			.use(helpPlugin())
+			.command("completions install", "Install shell completions")
+			.command("completions uninstall", "Uninstall shell completions")
+			.parse(["completions", "--help"]);
+
+		expect(getConsoleMock("log").mock.calls).toMatchSnapshot();
+	});
+
+	it("should still throw error when no subcommands exist for non-existent command", async () => {
+		await expect(async () => {
+			await TestBaseCli()
+				.use(helpPlugin())
+				.command("other", "Other command")
+				.parse(["help", "not-exist"]);
+		}).rejects.toThrow(NoSuchCommandError);
+	});
+
 	it("should work with friendly-error", async () => {
 		expect(async () => {
 			await TestBaseCli()