fix(help): align option descriptions across varying flag widths

Calculate max flag width across all options before formatting,
ensuring descriptions start at the same column regardless of
individual flag lengths.

Author: boneskull

README.md

@@ -685,7 +685,7 @@ my-cli --completion-script fish > ~/.config/fish/completions/my-cli.fish
 
 ### What Gets Completed
 
-Once installed, pressing <kbd>Tab</kbd> will complete:
+Once installed, pressing `Tab` will complete:
 
 - **Commands and subcommands** (including nested commands and aliases)
 - **Options** (`--verbose`, `-v`, `--no-verbose` for booleans)

examples/completion.ts

@@ -107,7 +107,7 @@ const lintParser = opt.options({
 // CLI
 // ═══════════════════════════════════════════════════════════════════════════════
 
-await bargs('completion-demo', {
+await bargs('completion', {
   // Enable shell completion support!
   completion: true,
   description: 'Example CLI with shell completion support',

src/help.ts

@@ -186,25 +186,12 @@ const getTypeLabel = (def: OptionDef): string => {
 };
 
 /**
- * Format a single option for help output.
- *
- * For boolean options with `default: true`, shows `--no-<name>` instead of
- * `--<name>` since that's how users would turn it off.
- *
- * Displays aliases in order: short alias first (-v), then multi-char aliases
- * sorted by length (--verb), then the canonical name (--verbose).
+ * Get the flag text for an option (used for width calculation and display).
  *
  * @function
  */
-const formatOptionHelp = (
-  name: string,
-  def: OptionDef,
-  styler: Styler,
-): string => {
-  const parts: string[] = [];
-
+const getOptionFlagText = (name: string, def: OptionDef): string => {
   // For boolean options with default: true, show --no-<name>
-  // since that's how users would turn it off
   const displayName =
     def.type === 'boolean' && def.default === true ? `no-${name}` : name;
 
@@ -215,7 +202,6 @@ const formatOptionHelp = (
     .sort((a, b) => a.length - b.length);
 
   // Build flag string: -v, --verb, --verbose
-  // Don't show short alias for negated booleans
   const flagParts: string[] = [];
   if (shortAlias && displayName === name) {
     flagParts.push(`-${shortAlias}`);
@@ -226,14 +212,51 @@ const formatOptionHelp = (
   flagParts.push(`--${displayName}`);
 
   // If no short alias and no long aliases, add padding
-  const flagText =
-    flagParts.length === 1 && !shortAlias
-      ? `    ${flagParts[0]}`
-      : flagParts.join(', ');
+  return flagParts.length === 1 && !shortAlias
+    ? `    ${flagParts[0]}`
+    : flagParts.join(', ');
+};
+
+/**
+ * Calculate the max flag width for a set of options.
+ *
+ * @function
+ */
+const calculateMaxFlagWidth = (
+  options: Array<{ def: OptionDef; name: string }>,
+): number => {
+  let maxWidth = 0;
+  for (const { def, name } of options) {
+    const flagText = getOptionFlagText(name, def);
+    maxWidth = Math.max(maxWidth, flagText.length);
+  }
+  return maxWidth;
+};
+
+/**
+ * Format a single option for help output.
+ *
+ * For boolean options with `default: true`, shows `--no-<name>` instead of
+ * `--<name>` since that's how users would turn it off.
+ *
+ * Displays aliases in order: short alias first (-v), then multi-char aliases
+ * sorted by length (--verb), then the canonical name (--verbose).
+ *
+ * @function
+ */
+const formatOptionHelp = (
+  name: string,
+  def: OptionDef,
+  styler: Styler,
+  maxFlagWidth?: number,
+): string => {
+  const parts: string[] = [];
+
+  const flagText = getOptionFlagText(name, def);
   parts.push(`  ${styler.flag(flagText)}`);
 
-  // Pad to align descriptions (increase base padding for longer alias chains)
-  const basePadding = Math.max(24, flagText.length + 4);
+  // Pad to align descriptions using provided maxFlagWidth or calculate dynamically
+  const basePadding = Math.max(24, (maxFlagWidth ?? flagText.length) + 4);
   const padding = Math.max(0, basePadding - flagText.length - 2);
   parts.push(' '.repeat(padding));
 
@@ -354,11 +377,15 @@ export const generateHelp = (
       }
     }
 
+    // Calculate max flag width across all visible options for alignment
+    const allOptions = [...ungrouped, ...Array.from(groups.values()).flat()];
+    const maxFlagWidth = calculateMaxFlagWidth(allOptions);
+
     // Print grouped options
     for (const [groupName, options] of Array.from(groups.entries())) {
       lines.push(styler.sectionHeader(groupName.toUpperCase()));
       for (const opt of options) {
-        lines.push(formatOptionHelp(opt.name, opt.def, styler));
+        lines.push(formatOptionHelp(opt.name, opt.def, styler, maxFlagWidth));
       }
       lines.push('');
     }
@@ -368,7 +395,7 @@ export const generateHelp = (
       const label = hasCommands(config) ? 'GLOBAL OPTIONS' : 'OPTIONS';
       lines.push(styler.sectionHeader(label));
       for (const opt of ungrouped) {
-        lines.push(formatOptionHelp(opt.name, opt.def, styler));
+        lines.push(formatOptionHelp(opt.name, opt.def, styler, maxFlagWidth));
       }
       lines.push('');
     }
@@ -451,14 +478,32 @@ export const generateCommandHelp = (
   lines.push(styler.usage(`  ${usageParts}`));
   lines.push('');
 
+  // Collect all visible options for alignment calculation
+  const allOptions: Array<{ def: OptionDef; name: string }> = [];
+  if (command.options) {
+    for (const [name, def] of Object.entries(command.options)) {
+      if (!def.hidden) {
+        allOptions.push({ def, name });
+      }
+    }
+  }
+  if (config.options) {
+    for (const [name, def] of Object.entries(config.options)) {
+      if (!def.hidden) {
+        allOptions.push({ def, name });
+      }
+    }
+  }
+  const maxFlagWidth = calculateMaxFlagWidth(allOptions);
+
   // Command options
   if (command.options && Object.keys(command.options).length > 0) {
     lines.push(styler.sectionHeader('OPTIONS'));
     for (const [name, def] of Object.entries(command.options)) {
       if (def.hidden) {
         continue;
       }
-      lines.push(formatOptionHelp(name, def, styler));
+      lines.push(formatOptionHelp(name, def, styler, maxFlagWidth));
     }
     lines.push('');
   }
@@ -470,7 +515,7 @@ export const generateCommandHelp = (
       if (def.hidden) {
         continue;
       }
-      lines.push(formatOptionHelp(name, def, styler));
+      lines.push(formatOptionHelp(name, def, styler, maxFlagWidth));
     }
     lines.push('');
   }