[ts-command-line] Escape % characters in help text.

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;

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

@@ -9,6 +9,7 @@ import type { CommandLineStringParameter } from '../parameters/CommandLineString
 import type { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
 import type { CommandLineParameterProvider } from '../providers/CommandLineParameterProvider';
 import { SCOPING_PARAMETER_GROUP } from '../Constants';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 class GenericCommandLine extends CommandLineParser {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -250,6 +251,17 @@ class AbbreviationScopedAction extends ScopedCommandLineAction {
 }
 
 describe(`Ambiguous ${CommandLineParser.name}`, () => {
+  it('renders help text', () => {
+    const commandLineParser: GenericCommandLine = new GenericCommandLine(
+      AmbiguousAction,
+      AbbreviationAction,
+      AliasAction,
+      AmbiguousScopedAction,
+      AbbreviationScopedAction
+    );
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+  });
+
   it('fails to execute when an ambiguous short name is provided', async () => {
     const commandLineParser: GenericCommandLine = new GenericCommandLine(AmbiguousAction);
 

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

@@ -2,13 +2,13 @@
 // See LICENSE in the project root for license information.
 
 import * as argparse from 'argparse';
-import { AnsiEscape } from '@rushstack/terminal';
 
 import { DynamicCommandLineParser } from '../providers/DynamicCommandLineParser';
 import { DynamicCommandLineAction } from '../providers/DynamicCommandLineAction';
 import { CommandLineParameterBase } from '../parameters/BaseClasses';
 import type { CommandLineParser } from '../providers/CommandLineParser';
 import type { CommandLineAction } from '../providers/CommandLineAction';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 interface IExtendedArgumentParser extends argparse.ArgumentParser {
   _printMessage: (message: string) => void;
@@ -174,18 +174,9 @@ describe(CommandLineParameterBase.name, () => {
     process.env = existingEnv;
   });
 
-  it('prints the global help', () => {
+  it('renders help text', () => {
     const commandLineParser: CommandLineParser = createParser();
-    const helpText: string = AnsiEscape.removeCodes(commandLineParser.renderHelpText());
-    expect(helpText).toMatchSnapshot();
-  });
-
-  it('prints the action help', () => {
-    const commandLineParser: CommandLineParser = createParser();
-    const helpText: string = AnsiEscape.removeCodes(
-      commandLineParser.getAction('do:the-job').renderHelpText()
-    );
-    expect(helpText).toMatchSnapshot();
+    ensureHelpTextMatchesSnapshot(commandLineParser);
   });
 
   it('parses an input with ALL parameters', async () => {

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

@@ -4,6 +4,7 @@
 import { CommandLineAction } from '../providers/CommandLineAction';
 import type { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
 import { CommandLineParser } from '../providers/CommandLineParser';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 class TestAction extends CommandLineAction {
   public done: boolean = false;
@@ -12,8 +13,8 @@ class TestAction extends CommandLineAction {
   public constructor() {
     super({
       actionName: 'do:the-job',
-      summary: 'does the job',
-      documentation: 'a longer description'
+      summary: 'does the job with sprintf-style escape characters, 100%',
+      documentation: 'a longer description with sprintf-style escape characters, 100%'
     });
 
     this._flag = this.defineFlagParameter({
@@ -32,14 +33,19 @@ class TestCommandLine extends CommandLineParser {
   public constructor() {
     super({
       toolFilename: 'example',
-      toolDescription: 'An example project'
+      toolDescription: 'An example project with sprintf-style escape characters, 100%'
     });
 
     this.addAction(new TestAction());
   }
 }
 
 describe(CommandLineParser.name, () => {
+  it('renders help text', () => {
+    const commandLineParser: TestCommandLine = new TestCommandLine();
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+  });
+
   it('executes an action', async () => {
     const commandLineParser: TestCommandLine = new TestCommandLine();
     commandLineParser._registerDefinedParameters({ parentParameterNames: new Set() });

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

@@ -1,13 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { AnsiEscape } from '@rushstack/terminal';
-
 import type { CommandLineAction } from '../providers/CommandLineAction';
 import type { CommandLineParser } from '../providers/CommandLineParser';
 import { DynamicCommandLineParser } from '../providers/DynamicCommandLineParser';
 import { DynamicCommandLineAction } from '../providers/DynamicCommandLineAction';
 import { CommandLineRemainder } from '../parameters/CommandLineRemainder';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 function createParser(): DynamicCommandLineParser {
   const commandLineParser: DynamicCommandLineParser = new DynamicCommandLineParser({
@@ -43,16 +42,9 @@ function createParser(): DynamicCommandLineParser {
 }
 
 describe(CommandLineRemainder.name, () => {
-  it('prints the global help', () => {
-    const commandLineParser: CommandLineParser = createParser();
-    const helpText: string = AnsiEscape.removeCodes(commandLineParser.renderHelpText());
-    expect(helpText).toMatchSnapshot();
-  });
-
-  it('prints the action help', () => {
+  it('renders help text', () => {
     const commandLineParser: CommandLineParser = createParser();
-    const helpText: string = AnsiEscape.removeCodes(commandLineParser.getAction('run').renderHelpText());
-    expect(helpText).toMatchSnapshot();
+    ensureHelpTextMatchesSnapshot(commandLineParser);
   });
 
   it('parses an action input with remainder', async () => {

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

@@ -5,6 +5,7 @@ import { CommandLineAction } from '../providers/CommandLineAction';
 import type { CommandLineStringParameter } from '../parameters/CommandLineStringParameter';
 import { CommandLineParser } from '../providers/CommandLineParser';
 import type { IScopedLongNameParseResult } from '../providers/CommandLineParameterProvider';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 class GenericCommandLine extends CommandLineParser {
   public constructor(action: new () => CommandLineAction) {
@@ -124,6 +125,8 @@ describe(`Conflicting ${CommandLineParser.name}`, () => {
   it('executes an action', async () => {
     const commandLineParser: GenericCommandLine = new GenericCommandLine(TestAction);
 
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+
     await commandLineParser.executeAsync([
       'do:the-job',
       '--scope1:arg',
@@ -147,6 +150,8 @@ describe(`Conflicting ${CommandLineParser.name}`, () => {
   it('parses the scope out of a long name correctly', async () => {
     const commandLineParser: GenericCommandLine = new GenericCommandLine(TestAction);
 
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+
     let result: IScopedLongNameParseResult = commandLineParser.parseScopedLongName('--scope1:arg');
     expect(result.scope).toEqual('scope1');
     expect(result.longName).toEqual('--arg');

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

@@ -4,6 +4,7 @@
 import { DynamicCommandLineParser } from '../providers/DynamicCommandLineParser';
 import { DynamicCommandLineAction } from '../providers/DynamicCommandLineAction';
 import type { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 describe(DynamicCommandLineParser.name, () => {
   it('parses an action', async () => {
@@ -23,6 +24,8 @@ describe(DynamicCommandLineParser.name, () => {
       description: 'The flag'
     });
 
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+
     await commandLineParser.executeAsync(['do:the-job', '--flag']);
 
     expect(commandLineParser.selectedAction).toEqual(action);

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

@@ -2,8 +2,8 @@
 // See LICENSE in the project root for license information.
 
 import type { ChildProcess } from 'node:child_process';
-import { AnsiEscape } from '@rushstack/terminal';
 import { Executable } from '@rushstack/node-core-library';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 const TEST_CLI_PATH: string = `${__dirname}/test-cli/start`;
 
@@ -36,13 +36,7 @@ describe('end-to-end test', () => {
 
     const parser = new WidgetCommandLine();
 
-    const globalHelpText: string = AnsiEscape.formatForTests(parser.renderHelpText());
-    expect(globalHelpText).toMatchSnapshot('global help');
-
-    for (const action of parser.actions) {
-      const actionHelpText: string = AnsiEscape.formatForTests(action.renderHelpText());
-      expect(actionHelpText).toMatchSnapshot(action.actionName);
-    }
+    ensureHelpTextMatchesSnapshot(parser);
   });
 
   describe('execution tests', () => {

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

@@ -8,6 +8,7 @@ import type { CommandLineStringParameter } from '../parameters/CommandLineString
 import { CommandLineParser } from '../providers/CommandLineParser';
 import type { CommandLineParameterProvider } from '../providers/CommandLineParameterProvider';
 import type { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
+import { ensureHelpTextMatchesSnapshot } from './helpTestUtilities';
 
 class TestScopedAction extends ScopedCommandLineAction {
   public done: boolean = false;
@@ -67,6 +68,11 @@ class TestCommandLine extends CommandLineParser {
 }
 
 describe(CommandLineParser.name, () => {
+  it('renders help text', () => {
+    const commandLineParser: TestCommandLine = new TestCommandLine();
+    ensureHelpTextMatchesSnapshot(commandLineParser);
+  });
+
   it('throws on unknown scoped arg', async () => {
     const commandLineParser: TestCommandLine = new TestCommandLine();
     const args: string[] = ['scoped-action', '--scope', 'foo', '--', '--scoped-bar', 'baz'];