feat: display option aliases in help output and hide auto-generated ones

[AgentEnder]

Summary

This PR enhances the help output formatting to display user-defined option aliases alongside their primary names, while filtering out automatically generated aliases (from strip-dashed conversions and localization).

Key Changes

• Help formatting improvements: Modified format-help.ts to display option aliases in the format --option, -a, --alias in help text
• Auto-alias tracking: Added autoAliases field to InternalOptionConfig to distinguish between user-provided and automatically generated aliases
• Parser enhancements: Refactored alias generation logic in parser.ts to track which aliases were auto-generated via strip-dashed conversions or localization
• Help output filtering: Updated help display logic to exclude auto-generated aliases while showing user-defined ones
• Test coverage: Added comprehensive test cases for:
  • Displaying single and multiple user-defined aliases
  • Filtering out auto-generated aliases (e.g., camelCase/dashed conversions)
  • Proper alignment and formatting of flag columns with aliases

Implementation Details

• The buildFlagColumn() helper formats flag names with proper dash prefixes (- for single char, -- for multi-char)
• getDisplayAliases() filters aliases to exclude both the primary display key and any auto-generated aliases
• Help output column width calculation now accounts for the full flag column (including aliases) to maintain proper alignment
• Auto-aliases are only added to the config when strip-dashed or localization features are enabled

https://claude.ai/code/session_01Xn7GsCWNdxtR8wYYqE1Cdr

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 1b0a35b

Command	Status	Duration	Result
nx run-many -t build test e2e lint	✅ Succeeded	3m 50s	View ↗
nx build docs-site	✅ Succeeded	1m 14s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-04-17 19:08:53 UTC

[nx-cloud]

Nx Cloud is proposing a fix for your failed CI:

We fixed a TypeScript compilation failure caused by using Omit<UnknownOptionConfig, 'alias'> in the InternalOptionConfig definition, which silently dropped variant-specific fields like properties from the discriminated union. Restoring the intersection form (UnknownOptionConfig & { ... }) makes InternalOptionConfig a proper subtype of UnknownOptionConfig, and the alias field is normalized inline in parsers/object.ts to satisfy the narrowed string[] expectation.

Tip

✅ We verified this fix by re-running parser:extract-docs:api.

Suggested Fix changes

diff --git a/packages/parser/src/lib/option-types/index.ts b/packages/parser/src/lib/option-types/index.ts
index 2d2bd81..73ac4a3 100644
--- a/packages/parser/src/lib/option-types/index.ts
+++ b/packages/parser/src/lib/option-types/index.ts
@@ -14,7 +14,7 @@ export * from './string';
 export type { OptionConfig, UnknownOptionConfig };
 
 export type Internal<T extends UnknownOptionConfig> = T & InternalOptionConfig;
-export type InternalOptionConfig = Omit<UnknownOptionConfig, 'alias'> & {
+export type InternalOptionConfig = UnknownOptionConfig & {
   key: string;
   position?: number;
   /**
diff --git a/packages/parser/src/lib/parsers/object.ts b/packages/parser/src/lib/parsers/object.ts
index aac905e..005dfbb 100644
--- a/packages/parser/src/lib/parsers/object.ts
+++ b/packages/parser/src/lib/parsers/object.ts
@@ -7,8 +7,7 @@ import { tryParseValue } from '../parser';
 import { parserMap } from './parser-map';
 import { Parser } from './typings';
 
-export const objectParser: Parser<Internal<ObjectOptionConfig<any, any>>> =
-  ({
+export const objectParser: Parser<Internal<ObjectOptionConfig<any, any>>> = ({
   tokens,
   config,
   providedFlag,
@@ -58,6 +57,9 @@ export const objectParser: Parser<Internal<ObjectOptionConfig<any, any>>> =
     config: {
       ...propConfig,
       key: `${config.key}.${parts.join('.')}`,
+      alias: propConfig.alias?.flatMap((a) =>
+        typeof a === 'string' ? [a] : [a.name]
+      ),
     },
     tokens,
     current: currentValue,
@@ -78,7 +80,7 @@ export const objectParser: Parser<Internal<ObjectOptionConfig<any, any>>> =
     let currentValue: any;
     let currentConfig: UnknownOptionConfig = config;
     let last: string;
-     
+
     while (true) {
       if (!currentKey) {
         return {

  

Or Apply changes locally with:

npx nx-cloud apply-locally jIrC-Xdjy

Apply fix locally with your editor ↗   View interactive diff ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

[github-actions]

Docs Preview: https://craigory.dev/cli-forge/pr/90/

Deployed commit: 1b0a35b (1b0a35b)