@rushstack/ts-command-line 5.2.0 → 5.3.0

package/CHANGELOG.json

@@ -1,6 +1,26 @@
 {
   "name": "@rushstack/ts-command-line",
   "entries": [
+    {
+      "version": "5.3.0",
+      "tag": "@rushstack/ts-command-line_v5.3.0",
+      "date": "Thu, 19 Feb 2026 00:04:53 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Normalize package layout. CommonJS is now under `lib-commonjs`, DTS is now under `lib-dts`, and ESM is now under `lib-esm`. Imports to `lib` still work as before, handled by the `\"exports\"` field in `package.json`."
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.22.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.20.0`"
+          }
+        ]
+      }
+    },
     {
       "version": "5.2.0",
       "tag": "@rushstack/ts-command-line_v5.2.0",

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log - @rushstack/ts-command-line
 
-This log was last generated on Wed, 04 Feb 2026 16:13:27 GMT and should not be manually modified.
+This log was last generated on Thu, 19 Feb 2026 00:04:53 GMT and should not be manually modified.
+
+## 5.3.0
+Thu, 19 Feb 2026 00:04:53 GMT
+
+### Minor changes
+
+- Normalize package layout. CommonJS is now under `lib-commonjs`, DTS is now under `lib-dts`, and ESM is now under `lib-esm`. Imports to `lib` still work as before, handled by the `"exports"` field in `package.json`.
 
 ## 5.2.0
 Wed, 04 Feb 2026 16:13:27 GMT

package/lib-esm/CommandLineHelper.js

@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineConstants } from './Constants';
+/**
+ * Helpers for working with the ts-command-line API.
+ *
+ * @public
+ */
+export class CommandLineHelper {
+    /**
+     * Returns true if the current command line action is tab-complete.
+     *
+     * @public
+     */
+    static isTabCompletionActionRequest(argv) {
+        return argv && argv.length > 2 && argv[2] === CommandLineConstants.TabCompletionActionName;
+    }
+}
+//# sourceMappingURL=CommandLineHelper.js.map

package/lib-esm/CommandLineHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineHelper.js","sourceRoot":"","sources":["../src/CommandLineHelper.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAC5B;;;;OAIG;IACI,MAAM,CAAC,4BAA4B,CAAC,IAAc;QACvD,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,oBAAoB,CAAC,uBAAuB,CAAC;IAC7F,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { CommandLineConstants } from './Constants';\n\n/**\n * Helpers for working with the ts-command-line API.\n *\n * @public\n */\nexport class CommandLineHelper {\n  /**\n   * Returns true if the current command line action is tab-complete.\n   *\n   * @public\n   */\n  public static isTabCompletionActionRequest(argv: string[]): boolean {\n    return argv && argv.length > 2 && argv[2] === CommandLineConstants.TabCompletionActionName;\n  }\n}\n"]}

package/lib-esm/Constants.js

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * String constants for command line processing.
+ *
+ * @public
+ */
+export var CommandLineConstants;
+(function (CommandLineConstants) {
+    /**
+     * The name of the built-in action that serves suggestions for tab-completion
+     */
+    CommandLineConstants["TabCompletionActionName"] = "tab-complete";
+})(CommandLineConstants || (CommandLineConstants = {}));
+export const SCOPING_PARAMETER_GROUP = Symbol('scoping');
+//# sourceMappingURL=Constants.js.map

package/lib-esm/Constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Constants.js","sourceRoot":"","sources":["../src/Constants.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;;GAIG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,gEAAwC,CAAA;AAC1C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAkB,MAAM,CAAC,SAAS,CAAC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * String constants for command line processing.\n *\n * @public\n */\nexport enum CommandLineConstants {\n  /**\n   * The name of the built-in action that serves suggestions for tab-completion\n   */\n  TabCompletionActionName = 'tab-complete'\n}\n\nexport const SCOPING_PARAMETER_GROUP: unique symbol = Symbol('scoping');\n"]}

package/lib-esm/TypeUuidLite.js

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+const classPrototypeUuidSymbol = Symbol.for('TypeUuid.classPrototypeUuid');
+export const uuidAlreadyReportedError = 'f26b0640-a49b-49d1-9ead-1a516d5920c7';
+// Avoid a dependency on node-core-library to access just this one API:
+export class TypeUuid {
+    /**
+     * Returns true if the `targetObject` is an instance of a JavaScript class that was previously
+     * registered using the specified `typeUuid`.  Base classes are also considered.
+     */
+    static isInstanceOf(targetObject, typeUuid) {
+        if (targetObject === undefined || targetObject === null) {
+            return false;
+        }
+        let objectPrototype = Object.getPrototypeOf(targetObject);
+        while (objectPrototype !== undefined && objectPrototype !== null) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const registeredUuid = objectPrototype[classPrototypeUuidSymbol];
+            if (registeredUuid === typeUuid) {
+                return true;
+            }
+            // Walk upwards an examine base class prototypes
+            objectPrototype = Object.getPrototypeOf(objectPrototype);
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=TypeUuidLite.js.map

package/lib-esm/TypeUuidLite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeUuidLite.js","sourceRoot":"","sources":["../src/TypeUuidLite.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,MAAM,wBAAwB,GAAW,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AAEnF,MAAM,CAAC,MAAM,wBAAwB,GAAW,sCAAsC,CAAC;AAEvF,uEAAuE;AACvE,MAAM,OAAO,QAAQ;IACnB;;;OAGG;IACI,MAAM,CAAC,YAAY,CAAC,YAAqB,EAAE,QAAgB;QAChE,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YACxD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,eAAe,GAAO,MAAM,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QAC9D,OAAO,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;YACjE,8DAA8D;YAC9D,MAAM,cAAc,GAAY,eAAuB,CAAC,wBAAwB,CAAC,CAAC;YAClF,IAAI,cAAc,KAAK,QAAQ,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,gDAAgD;YAChD,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nconst classPrototypeUuidSymbol: symbol = Symbol.for('TypeUuid.classPrototypeUuid');\n\nexport const uuidAlreadyReportedError: string = 'f26b0640-a49b-49d1-9ead-1a516d5920c7';\n\n// Avoid a dependency on node-core-library to access just this one API:\nexport class TypeUuid {\n  /**\n   * Returns true if the `targetObject` is an instance of a JavaScript class that was previously\n   * registered using the specified `typeUuid`.  Base classes are also considered.\n   */\n  public static isInstanceOf(targetObject: unknown, typeUuid: string): boolean {\n    if (targetObject === undefined || targetObject === null) {\n      return false;\n    }\n\n    let objectPrototype: {} = Object.getPrototypeOf(targetObject);\n    while (objectPrototype !== undefined && objectPrototype !== null) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const registeredUuid: string = (objectPrototype as any)[classPrototypeUuidSymbol];\n      if (registeredUuid === typeUuid) {\n        return true;\n      }\n      // Walk upwards an examine base class prototypes\n      objectPrototype = Object.getPrototypeOf(objectPrototype);\n    }\n\n    return false;\n  }\n}\n"]}

package/lib-esm/escapeSprintf.js

@@ -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) {
+    // 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, '%%');
+}
+//# sourceMappingURL=escapeSprintf.js.map

package/lib-esm/escapeSprintf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeSprintf.js","sourceRoot":"","sources":["../src/escapeSprintf.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,yCAAyC;IACzC,iEAAiE;IACjE,2DAA2D;IAC3D,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nexport function escapeSprintf(input: string): string {\n  // Escape sprintf-style escape characters\n  // The primary special character in sprintf format strings is '%'\n  // which introduces format specifiers like %s, %d, %f, etc.\n  return input.replace(/%/g, '%%');\n}\n"]}

package/lib-esm/index.js

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * An object-oriented command-line parser for TypeScript projects.
+ *
+ * @packageDocumentation
+ */
+export { CommandLineAction } from './providers/CommandLineAction';
+export { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';
+export { ScopedCommandLineAction } from './providers/ScopedCommandLineAction';
+export { AliasCommandLineAction } from './providers/AliasCommandLineAction';
+export { CommandLineParameterKind, CommandLineParameterBase, CommandLineParameterWithArgument } from './parameters/BaseClasses';
+export { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';
+export { CommandLineStringParameter } from './parameters/CommandLineStringParameter';
+export { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';
+export { CommandLineIntegerParameter } from './parameters/CommandLineIntegerParameter';
+export { CommandLineIntegerListParameter } from './parameters/CommandLineIntegerListParameter';
+export { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';
+export { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';
+export { CommandLineRemainder } from './parameters/CommandLineRemainder';
+export { CommandLineParameterProvider } from './providers/CommandLineParameterProvider';
+export { CommandLineParser } from './providers/CommandLineParser';
+export { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';
+export { CommandLineConstants } from './Constants';
+export { CommandLineHelper } from './CommandLineHelper';
+//# sourceMappingURL=index.js.map

package/lib-esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAkC,MAAM,+BAA+B,CAAC;AAClG,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,EACL,sBAAsB,EAEvB,MAAM,oCAAoC,CAAC;AAe5C,OAAO,EAEL,wBAAwB,EACxB,wBAAwB,EACxB,gCAAgC,EACjC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,0BAA0B,EAE3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,8BAA8B,EAAE,MAAM,6CAA6C,CAAC;AAC7F,OAAO,EACL,2BAA2B,EAE5B,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,+BAA+B,EAAE,MAAM,8CAA8C,CAAC;AAC/F,OAAO,EACL,0BAA0B,EAE3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,8BAA8B,EAAE,MAAM,6CAA6C,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EACL,4BAA4B,EAI7B,MAAM,0CAA0C,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAkC,MAAM,+BAA+B,CAAC;AAClG,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * An object-oriented command-line parser for TypeScript projects.\n *\n * @packageDocumentation\n */\n\nexport { CommandLineAction, type ICommandLineActionOptions } from './providers/CommandLineAction';\nexport { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';\nexport { ScopedCommandLineAction } from './providers/ScopedCommandLineAction';\nexport {\n  AliasCommandLineAction,\n  type IAliasCommandLineActionOptions\n} from './providers/AliasCommandLineAction';\n\nexport type {\n  IBaseCommandLineDefinition,\n  IBaseCommandLineDefinitionWithArgument,\n  ICommandLineFlagDefinition,\n  ICommandLineStringDefinition,\n  ICommandLineStringListDefinition,\n  ICommandLineIntegerDefinition,\n  ICommandLineIntegerListDefinition,\n  ICommandLineChoiceDefinition,\n  ICommandLineChoiceListDefinition,\n  ICommandLineRemainderDefinition\n} from './parameters/CommandLineDefinition';\n\nexport {\n  type CommandLineParameter,\n  CommandLineParameterKind,\n  CommandLineParameterBase,\n  CommandLineParameterWithArgument\n} from './parameters/BaseClasses';\n\nexport { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';\nexport {\n  CommandLineStringParameter,\n  type IRequiredCommandLineStringParameter\n} from './parameters/CommandLineStringParameter';\nexport { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';\nexport {\n  CommandLineIntegerParameter,\n  type IRequiredCommandLineIntegerParameter\n} from './parameters/CommandLineIntegerParameter';\nexport { CommandLineIntegerListParameter } from './parameters/CommandLineIntegerListParameter';\nexport {\n  CommandLineChoiceParameter,\n  type IRequiredCommandLineChoiceParameter\n} from './parameters/CommandLineChoiceParameter';\nexport { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';\nexport { CommandLineRemainder } from './parameters/CommandLineRemainder';\n\nexport {\n  CommandLineParameterProvider,\n  type IScopedLongNameParseResult,\n  type ICommandLineParserData as _ICommandLineParserData,\n  type IRegisterDefinedParametersState as _IRegisterDefinedParametersState\n} from './providers/CommandLineParameterProvider';\n\nexport { CommandLineParser, type ICommandLineParserOptions } from './providers/CommandLineParser';\nexport { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';\n\nexport { CommandLineConstants } from './Constants';\n\nexport { CommandLineHelper } from './CommandLineHelper';\n"]}

package/lib-esm/parameters/BaseClasses.js

@@ -0,0 +1,163 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Identifies the kind of a CommandLineParameter.
+ * @public
+ */
+export var CommandLineParameterKind;
+(function (CommandLineParameterKind) {
+    /** Indicates a CommandLineChoiceParameter */
+    CommandLineParameterKind[CommandLineParameterKind["Choice"] = 0] = "Choice";
+    /** Indicates a CommandLineFlagParameter */
+    CommandLineParameterKind[CommandLineParameterKind["Flag"] = 1] = "Flag";
+    /** Indicates a CommandLineIntegerParameter */
+    CommandLineParameterKind[CommandLineParameterKind["Integer"] = 2] = "Integer";
+    /** Indicates a CommandLineStringParameter */
+    CommandLineParameterKind[CommandLineParameterKind["String"] = 3] = "String";
+    /** Indicates a CommandLineStringListParameter */
+    CommandLineParameterKind[CommandLineParameterKind["StringList"] = 4] = "StringList";
+    /** Indicates a CommandLineChoiceListParameter */
+    CommandLineParameterKind[CommandLineParameterKind["ChoiceList"] = 5] = "ChoiceList";
+    /** Indicates a CommandLineIntegerListParameter */
+    CommandLineParameterKind[CommandLineParameterKind["IntegerList"] = 6] = "IntegerList";
+})(CommandLineParameterKind || (CommandLineParameterKind = {}));
+/**
+ * Matches kebab-case formatted strings prefixed with double dashes.
+ * Example: "--do-something"
+ */
+const LONG_NAME_REGEXP = /^-(-[a-z0-9]+)+$/;
+/**
+ * Matches a single upper-case or lower-case letter prefixed with a dash.
+ * Example: "-d"
+ */
+const SHORT_NAME_REGEXP = /^-[a-zA-Z]$/;
+/**
+ * Matches kebab-case formatted strings
+ * Example: "my-scope"
+ */
+const SCOPE_REGEXP = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * "Environment variable names used by the utilities in the Shell and Utilities volume of
+ * IEEE Std 1003.1-2001 consist solely of uppercase letters, digits, and the '_' (underscore)
+ * from the characters defined in Portable Character Set and do not begin with a digit."
+ * Example: "THE_SETTING"
+ */
+const ENVIRONMENT_VARIABLE_NAME_REGEXP = /^[A-Z_][A-Z0-9_]*$/;
+/**
+ * The base class for the various command-line parameter types.
+ * @public
+ */
+export class CommandLineParameterBase {
+    /** @internal */
+    constructor(definition) {
+        this.longName = definition.parameterLongName;
+        this._shortNameValue = definition.parameterShortName;
+        this.parameterGroup = definition.parameterGroup;
+        this.parameterScope = definition.parameterScope;
+        this.description = definition.description;
+        this.required = !!definition.required;
+        this.environmentVariable = definition.environmentVariable;
+        this.undocumentedSynonyms = definition.undocumentedSynonyms;
+        this.allowNonStandardEnvironmentVariableNames = definition.allowNonStandardEnvironmentVariableNames;
+        if (!LONG_NAME_REGEXP.test(this.longName)) {
+            throw new Error(`Invalid name: "${this.longName}". The parameter long name must be` +
+                ` lower-case and use dash delimiters (e.g. "--do-a-thing")`);
+        }
+        if (this.shortName) {
+            if (!SHORT_NAME_REGEXP.test(this.shortName)) {
+                throw new Error(`Invalid name: "${this.shortName}". The parameter short name must be` +
+                    ` a dash followed by a single upper-case or lower-case letter (e.g. "-a")`);
+            }
+        }
+        if (this.parameterScope) {
+            if (!SCOPE_REGEXP.test(this.parameterScope)) {
+                throw new Error(`Invalid scope: "${this.parameterScope}". The parameter scope name must be` +
+                    ` lower-case and use dash delimiters (e.g. "my-scope")`);
+            }
+            // Parameter long name is guaranteed to start with '--' since this is validated above
+            const unprefixedLongName = this.longName.slice(2);
+            this.scopedLongName = `--${this.parameterScope}:${unprefixedLongName}`;
+        }
+        if (this.environmentVariable) {
+            if (!this.allowNonStandardEnvironmentVariableNames &&
+                !ENVIRONMENT_VARIABLE_NAME_REGEXP.test(this.environmentVariable)) {
+                throw new Error(`Invalid environment variable name: "${this.environmentVariable}". The name must` +
+                    ` consist only of upper-case letters, numbers, and underscores. It may not start with a number.`);
+            }
+        }
+        if (this.undocumentedSynonyms && this.undocumentedSynonyms.length > 0) {
+            for (const undocumentedSynonym of this.undocumentedSynonyms) {
+                if (this.longName === undocumentedSynonym) {
+                    throw new Error(`Invalid name: "${undocumentedSynonym}". Undocumented synonyms must not be the same` +
+                        ` as the the long name.`);
+                }
+                else if (!LONG_NAME_REGEXP.test(undocumentedSynonym)) {
+                    throw new Error(`Invalid name: "${undocumentedSynonym}". All undocumented synonyms name must be lower-case and ` +
+                        'use dash delimiters (e.g. "--do-a-thing")');
+                }
+            }
+        }
+    }
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterShortName} */
+    get shortName() {
+        return this._shortNameValue;
+    }
+    /**
+     * Returns additional text used by the help formatter.
+     * @internal
+     */
+    _getSupplementaryNotes(supplementaryNotes) {
+        // virtual
+        if (this.environmentVariable !== undefined) {
+            supplementaryNotes.push('This parameter may alternatively be specified via the ' +
+                this.environmentVariable +
+                ' environment variable.');
+        }
+    }
+    /**
+     * Internal usage only.  Used to report unexpected output from the argparse library.
+     */
+    reportInvalidData(data) {
+        throw new Error(`Unexpected data object for parameter "${this.longName}": ` + JSON.stringify(data));
+    }
+    validateDefaultValue(hasDefaultValue) {
+        if (this.required && hasDefaultValue) {
+            // If a parameter is "required", then the user understands that they always need to
+            // specify a value for this parameter (either via the command line or via an environment variable).
+            // It would be confusing to allow a default value that sometimes allows the "required" parameter
+            // to be omitted.  If you sometimes don't have a suitable default value, then the better approach
+            // is to throw a custom error explaining why the parameter is required in that case.
+            throw new Error(`A default value cannot be specified for "${this.longName}" because it is a "required" parameter`);
+        }
+    }
+}
+/**
+ * The common base class for parameters types that receive an argument.
+ *
+ * @remarks
+ * An argument is an accompanying command-line token, such as "123" in the
+ * example "--max-count 123".
+ * @public
+ */
+export class CommandLineParameterWithArgument extends CommandLineParameterBase {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        if (definition.argumentName === '') {
+            throw new Error('The argument name cannot be an empty string. (For the default name, specify undefined.)');
+        }
+        if (definition.argumentName.toUpperCase() !== definition.argumentName) {
+            throw new Error(`Invalid name: "${definition.argumentName}". The argument name must be all upper case.`);
+        }
+        const match = definition.argumentName.match(CommandLineParameterWithArgument._invalidArgumentNameRegExp);
+        if (match) {
+            throw new Error(`The argument name "${definition.argumentName}" contains an invalid character "${match[0]}".` +
+                ` Only upper-case letters, numbers, and underscores are allowed.`);
+        }
+        this.argumentName = definition.argumentName;
+        this.getCompletionsAsync = definition.getCompletionsAsync;
+    }
+}
+// Matches the first character that *isn't* part of a valid upper-case argument name such as "URL_2"
+CommandLineParameterWithArgument._invalidArgumentNameRegExp = /[^A-Z_0-9]/;
+//# sourceMappingURL=BaseClasses.js.map

package/lib-esm/parameters/BaseClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseClasses.js","sourceRoot":"","sources":["../../src/parameters/BaseClasses.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { SCOPING_PARAMETER_GROUP } from '../Constants';\nimport type {\n  IBaseCommandLineDefinition,\n  IBaseCommandLineDefinitionWithArgument\n} from './CommandLineDefinition';\nimport type { CommandLineChoiceListParameter } from './CommandLineChoiceListParameter';\nimport type { CommandLineChoiceParameter } from './CommandLineChoiceParameter';\nimport type { CommandLineFlagParameter } from './CommandLineFlagParameter';\nimport type { CommandLineIntegerListParameter } from './CommandLineIntegerListParameter';\nimport type { CommandLineIntegerParameter } from './CommandLineIntegerParameter';\nimport type { CommandLineStringListParameter } from './CommandLineStringListParameter';\nimport type { CommandLineStringParameter } from './CommandLineStringParameter';\n\n/**\n * Identifies the kind of a CommandLineParameter.\n * @public\n */\nexport enum CommandLineParameterKind {\n  /** Indicates a CommandLineChoiceParameter */\n  Choice,\n  /** Indicates a CommandLineFlagParameter */\n  Flag,\n  /** Indicates a CommandLineIntegerParameter */\n  Integer,\n  /** Indicates a CommandLineStringParameter */\n  String,\n  /** Indicates a CommandLineStringListParameter */\n  StringList,\n  /** Indicates a CommandLineChoiceListParameter */\n  ChoiceList,\n  /** Indicates a CommandLineIntegerListParameter */\n  IntegerList\n}\n\n/**\n * Matches kebab-case formatted strings prefixed with double dashes.\n * Example: \"--do-something\"\n */\nconst LONG_NAME_REGEXP: RegExp = /^-(-[a-z0-9]+)+$/;\n\n/**\n * Matches a single upper-case or lower-case letter prefixed with a dash.\n * Example: \"-d\"\n */\nconst SHORT_NAME_REGEXP: RegExp = /^-[a-zA-Z]$/;\n\n/**\n * Matches kebab-case formatted strings\n * Example: \"my-scope\"\n */\nconst SCOPE_REGEXP: RegExp = /^[a-z0-9]+(-[a-z0-9]+)*$/;\n\n/**\n * \"Environment variable names used by the utilities in the Shell and Utilities volume of\n * IEEE Std 1003.1-2001 consist solely of uppercase letters, digits, and the '_' (underscore)\n * from the characters defined in Portable Character Set and do not begin with a digit.\"\n * Example: \"THE_SETTING\"\n */\nconst ENVIRONMENT_VARIABLE_NAME_REGEXP: RegExp = /^[A-Z_][A-Z0-9_]*$/;\n\n/**\n * @public\n */\nexport type CommandLineParameter =\n  | CommandLineChoiceListParameter\n  | CommandLineChoiceParameter\n  | CommandLineFlagParameter\n  | CommandLineIntegerListParameter\n  | CommandLineIntegerParameter\n  | CommandLineStringListParameter\n  | CommandLineStringParameter;\n\n/**\n * The base class for the various command-line parameter types.\n * @public\n */\nexport abstract class CommandLineParameterBase {\n  private _shortNameValue: string | undefined;\n\n  /**\n   * A unique internal key used to retrieve the value from the parser's dictionary.\n   * @internal\n   */\n  public _parserKey: string | undefined;\n\n  /**\n   * @internal\n   */\n  public _preParse?: () => void;\n\n  /**\n   * @internal\n   */\n  public _postParse?: () => void;\n\n  /**\n   * @internal\n   */\n  public _validateValue?: () => void;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.parameterLongName} */\n  public readonly longName: string;\n\n  /**\n   * If a parameterScope is provided, returns the scope-prefixed long name of the flag,\n   * including double dashes, eg. \"--scope:do-something\". Otherwise undefined.\n   */\n  public readonly scopedLongName: string | undefined;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.parameterGroup} */\n  public readonly parameterGroup: string | typeof SCOPING_PARAMETER_GROUP | undefined;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.parameterScope} */\n  public readonly parameterScope: string | undefined;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.description} */\n  public readonly description: string;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.required} */\n  public readonly required: boolean;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.environmentVariable} */\n  public readonly environmentVariable: string | undefined;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.allowNonStandardEnvironmentVariableNames} */\n  public readonly allowNonStandardEnvironmentVariableNames: boolean | undefined;\n\n  /** {@inheritDoc IBaseCommandLineDefinition.undocumentedSynonyms } */\n  public readonly undocumentedSynonyms: string[] | undefined;\n\n  /** @internal */\n  public constructor(definition: IBaseCommandLineDefinition) {\n    this.longName = definition.parameterLongName;\n    this._shortNameValue = definition.parameterShortName;\n    this.parameterGroup = definition.parameterGroup;\n    this.parameterScope = definition.parameterScope;\n    this.description = definition.description;\n    this.required = !!definition.required;\n    this.environmentVariable = definition.environmentVariable;\n    this.undocumentedSynonyms = definition.undocumentedSynonyms;\n    this.allowNonStandardEnvironmentVariableNames = definition.allowNonStandardEnvironmentVariableNames;\n\n    if (!LONG_NAME_REGEXP.test(this.longName)) {\n      throw new Error(\n        `Invalid name: \"${this.longName}\". The parameter long name must be` +\n          ` lower-case and use dash delimiters (e.g. \"--do-a-thing\")`\n      );\n    }\n\n    if (this.shortName) {\n      if (!SHORT_NAME_REGEXP.test(this.shortName)) {\n        throw new Error(\n          `Invalid name: \"${this.shortName}\". The parameter short name must be` +\n            ` a dash followed by a single upper-case or lower-case letter (e.g. \"-a\")`\n        );\n      }\n    }\n\n    if (this.parameterScope) {\n      if (!SCOPE_REGEXP.test(this.parameterScope)) {\n        throw new Error(\n          `Invalid scope: \"${this.parameterScope}\". The parameter scope name must be` +\n            ` lower-case and use dash delimiters (e.g. \"my-scope\")`\n        );\n      }\n      // Parameter long name is guaranteed to start with '--' since this is validated above\n      const unprefixedLongName: string = this.longName.slice(2);\n      this.scopedLongName = `--${this.parameterScope}:${unprefixedLongName}`;\n    }\n\n    if (this.environmentVariable) {\n      if (\n        !this.allowNonStandardEnvironmentVariableNames &&\n        !ENVIRONMENT_VARIABLE_NAME_REGEXP.test(this.environmentVariable)\n      ) {\n        throw new Error(\n          `Invalid environment variable name: \"${this.environmentVariable}\". The name must` +\n            ` consist only of upper-case letters, numbers, and underscores. It may not start with a number.`\n        );\n      }\n    }\n\n    if (this.undocumentedSynonyms && this.undocumentedSynonyms.length > 0) {\n      for (const undocumentedSynonym of this.undocumentedSynonyms) {\n        if (this.longName === undocumentedSynonym) {\n          throw new Error(\n            `Invalid name: \"${undocumentedSynonym}\". Undocumented synonyms must not be the same` +\n              ` as the the long name.`\n          );\n        } else if (!LONG_NAME_REGEXP.test(undocumentedSynonym)) {\n          throw new Error(\n            `Invalid name: \"${undocumentedSynonym}\". All undocumented synonyms name must be lower-case and ` +\n              'use dash delimiters (e.g. \"--do-a-thing\")'\n          );\n        }\n      }\n    }\n  }\n\n  /** {@inheritDoc IBaseCommandLineDefinition.parameterShortName} */\n  public get shortName(): string | undefined {\n    return this._shortNameValue;\n  }\n\n  /**\n   * Called internally by CommandLineParameterProvider._processParsedData()\n   * @internal\n   */\n  public abstract _setValue(data: unknown): void;\n\n  /**\n   * Returns additional text used by the help formatter.\n   * @internal\n   */\n  public _getSupplementaryNotes(supplementaryNotes: string[]): void {\n    // virtual\n    if (this.environmentVariable !== undefined) {\n      supplementaryNotes.push(\n        'This parameter may alternatively be specified via the ' +\n          this.environmentVariable +\n          ' environment variable.'\n      );\n    }\n  }\n\n  /**\n   * Indicates the type of parameter.\n   */\n  public abstract get kind(): CommandLineParameterKind;\n\n  /**\n   * Append the parsed values to the provided string array.\n   * @remarks\n   * Sometimes a command line parameter is not used directly, but instead gets passed through to another\n   * tool that will use it.  For example if our parameter comes in as \"--max-count 3\", then we might want to\n   * call `child_process.spawn()` and append [\"--max-count\", \"3\"] to the args array for that tool.\n   * appendToArgList() appends zero or more strings to the provided array, based on the input command-line\n   * that we parsed.\n   *\n   * If the parameter was omitted from our command-line and has no default value, then\n   * nothing will be appended.  If the short name was used, the long name will be appended instead.\n   * @param argList - the parsed strings will be appended to this string array\n   */\n  public abstract appendToArgList(argList: string[]): void;\n\n  /**\n   * Internal usage only.  Used to report unexpected output from the argparse library.\n   */\n  protected reportInvalidData(data: unknown): never {\n    throw new Error(`Unexpected data object for parameter \"${this.longName}\": ` + JSON.stringify(data));\n  }\n\n  protected validateDefaultValue(hasDefaultValue: boolean): void {\n    if (this.required && hasDefaultValue) {\n      // If a parameter is \"required\", then the user understands that they always need to\n      // specify a value for this parameter (either via the command line or via an environment variable).\n      // It would be confusing to allow a default value that sometimes allows the \"required\" parameter\n      // to be omitted.  If you sometimes don't have a suitable default value, then the better approach\n      // is to throw a custom error explaining why the parameter is required in that case.\n      throw new Error(\n        `A default value cannot be specified for \"${this.longName}\" because it is a \"required\" parameter`\n      );\n    }\n  }\n}\n\n/**\n * The common base class for parameters types that receive an argument.\n *\n * @remarks\n * An argument is an accompanying command-line token, such as \"123\" in the\n * example \"--max-count 123\".\n * @public\n */\nexport abstract class CommandLineParameterWithArgument extends CommandLineParameterBase {\n  // Matches the first character that *isn't* part of a valid upper-case argument name such as \"URL_2\"\n  private static _invalidArgumentNameRegExp: RegExp = /[^A-Z_0-9]/;\n\n  /** {@inheritDoc IBaseCommandLineDefinitionWithArgument.argumentName} */\n  public readonly argumentName: string;\n\n  /** {@inheritDoc IBaseCommandLineDefinitionWithArgument.getCompletionsAsync} */\n  public readonly getCompletionsAsync:\n    | (() => Promise<ReadonlyArray<string> | ReadonlySet<string>>)\n    | undefined;\n\n  /** @internal */\n  public constructor(definition: IBaseCommandLineDefinitionWithArgument) {\n    super(definition);\n\n    if (definition.argumentName === '') {\n      throw new Error(\n        'The argument name cannot be an empty string. (For the default name, specify undefined.)'\n      );\n    }\n    if (definition.argumentName.toUpperCase() !== definition.argumentName) {\n      throw new Error(\n        `Invalid name: \"${definition.argumentName}\". The argument name must be all upper case.`\n      );\n    }\n    const match: RegExpMatchArray | null = definition.argumentName.match(\n      CommandLineParameterWithArgument._invalidArgumentNameRegExp\n    );\n    if (match) {\n      throw new Error(\n        `The argument name \"${definition.argumentName}\" contains an invalid character \"${match[0]}\".` +\n          ` Only upper-case letters, numbers, and underscores are allowed.`\n      );\n    }\n    this.argumentName = definition.argumentName;\n    this.getCompletionsAsync = definition.getCompletionsAsync;\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineChoiceListParameter.js

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterBase, CommandLineParameterKind } from './BaseClasses';
+import { EnvironmentVariableParser } from './EnvironmentVariableParser';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineChoiceListParameter}.
+ * @public
+ */
+export class CommandLineChoiceListParameter extends CommandLineParameterBase {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._values = [];
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = CommandLineParameterKind.ChoiceList;
+        const { alternatives, completions } = definition;
+        const alternativesSet = alternatives instanceof Set ? alternatives : new Set(alternatives);
+        if (alternativesSet.size < 1) {
+            throw new Error(`When defining a choice list parameter, the alternatives list must contain at least one value.`);
+        }
+        this.alternatives = alternativesSet;
+        this.completions = completions;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _setValue(data) {
+        // If argparse passed us a value, confirm it is valid
+        if (data !== null && data !== undefined) {
+            if (!Array.isArray(data)) {
+                this.reportInvalidData(data);
+            }
+            for (const arrayItem of data) {
+                if (typeof arrayItem !== 'string') {
+                    this.reportInvalidData(data);
+                }
+            }
+            this._values = data;
+            return;
+        }
+        if (this.environmentVariable !== undefined) {
+            const values = EnvironmentVariableParser.parseAsList(this.environmentVariable);
+            if (values) {
+                for (const value of values) {
+                    if (!this.alternatives.has(value)) {
+                        const choices = '"' + Array.from(this.alternatives).join('", "') + '"';
+                        throw new Error(`Invalid value "${value}" for the environment variable` +
+                            ` ${this.environmentVariable}.  Valid choices are: ${choices}`);
+                    }
+                }
+                this._values = values;
+                return;
+            }
+        }
+        // (No default value for choice lists)
+        this._values = [];
+    }
+    /**
+     * Returns the string arguments for a choice list parameter that was parsed from the command line.
+     *
+     * @remarks
+     * The array will be empty if the command-line has not been parsed yet,
+     * or if the parameter was omitted and has no default value.
+     */
+    get values() {
+        return this._values;
+    }
+    /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.values.length > 0) {
+            for (const value of this.values) {
+                argList.push(this.longName);
+                argList.push(value);
+            }
+        }
+    }
+}
+//# sourceMappingURL=CommandLineChoiceListParameter.js.map

package/lib-esm/parameters/CommandLineChoiceListParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineChoiceListParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineChoiceListParameter.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { ICommandLineChoiceListDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterBase, CommandLineParameterKind } from './BaseClasses';\nimport { EnvironmentVariableParser } from './EnvironmentVariableParser';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.defineChoiceListParameter}.\n * @public\n */\nexport class CommandLineChoiceListParameter<\n  TChoice extends string = string\n> extends CommandLineParameterBase {\n  /** {@inheritDoc ICommandLineChoiceListDefinition.alternatives} */\n  public readonly alternatives: ReadonlySet<TChoice>;\n\n  private _values: TChoice[] = [];\n\n  /** {@inheritDoc ICommandLineChoiceListDefinition.completions} */\n  public readonly completions: (() => Promise<ReadonlyArray<TChoice> | ReadonlySet<TChoice>>) | undefined;\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.ChoiceList = CommandLineParameterKind.ChoiceList;\n\n  /** @internal */\n  public constructor(definition: ICommandLineChoiceListDefinition<TChoice>) {\n    super(definition);\n    const { alternatives, completions } = definition;\n\n    const alternativesSet: Set<TChoice> = alternatives instanceof Set ? alternatives : new Set(alternatives);\n    if (alternativesSet.size < 1) {\n      throw new Error(\n        `When defining a choice list parameter, the alternatives list must contain at least one value.`\n      );\n    }\n\n    this.alternatives = alternativesSet;\n    this.completions = completions;\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // If argparse passed us a value, confirm it is valid\n    if (data !== null && data !== undefined) {\n      if (!Array.isArray(data)) {\n        this.reportInvalidData(data);\n      }\n      for (const arrayItem of data) {\n        if (typeof arrayItem !== 'string') {\n          this.reportInvalidData(data);\n        }\n      }\n      this._values = data;\n      return;\n    }\n\n    if (this.environmentVariable !== undefined) {\n      const values: string[] | undefined = EnvironmentVariableParser.parseAsList(this.environmentVariable);\n      if (values) {\n        for (const value of values) {\n          if (!this.alternatives.has(value as TChoice)) {\n            const choices: string = '\"' + Array.from(this.alternatives).join('\", \"') + '\"';\n            throw new Error(\n              `Invalid value \"${value}\" for the environment variable` +\n                ` ${this.environmentVariable}.  Valid choices are: ${choices}`\n            );\n          }\n        }\n\n        this._values = values as TChoice[];\n        return;\n      }\n    }\n\n    // (No default value for choice lists)\n\n    this._values = [];\n  }\n\n  /**\n   * Returns the string arguments for a choice list parameter that was parsed from the command line.\n   *\n   * @remarks\n   * The array will be empty if the command-line has not been parsed yet,\n   * or if the parameter was omitted and has no default value.\n   */\n  public get values(): ReadonlyArray<TChoice> {\n    return this._values;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.values.length > 0) {\n      for (const value of this.values) {\n        argList.push(this.longName);\n        argList.push(value);\n      }\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineChoiceParameter.js

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterBase, CommandLineParameterKind } from './BaseClasses';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.(defineChoiceParameter:1)}.
+ * @public
+ */
+export class CommandLineChoiceParameter extends CommandLineParameterBase {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._value = undefined;
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = -CommandLineParameterKind.Choice;
+        const { alternatives, defaultValue, completions } = definition;
+        const alternativesSet = alternatives instanceof Set ? alternatives : new Set(alternatives);
+        if (alternativesSet.size < 1) {
+            throw new Error(`When defining a choice parameter, the alternatives list must contain at least one value.`);
+        }
+        if (defaultValue && !alternativesSet.has(defaultValue)) {
+            throw new Error(`The specified default value "${defaultValue}"` +
+                ` is not one of the available options: ${alternatives.toString()}`);
+        }
+        this.alternatives = alternativesSet;
+        this.defaultValue = defaultValue;
+        this.validateDefaultValue(!!this.defaultValue);
+        this.completions = completions;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _setValue(data) {
+        // abstract
+        if (data !== null && data !== undefined) {
+            if (typeof data !== 'string') {
+                this.reportInvalidData(data);
+            }
+            this._value = data;
+            return;
+        }
+        if (this.environmentVariable !== undefined) {
+            // Try reading the environment variable
+            const environmentValue = process.env[this.environmentVariable];
+            if (environmentValue !== undefined && environmentValue !== '') {
+                if (!this.alternatives.has(environmentValue)) {
+                    const choices = '"' + Array.from(this.alternatives).join('", "') + '"';
+                    throw new Error(`Invalid value "${environmentValue}" for the environment variable` +
+                        ` ${this.environmentVariable}.  Valid choices are: ${choices}`);
+                }
+                this._value = environmentValue;
+                return;
+            }
+        }
+        if (this.defaultValue !== undefined) {
+            this._value = this.defaultValue;
+            return;
+        }
+        this._value = undefined;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._getSupplementaryNotes}
+     * @internal
+     */
+    _getSupplementaryNotes(supplementaryNotes) {
+        // virtual
+        super._getSupplementaryNotes(supplementaryNotes);
+        if (this.defaultValue !== undefined) {
+            supplementaryNotes.push(`The default value is "${this.defaultValue}".`);
+        }
+    }
+    /**
+     * Returns the argument value for a choice parameter that was parsed from the command line.
+     *
+     * @remarks
+     * The return value will be `undefined` if the command-line has not been parsed yet,
+     * or if the parameter was omitted and has no default value.
+     */
+    get value() {
+        return this._value;
+    }
+    /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.value !== undefined) {
+            argList.push(this.longName);
+            argList.push(this.value);
+        }
+    }
+}
+//# sourceMappingURL=CommandLineChoiceParameter.js.map

package/lib-esm/parameters/CommandLineChoiceParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineChoiceParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineChoiceParameter.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { ICommandLineChoiceDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterBase, CommandLineParameterKind } from './BaseClasses';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.(defineChoiceParameter:2)}.\n * @public\n */\nexport interface IRequiredCommandLineChoiceParameter<TChoice extends string = string>\n  extends CommandLineChoiceParameter<TChoice> {\n  readonly value: TChoice;\n}\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.(defineChoiceParameter:1)}.\n * @public\n */\nexport class CommandLineChoiceParameter<TChoice extends string = string> extends CommandLineParameterBase {\n  /** {@inheritDoc ICommandLineChoiceDefinition.alternatives} */\n  public readonly alternatives: ReadonlySet<TChoice>;\n\n  /** {@inheritDoc ICommandLineStringDefinition.defaultValue} */\n  public readonly defaultValue: TChoice | undefined;\n\n  private _value: TChoice | undefined = undefined;\n\n  /** {@inheritDoc ICommandLineChoiceDefinition.completions} */\n  public readonly completions: (() => Promise<ReadonlyArray<TChoice> | ReadonlySet<TChoice>>) | undefined;\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.Choice = -CommandLineParameterKind.Choice;\n\n  /** @internal */\n  public constructor(definition: ICommandLineChoiceDefinition<TChoice>) {\n    super(definition);\n    const { alternatives, defaultValue, completions } = definition;\n\n    const alternativesSet: Set<TChoice> = alternatives instanceof Set ? alternatives : new Set(alternatives);\n    if (alternativesSet.size < 1) {\n      throw new Error(\n        `When defining a choice parameter, the alternatives list must contain at least one value.`\n      );\n    }\n    if (defaultValue && !alternativesSet.has(defaultValue)) {\n      throw new Error(\n        `The specified default value \"${defaultValue}\"` +\n          ` is not one of the available options: ${alternatives.toString()}`\n      );\n    }\n\n    this.alternatives = alternativesSet;\n    this.defaultValue = defaultValue;\n    this.validateDefaultValue(!!this.defaultValue);\n    this.completions = completions;\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // abstract\n    if (data !== null && data !== undefined) {\n      if (typeof data !== 'string') {\n        this.reportInvalidData(data);\n      }\n      this._value = data as TChoice;\n      return;\n    }\n\n    if (this.environmentVariable !== undefined) {\n      // Try reading the environment variable\n      const environmentValue: string | undefined = process.env[this.environmentVariable];\n      if (environmentValue !== undefined && environmentValue !== '') {\n        if (!this.alternatives.has(environmentValue as TChoice)) {\n          const choices: string = '\"' + Array.from(this.alternatives).join('\", \"') + '\"';\n          throw new Error(\n            `Invalid value \"${environmentValue}\" for the environment variable` +\n              ` ${this.environmentVariable}.  Valid choices are: ${choices}`\n          );\n        }\n\n        this._value = environmentValue as TChoice;\n        return;\n      }\n    }\n\n    if (this.defaultValue !== undefined) {\n      this._value = this.defaultValue;\n      return;\n    }\n\n    this._value = undefined;\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._getSupplementaryNotes}\n   * @internal\n   */\n  public _getSupplementaryNotes(supplementaryNotes: string[]): void {\n    // virtual\n    super._getSupplementaryNotes(supplementaryNotes);\n    if (this.defaultValue !== undefined) {\n      supplementaryNotes.push(`The default value is \"${this.defaultValue}\".`);\n    }\n  }\n\n  /**\n   * Returns the argument value for a choice parameter that was parsed from the command line.\n   *\n   * @remarks\n   * The return value will be `undefined` if the command-line has not been parsed yet,\n   * or if the parameter was omitted and has no default value.\n   */\n  public get value(): TChoice | undefined {\n    return this._value;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.value !== undefined) {\n      argList.push(this.longName);\n      argList.push(this.value);\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineDefinition.js

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+export {};
+//# sourceMappingURL=CommandLineDefinition.js.map

package/lib-esm/parameters/CommandLineDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineDefinition.js","sourceRoot":"","sources":["../../src/parameters/CommandLineDefinition.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { SCOPING_PARAMETER_GROUP } from '../Constants';\n\n/**\n * For use with CommandLineParser, this interface represents a generic command-line parameter\n *\n * @public\n */\nexport interface IBaseCommandLineDefinition {\n  /**\n   * The long name of the flag including double dashes, e.g. \"--do-something\"\n   */\n  parameterLongName: string;\n\n  /**\n   * An optional short name for the flag including the dash, e.g. \"-d\"\n   */\n  parameterShortName?: string;\n\n  /**\n   * An optional parameter group name, shown when invoking the tool with \"--help\"\n   */\n  parameterGroup?: string | typeof SCOPING_PARAMETER_GROUP;\n\n  /**\n   * An optional parameter scope name, used to add a scope-prefixed parameter synonym,\n   * e.g. \"--scope:do-something\". Scopes provide additional flexibility for parameters\n   * in conflict resolution since when a scope is specified, parameters that have\n   * conflicting long names will be defined using only the scope-prefixed name.\n   */\n  parameterScope?: string;\n\n  /**\n   * Documentation for the parameter that will be shown when invoking the tool with \"--help\"\n   */\n  description: string;\n\n  /**\n   * If true, then an error occurs if the parameter was not included on the command-line.\n   */\n  required?: boolean;\n\n  /**\n   * The name of an environment variable that the parameter value will be read from,\n   * if it was omitted from the command-line.  An error will be reported if the\n   * environment value cannot be parsed.\n   *\n   * @remarks\n   * The environment variable name must consist only of upper-case letters, numbers,\n   * and underscores. It may not start with a number. To disable this validation, set\n   * `{@link IBaseCommandLineDefinition.allowNonStandardEnvironmentVariableNames}`\n   * to `true`.\n   *\n   * Syntax notes for environment variable values:\n   *\n   * - Choice Parameter: The value must match one of the defined choices,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - Flag Parameter: The value must be `1` for true, or `0` for false,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - Integer Parameter: The value must be an integer number,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - String Parameter: Any value is accepted, including an empty string.\n   *\n   * - String List Parameter: If the string starts with `[` (ignoring whitespace)\n   *   then it will be parsed as a JSON array, whose elements must be strings,\n   *   numbers, or boolean values.\n   *   If the string does not start with `[`, then it behaves like an\n   *   ordinary String Parameter:  Any value is accepted, including an empty string.\n   */\n  environmentVariable?: string;\n\n  /**\n   * Allows for the use of environment variable names that do not conform to the standard\n   * described by the Shell and Utilities volume of IEEE Std 1003.1-2001. This disables\n   * the validation that is performed on the provided\n   * {@link IBaseCommandLineDefinition.environmentVariable} value by default.\n   *\n   * @remarks\n   * if this is set to `true`, environment variable discovery will vary based on the\n   * platform in use. For example, Windows environment variable names are case-insensitive,\n   * while on Linux, environment variable names are case-sensitive. It is recommended that\n   * this option be used only when necessary based on environmental constraints.\n   */\n  allowNonStandardEnvironmentVariableNames?: boolean;\n\n  /**\n   * Specifies additional names for this parameter that are accepted but not displayed\n   * in the command line help.\n   *\n   * @remarks\n   * This option can be used in cases where a command-line parameter may have been renamed,\n   * but the developer doesn't want to break backwards compatibility with systems that may\n   * still be using the old name. Only the `parameterLongName` syntax is currently allowed.\n   */\n  undocumentedSynonyms?: string[];\n}\n\n/**\n * The common base interface for parameter types that accept an argument.\n *\n * @remarks\n * An argument is an accompanying command-line token, such as \"123\" in the\n * example \"--max-count 123\".\n * @public\n */\nexport interface IBaseCommandLineDefinitionWithArgument extends IBaseCommandLineDefinition {\n  /**\n   * The name of the argument, which will be shown in the command-line help.\n   *\n   * @remarks\n   * For example, if the parameter name is '--count\" and the argument name is \"NUMBER\",\n   * then the command-line help would display \"--count NUMBER\".  The argument name must\n   * be comprised of upper-case letters, numbers, and underscores.  It should be kept short.\n   */\n  argumentName: string;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  getCompletionsAsync?: () => Promise<ReadonlyArray<string> | ReadonlySet<string>>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.(defineChoiceParameter:1)} and\n * {@link CommandLineParameterProvider.(defineChoiceParameter:2)}, this interface\n * defines a command line parameter which is constrained to a list of possible\n * options.\n *\n * @public\n */\nexport interface ICommandLineChoiceDefinition<TChoice extends string = string>\n  extends IBaseCommandLineDefinition {\n  /**\n   * A list of strings (which contain no spaces), of possible options which can be selected\n   */\n  alternatives: ReadonlyArray<TChoice> | ReadonlySet<TChoice>;\n\n  /**\n   * {@inheritDoc ICommandLineStringDefinition.defaultValue}\n   */\n  defaultValue?: TChoice;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<ReadonlyArray<TChoice> | ReadonlySet<TChoice>>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineChoiceListParameter},\n * this interface defines a command line parameter which is constrained to a list of possible\n * options. The parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineChoiceListDefinition<TChoice extends string = string>\n  extends IBaseCommandLineDefinition {\n  /**\n   * A list of strings (which contain no spaces), of possible options which can be selected\n   */\n  alternatives: ReadonlyArray<TChoice> | ReadonlySet<TChoice>;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<ReadonlyArray<TChoice> | ReadonlySet<TChoice>>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineFlagParameter},\n * this interface defines a command line parameter that is a boolean flag.\n *\n * @public\n */\nexport interface ICommandLineFlagDefinition extends IBaseCommandLineDefinition {}\n\n/**\n * For use with {@link CommandLineParameterProvider.(defineIntegerParameter:1)},\n * {@link CommandLineParameterProvider.(defineIntegerParameter:2)}, this interface\n * defines a command line parameter whose argument is an integer value.\n *\n * @public\n */\nexport interface ICommandLineIntegerDefinition extends IBaseCommandLineDefinitionWithArgument {\n  /**\n   * {@inheritDoc ICommandLineStringDefinition.defaultValue}\n   */\n  defaultValue?: number;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineIntegerListParameter},\n * this interface defines a command line parameter whose argument is an integer value. The\n * parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineIntegerListDefinition extends IBaseCommandLineDefinitionWithArgument {}\n\n/**\n * For use with {@link CommandLineParameterProvider.(defineStringParameter:1)} and\n * {@link CommandLineParameterProvider.(defineStringParameter:2)}, this interface\n * defines a command line parameter whose argument is a string value.\n *\n * @public\n */\nexport interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument {\n  /**\n   * The default value which will be used if the parameter is omitted from the command line.\n   *\n   * @remarks\n   * If a default value is specified, then {@link IBaseCommandLineDefinition.required}\n   * must not be true.  Instead, a custom error message should be used to report cases\n   * where a default value was not available.\n   */\n  defaultValue?: string;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineStringListParameter},\n * this interface defines a command line parameter whose argument is a single text string.\n * The parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineStringListDefinition extends IBaseCommandLineDefinitionWithArgument {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineCommandLineRemainder},\n * this interface defines a rule that captures any remaining command line arguments after the recognized portion.\n *\n * @public\n */\nexport interface ICommandLineRemainderDefinition {\n  /**\n   * Documentation for how the remaining arguments will be used.  This will be shown when invoking\n   * the tool with \"--help\".\n   */\n  description: string;\n}\n"]}