fix(complete): resolve command aliases and make the parser optional

Completing after an alias returned only the global options, because
`@bomb.sh/tab` registers each command under `command.name()` and has no
alias concept: `webpack b <TAB>` offered 4 candidates where `webpack build
<TAB>` offers 21, and `webpack s <TAB>` 4 against `serve`'s 94. The alias
being completed is now registered against the command it stands for, so
every alias resolves. Only the requested one is registered, which keeps
`webpack <TAB>` listing the eight commands rather than all thirteen names.

`@bomb.sh/tab` also moves to an optional peer dependency, next to the other
packages the CLI loads on demand. It is imported only to serve a completion
request, so installing it is the user's choice: the shell runs
`complete -- <words>` on every keypress and now gets silence when the
package is absent, while `complete <shell>` says what to install.

Also updates the dev-server 6 help snapshots, which were added after this
work branched.

Author: alexander-akait

.changeset/tab-completions.md

@@ -0,0 +1,5 @@
+---
+"webpack-cli": minor
+---
+
+feat: add shell completions for zsh, bash, fish and powershell through the `complete` command

package-lock.json

@@ -48,6 +48,7 @@
     "prepare": "husky"
   },
   "devDependencies": {
+    "@bomb.sh/tab": "^0.0.22",
     "@babel/core": "^8.0.1",
     "@babel/preset-env": "^8.0.2",
     "@babel/register": "^8.0.1",

package.json

@@ -31,7 +31,6 @@
     "!**/*__tests__"
   ],
   "dependencies": {
-    "@bomb.sh/tab": "^0.0.22",
     "@discoveryjs/json-ext": "^1.1.0",
     "commander": "^14.0.3",
     "cross-spawn": "^7.0.6",
@@ -45,6 +44,7 @@
     "@types/envinfo": "^7.8.4"
   },
   "peerDependencies": {
+    "@bomb.sh/tab": "^0.0.22",
     "js-yaml": "^4.0.0 || ^5.0.0",
     "json5": "^2.2.3",
     "toml": "^3.0.0 || ^4.0.0 || ^5.0.0",
@@ -53,6 +53,9 @@
     "webpack-dev-server": "^5.0.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
+    "@bomb.sh/tab": {
+      "optional": true
+    },
     "js-yaml": {
       "optional": true
     },

packages/webpack-cli/package.json

@@ -41,6 +41,7 @@ const WEBPACK_DEV_SERVER_PACKAGE_IS_CUSTOM = Boolean(process.env.WEBPACK_DEV_SER
 const WEBPACK_DEV_SERVER_PACKAGE = WEBPACK_DEV_SERVER_PACKAGE_IS_CUSTOM
   ? (process.env.WEBPACK_DEV_SERVER_PACKAGE as string)
   : "webpack-dev-server";
+const COMPLETION_PACKAGE = "@bomb.sh/tab";
 
 // `webpack-dev-server` v6 is ESM and exposes the server as its `default` export,
 // while v5 exports it directly
@@ -2545,13 +2546,24 @@ class WebpackCLI {
     return externalCommand;
   }
 
-  #isCompletionRequest(args: readonly string[], parseOptions?: ParseOptions): boolean {
+  #completionRequest(
+    args: readonly string[],
+    parseOptions?: ParseOptions,
+  ): { words: string[] } | undefined {
     const userArgs = parseOptions?.from === "user" ? args : args.slice(2);
 
-    return userArgs.find((arg) => arg !== "--" && !arg.startsWith("-")) === "complete";
+    if (userArgs.find((arg) => arg !== "--" && !arg.startsWith("-")) !== "complete") {
+      return;
+    }
+
+    // `complete -- <words>` asks what to suggest for `<words>`; `complete <shell>`
+    // only prints a script and has no words to resolve.
+    const separator = userArgs.indexOf("--");
+
+    return { words: separator === -1 ? [] : userArgs.slice(separator + 1) };
   }
 
-  async #prepareCompletions(): Promise<void> {
+  async #prepareCompletions(words: string[]): Promise<void> {
     // Register every option (same as `--help`) so tab can inspect the full tree.
     this.program.forHelp = true;
 
@@ -2561,12 +2573,31 @@ class WebpackCLI {
         .map((command) => this.#loadCommandByName(command.rawName)),
     );
 
-    const { default: tab } = await import("@bomb.sh/tab/commander");
+    let tab: typeof import("@bomb.sh/tab/commander").default;
+
+    try {
+      ({ default: tab } = await import("@bomb.sh/tab/commander"));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ERR_MODULE_NOT_FOUND") {
+        throw error;
+      }
+
+      // The shell runs `complete -- <words>` on every keypress, so a missing
+      // optional package stays silent there and only reports when asked for a script.
+      if (words.length === 0) {
+        this.logger.error(
+          `For using '${this.colors.green("complete")}' command you need to install: '${this.colors.green(COMPLETION_PACKAGE)}' package.`,
+        );
+        process.exit(2);
+      }
+
+      process.exit(0);
+    }
 
-    this.#attachCompletionHandlers(tab(this.program));
+    this.#attachCompletionHandlers(tab(this.program), words);
   }
 
-  #attachCompletionHandlers(completion: RootCommand): void {
+  #attachCompletionHandlers(completion: RootCommand, words: string[]): void {
     const helpOption = completion.options.get("help");
 
     if (helpOption) {
@@ -2612,13 +2643,22 @@ class WebpackCLI {
       };
     }
 
+    // The command being completed, e.g. `b` in `complete -- b --mode=`.
+    const requested = words.find((word) => word !== "--" && !word.startsWith("-"));
+
     for (const command of this.program.commands) {
       const tabCommand = completion.commands.get(command.name());
 
       if (!tabCommand) {
         continue;
       }
 
+      // Commands are registered under their name, so an alias resolves to nothing.
+      // Only the requested one is registered, to keep aliases out of the suggestions.
+      if (requested && requested !== command.name() && command.aliases().includes(requested)) {
+        completion.commands.set(requested, tabCommand);
+      }
+
       for (const option of command.options) {
         const longName = option.long?.slice(2);
 
@@ -2871,8 +2911,10 @@ class WebpackCLI {
       await command.parseAsync([...commandOperands, ...unknown], { from: "user" });
     });
 
-    if (this.#isCompletionRequest(args, parseOptions)) {
-      await this.#prepareCompletions();
+    const completionRequest = this.#completionRequest(args, parseOptions);
+
+    if (completionRequest) {
+      await this.#prepareCompletions(completionRequest.words);
     }
 
     await this.program.parseAsync(args, parseOptions);

packages/webpack-cli/src/webpack-cli.ts

@@ -70,6 +70,43 @@ describe("complete", () => {
     expect(suggestions).toEqual(expect.arrayContaining(["json", "markdown"]));
   });
 
+  it("should suggest the same options for a command alias", async () => {
+    const { stdout: canonical } = await run(__dirname, ["complete", "--", "build", "--"]);
+
+    for (const alias of ["b", "bundle"]) {
+      const { exitCode, stderr, stdout } = await run(__dirname, ["complete", "--", alias, "--"]);
+
+      expect(exitCode).toBe(0);
+      expect(stderr).toBeFalsy();
+      expect(parseCompletions(stdout)).toEqual(parseCompletions(canonical));
+    }
+  });
+
+  it("should suggest option values for a command alias", async () => {
+    const { exitCode, stderr, stdout } = await run(__dirname, ["complete", "--", "b", "--mode="]);
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBeFalsy();
+    expect(parseCompletions(stdout)).toEqual(
+      expect.arrayContaining(["development", "production", "none"]),
+    );
+  });
+
+  it("should not suggest aliases as commands", async () => {
+    const { exitCode, stderr, stdout } = await run(__dirname, ["complete", "--", ""]);
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBeFalsy();
+
+    const suggestions = parseCompletions(stdout);
+
+    expect(suggestions).toEqual(expect.arrayContaining(["build", "watch", "serve"]));
+
+    for (const alias of ["b", "bundle", "w", "s", "server"]) {
+      expect(suggestions).not.toContain(alias);
+    }
+  });
+
   it("should suggest flags for the build command", async () => {
     const { exitCode, stderr, stdout } = await run(__dirname, ["complete", "--", "build", "--"]);
 

test/complete/complete.test.js

@@ -134,6 +134,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.
@@ -193,6 +194,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.
@@ -252,6 +254,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.
@@ -2643,6 +2646,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.
@@ -2732,6 +2736,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.
@@ -3089,6 +3094,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.
@@ -3146,6 +3152,7 @@ Global options
 Commands
 ────────────────────────────────────────────────────────────────────────
   build|bundle|b [entries...] [options]  Run webpack (default command, can be omitted).
+  complete [shell]                       Generate shell completion scripts.
   configtest|t [config-path]             Validate a webpack configuration.
   help|h [command] [option]              Display help for commands and options.
   info|i [options]                       Outputs information about your system.