[ts-command-line] Escape % characters in help text. (#5281)

* Add CLI help snapshot tests.

* Introduce a failing test with sprintf-style characters.

* Escape % characters.

Author: iclanton

common/changes/@microsoft/rush/ts-command-line-sprintf_2025-07-23-19-30.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/changes/@rushstack/ts-command-line/ts-command-line-sprintf_2025-07-23-19-06.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Escape `%` characters in help text to fix an issue where they were previously interpreted as sprintf-style tokens.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line"
+}

libraries/rush-lib/src/api/test/__snapshots__/RushCommandLine.test.ts.snap

@@ -1191,7 +1191,7 @@ Object {
       "actionName": "import-strings",
       "parameters": Array [
         Object {
-          "description": "Specifies the maximum number of concurrent processes to launch during a build. The COUNT should be a positive integer, a percentage value (eg. \\"50%%\\") or the word \\"max\\" to specify a count that is equal to the number of CPU cores. If this parameter is omitted, then the default value depends on the operating system and number of CPU cores.",
+          "description": "Specifies the maximum number of concurrent processes to launch during a build. The COUNT should be a positive integer, a percentage value (eg. \\"50%\\") or the word \\"max\\" to specify a count that is equal to the number of CPU cores. If this parameter is omitted, then the default value depends on the operating system and number of CPU cores.",
           "environmentVariable": "RUSH_PARALLELISM",
           "kind": "String",
           "longName": "--parallelism",
@@ -1345,7 +1345,7 @@ Object {
       "actionName": "build",
       "parameters": Array [
         Object {
-          "description": "Specifies the maximum number of concurrent processes to launch during a build. The COUNT should be a positive integer, a percentage value (eg. \\"50%%\\") or the word \\"max\\" to specify a count that is equal to the number of CPU cores. If this parameter is omitted, then the default value depends on the operating system and number of CPU cores.",
+          "description": "Specifies the maximum number of concurrent processes to launch during a build. The COUNT should be a positive integer, a percentage value (eg. \\"50%\\") or the word \\"max\\" to specify a count that is equal to the number of CPU cores. If this parameter is omitted, then the default value depends on the operating system and number of CPU cores.",
           "environmentVariable": "RUSH_PARALLELISM",
           "kind": "String",
           "longName": "--parallelism",
@@ -1502,7 +1502,7 @@ Object {
       "actionName": "rebuild",
       "parameters": Array [
         Object {
-          "description": "Specifies the maximum number of concurrent processes to launch during a build. The COUNT should be a positive integer, a percentage value (eg. \\"50%%\\") or the word \\"max\\" to specify a count that is equal to the number of CPU cores. If this parameter is omitted, then the default value depends on the operating system and number of CPU cores.",
+          "description": "Specifies the maximum number of concurrent processes to launch during a build. The COUNT should be a positive integer, a percentage value (eg. \\"50%\\") or the word \\"max\\" to specify a count that is equal to the number of CPU cores. If this parameter is omitted, then the default value depends on the operating system and number of CPU cores.",
           "environmentVariable": "RUSH_PARALLELISM",
           "kind": "String",
           "longName": "--parallelism",

libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts

@@ -193,7 +193,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> {
           environmentVariable: EnvironmentVariableNames.RUSH_PARALLELISM,
           description:
             'Specifies the maximum number of concurrent processes to launch during a build.' +
-            ' The COUNT should be a positive integer, a percentage value (eg. "50%%") or the word "max"' +
+            ' The COUNT should be a positive integer, a percentage value (eg. "50%") or the word "max"' +
             ' to specify a count that is equal to the number of CPU cores. If this parameter is omitted,' +
             ' then the default value depends on the operating system and number of CPU cores.'
         })

libraries/ts-command-line/src/escapeSprintf.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+export function escapeSprintf(input: string): string {
+  // Escape sprintf-style escape characters
+  // The primary special character in sprintf format strings is '%'
+  // which introduces format specifiers like %s, %d, %f, etc.
+  return input.replace(/%/g, '%%');
+}

libraries/ts-command-line/src/providers/CommandLineAction.ts

@@ -5,6 +5,7 @@ import type * as argparse from 'argparse';
 
 import { CommandLineParameterProvider } from './CommandLineParameterProvider';
 import { CommandLineParserExitError } from './CommandLineParserExitError';
+import { escapeSprintf } from '../escapeSprintf';
 
 /**
  * Options for the CommandLineAction constructor.
@@ -83,8 +84,8 @@ export abstract class CommandLineAction extends CommandLineParameterProvider {
    */
   public _buildParser(actionsSubParser: argparse.SubParser): void {
     this._argumentParser = actionsSubParser.addParser(this.actionName, {
-      help: this.summary,
-      description: this.documentation
+      help: escapeSprintf(this.summary),
+      description: escapeSprintf(this.documentation)
     });
 
     // Monkey-patch the error handling for the action parser

libraries/ts-command-line/src/providers/CommandLineParameterProvider.ts

@@ -39,6 +39,7 @@ import { CommandLineStringListParameter } from '../parameters/CommandLineStringL
 import { CommandLineRemainder } from '../parameters/CommandLineRemainder';
 import { SCOPING_PARAMETER_GROUP } from '../Constants';
 import { CommandLineParserExitError } from './CommandLineParserExitError';
+import { escapeSprintf } from '../escapeSprintf';
 
 /**
  * The result containing the parsed parameter long name and scope. Returned when calling
@@ -858,7 +859,7 @@ export abstract class CommandLineParameterProvider {
     // NOTE: Our "environmentVariable" feature takes precedence over argparse's "defaultValue",
     // so we have to reimplement that feature.
     const argparseOptions: argparse.ArgumentOptions = {
-      help: finalDescription,
+      help: escapeSprintf(finalDescription),
       dest: parserKey,
       metavar: (parameter as CommandLineParameterWithArgument).argumentName,
       required,

libraries/ts-command-line/src/providers/CommandLineParser.ts

@@ -14,6 +14,7 @@ import {
 import { CommandLineParserExitError, CustomArgumentParser } from './CommandLineParserExitError';
 import { TabCompleteAction } from './TabCompletionAction';
 import { TypeUuid, uuidAlreadyReportedError } from '../TypeUuidLite';
+import { escapeSprintf } from '../escapeSprintf';
 
 /**
  * Options for the {@link CommandLineParser} constructor.
@@ -75,13 +76,16 @@ export abstract class CommandLineParser extends CommandLineParameterProvider {
     this._actions = [];
     this._actionsByName = new Map<string, CommandLineAction>();
 
+    const { toolFilename, toolDescription, toolEpilog } = options;
+
     this._argumentParser = new CustomArgumentParser({
       addHelp: true,
-      prog: this._options.toolFilename,
-      description: this._options.toolDescription,
+      prog: toolFilename,
+      description: escapeSprintf(toolDescription),
       epilog: Colorize.bold(
-        this._options.toolEpilog ??
-          `For detailed help about a specific command, use: ${this._options.toolFilename} <command> -h`
+        escapeSprintf(
+          toolEpilog ?? `For detailed help about a specific command, use: ${toolFilename} <command> -h`
+        )
       )
     });
   }

libraries/ts-command-line/src/test/ActionlessParser.test.ts

@@ -3,6 +3,7 @@
 
 import { CommandLineParser } from '../providers/CommandLineParser';
 import type { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 class TestCommandLine extends CommandLineParser {
   public flag: CommandLineFlagParameter;
@@ -27,6 +28,11 @@ class TestCommandLine extends CommandLineParser {
 }
 
 describe(`Actionless ${CommandLineParser.name}`, () => {
+  it('renders help text', () => {
+    const commandLineParser: TestCommandLine = new TestCommandLine();
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+  });
+
   it('parses an empty arg list', async () => {
     const commandLineParser: TestCommandLine = new TestCommandLine();
 

libraries/ts-command-line/src/test/AliasedCommandLineAction.test.ts

@@ -8,6 +8,7 @@ import type { CommandLineParameterProvider } from '../providers/CommandLineParam
 import { AliasCommandLineAction } from '../providers/AliasCommandLineAction';
 import { CommandLineAction } from '../providers/CommandLineAction';
 import type { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 class TestAliasAction extends AliasCommandLineAction {
   public done: boolean = false;
@@ -104,6 +105,11 @@ class TestCommandLine extends CommandLineParser {
 }
 
 describe(AliasCommandLineAction.name, () => {
+  it('renders help text', () => {
+    const commandLineParser: TestCommandLine = new TestCommandLine();
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+  });
+
   it('executes the aliased action', async () => {
     const commandLineParser: TestCommandLine = new TestCommandLine();
     const targetAction: TestAction = commandLineParser.getAction('action') as TestAction;