@rushstack/rush-sdk 5.91.0 → 5.93.0

package/lib/api/CommandLineConfiguration.d.ts

@@ -0,0 +1,161 @@
+import type { CommandLineParameter } from '@rushstack/ts-command-line';
+import type { ICommandLineJson, IGlobalCommandJson, IFlagParameterJson, IChoiceParameterJson, IStringParameterJson, IIntegerParameterJson, IStringListParameterJson, IIntegerListParameterJson, IChoiceListParameterJson, IPhasedCommandWithoutPhasesJson } from './CommandLineJson';
+export interface IShellCommandTokenContext {
+    packageFolder: string;
+}
+/**
+ * Metadata about a phase.
+ * @alpha
+ */
+export interface IPhase {
+    /**
+     * The name of this phase.
+     */
+    name: string;
+    /**
+     * If set to `true,` this this phase was generated from a bulk command, and
+     * was not explicitly defined in the command-line.json file.
+     */
+    isSynthetic: boolean;
+    /**
+     * This property is used in the name of the filename for the logs generated by this
+     * phase. This is a filesystem-safe version of the phase name. For example,
+     * a phase with name `_phase:compile` has a `logFilenameIdentifier` of `_phase_compile`.
+     */
+    logFilenameIdentifier: string;
+    /**
+     * The set of custom command line parameters that are relevant to this phase.
+     */
+    associatedParameters: Set<CommandLineParameter>;
+    /**
+     * The resolved dependencies of the phase
+     */
+    dependencies: {
+        self: Set<IPhase>;
+        upstream: Set<IPhase>;
+    };
+    /**
+     * Normally Rush requires that each project's package.json has a `"scripts"` entry matching the phase name.
+     * To disable this check, set `ignoreMissingScript` to true.
+     */
+    ignoreMissingScript: boolean;
+    /**
+     * By default, Rush returns a nonzero exit code if errors or warnings occur during a command. If this option is
+     * set to `true`, Rush will return a zero exit code if warnings occur during the execution of this phase.
+     */
+    allowWarningsOnSuccess: boolean;
+    /**
+     * (Optional) If the `shellCommand` field is set for a bulk command, Rush will invoke it for each
+     * selected project; otherwise, Rush will invoke the package.json `"scripts"` entry matching Rush command/phase name.
+     *
+     * This string is the path to a script that will be invoked using the OS shell. The working directory will be
+     * the folder that contains rush.json.  If custom parameters are associated with this command, their
+     * values will be appended to the end of this string.
+     */
+    shellCommand?: string;
+}
+export interface ICommandWithParameters {
+    associatedParameters: Set<IParameterJson>;
+}
+export interface IPhasedCommandConfig extends IPhasedCommandWithoutPhasesJson, ICommandWithParameters {
+    /**
+     * If set to `true`, then this phased command was generated from a bulk command, and
+     * was not explicitly defined in the command-line.json file.
+     */
+    isSynthetic: boolean;
+    disableBuildCache?: boolean;
+    phases: Set<IPhase>;
+    /**
+     * If set to `true`, this phased command will always run in watch mode, regardless of CLI flags.
+     */
+    alwaysWatch: boolean;
+    /**
+     * The set of phases to execute when running this phased command in watch mode.
+     */
+    watchPhases: Set<IPhase>;
+    /**
+     * How many milliseconds to wait after receiving a file system notification before executing in watch mode.
+     */
+    watchDebounceMs?: number;
+    /**
+     * If set to `true`, then this phased command will always perform an install before executing, regardless of CLI flags.
+     * If set to `false`, then Rush will define a built-in "--install" CLI flag for this command.
+     * If undefined, then Rush does not define a built-in "--install" CLI flag for this command and no installation is performed.
+     */
+    alwaysInstall: boolean | undefined;
+}
+export interface IGlobalCommandConfig extends IGlobalCommandJson, ICommandWithParameters {
+}
+export declare type Command = IGlobalCommandConfig | IPhasedCommandConfig;
+/**
+ * Metadata about a custom parameter defined in command-line.json
+ * @alpha
+ */
+export declare type IParameterJson = IFlagParameterJson | IChoiceParameterJson | IStringParameterJson | IIntegerParameterJson | IStringListParameterJson | IIntegerListParameterJson | IChoiceListParameterJson;
+interface ICommandLineConfigurationOptions {
+    /**
+     * If true, do not include default build and rebuild commands.
+     */
+    doNotIncludeDefaultBuildCommands?: boolean;
+}
+/**
+ * Custom Commands and Options for the Rush Command Line
+ */
+export declare class CommandLineConfiguration {
+    private static _jsonSchema;
+    readonly commands: Map<string, Command>;
+    readonly phases: Map<string, IPhase>;
+    readonly parameters: IParameterJson[];
+    /**
+     * shellCommand from plugin custom command line configuration needs to be expanded with tokens
+     */
+    shellCommandTokenContext: IShellCommandTokenContext | undefined;
+    /**
+     * These path will be prepended to the PATH environment variable
+     */
+    readonly additionalPathFolders: Readonly<string[]>;
+    /**
+     * A map of bulk command names to their corresponding synthetic phase identifiers
+     */
+    private readonly _syntheticPhasesByTranslatedBulkCommandName;
+    /**
+     * Use CommandLineConfiguration.loadFromFile()
+     *
+     * @internal
+     */
+    constructor(commandLineJson: ICommandLineJson | undefined, options?: ICommandLineConfigurationOptions);
+    /**
+     * Performs a depth-first search to detect cycles in the directed graph of phase "self" dependencies.
+     *
+     * @param phase The phase node currently being checked
+     * @param phasesInPath The current path from the start node to `phase`
+     * @param cycleFreePhases Phases that have already been fully walked and confirmed to not be in any cycles
+     */
+    private _checkForPhaseSelfCycles;
+    /**
+     * Load the command-line.json configuration file from the specified path. Note that this
+     * does not include the default build settings. This option is intended to be used to load
+     * command-line.json files from plugins. To load a common/config/rush/command-line.json file,
+     * use {@see loadFromFileOrDefault} instead.
+     *
+     * If the file does not exist, this function returns `undefined`
+     */
+    static tryLoadFromFile(jsonFilePath: string): CommandLineConfiguration | undefined;
+    /**
+     * Loads the configuration from the specified file and applies any omitted default build
+     * settings.  If the file does not exist, then a default instance is returned.
+     * If the file contains errors, then an exception is thrown.
+     */
+    static loadFromFileOrDefault(jsonFilePath?: string): CommandLineConfiguration;
+    prependAdditionalPathFolder(pathFolder: string): void;
+    /**
+     * This function replaces colons (":") with underscores ("_").
+     *
+     * ts-command-line restricts command names to lowercase letters, numbers, underscores, and colons.
+     * Replacing colons with underscores produces a filesystem-safe name.
+     */
+    private _normalizeNameForLogFilenameIdentifiers;
+    private _translateBulkCommandToPhasedCommand;
+}
+export {};
+//# sourceMappingURL=CommandLineConfiguration.d.ts.map

package/lib/api/CommandLineConfiguration.js

@@ -0,0 +1 @@
+module.exports = require("../../lib-shim/index")._rushSdk_loadInternalModule("api/CommandLineConfiguration");

package/lib/api/CommandLineJson.d.ts

@@ -0,0 +1,251 @@
+/**
+ * "baseCommand" from command-line.schema.json
+ */
+export interface IBaseCommandJson {
+    commandKind: 'bulk' | 'global' | 'phased';
+    name: string;
+    summary: string;
+    /**
+     * If omitted, the summary will be used instead.
+     */
+    description?: string;
+    safeForSimultaneousRushProcesses: boolean;
+    autoinstallerName?: string;
+    shellCommand?: string;
+}
+/**
+ * "bulkCommand" from command-line.schema.json
+ */
+export interface IBulkCommandJson extends IBaseCommandJson {
+    commandKind: 'bulk';
+    enableParallelism: boolean;
+    ignoreDependencyOrder?: boolean;
+    ignoreMissingScript?: boolean;
+    incremental?: boolean;
+    allowWarningsInSuccessfulBuild?: boolean;
+    watchForChanges?: boolean;
+    disableBuildCache?: boolean;
+}
+/**
+ * Base interface shared by the "phasedCommand" JSON entries and the post-processed
+ * "IPhase" interface in the CommandLineConfiguration
+ */
+export interface IPhasedCommandWithoutPhasesJson extends IBaseCommandJson {
+    commandKind: 'phased';
+    enableParallelism: boolean;
+    incremental?: boolean;
+}
+/**
+ * "phasedCommand" from command-line.schema.json
+ */
+export interface IPhasedCommandJson extends IPhasedCommandWithoutPhasesJson {
+    phases: string[];
+    watchOptions?: {
+        alwaysWatch: boolean;
+        debounceMs?: number;
+        watchPhases: string[];
+    };
+    installOptions?: {
+        alwaysInstall: boolean;
+    };
+}
+/**
+ * "globalCommand" from command-line.schema.json
+ */
+export interface IGlobalCommandJson extends IBaseCommandJson {
+    commandKind: 'global';
+    shellCommand: string;
+}
+export declare type CommandJson = IBulkCommandJson | IGlobalCommandJson | IPhasedCommandJson;
+/**
+ * The dependencies of a phase.
+ * @alpha
+ */
+export interface IPhaseDependencies {
+    /**
+     * Dependency phases within the same project.
+     */
+    self?: string[];
+    /**
+     * Dependency phases in upstream projects.
+     */
+    upstream?: string[];
+}
+/**
+ * A phase, used in the phased command feature.
+ * @alpha
+ */
+export interface IPhaseJson {
+    /**
+     * The name of the phase. Note that this value must start with the \"_phase:\" prefix.
+     */
+    name: string;
+    /**
+     * The dependencies of this phase.
+     */
+    dependencies?: IPhaseDependencies;
+    /**
+     * Normally Rush requires that each project's package.json has a \"scripts\" entry matching the phase name. To disable this check, set \"ignoreMissingScript\" to true.
+     */
+    ignoreMissingScript?: boolean;
+    /**
+     * By default, Rush returns a nonzero exit code if errors or warnings occur during a command. If this option is set to \"true\", Rush will return a zero exit code if warnings occur during the execution of this phase.
+     */
+    allowWarningsOnSuccess?: boolean;
+}
+/**
+ * "baseParameter" from command-line.schema.json
+ * @public
+ */
+export interface IBaseParameterJson {
+    /**
+     * Indicates the kind of syntax for this command-line parameter: \"flag\" or \"choice\" or \"string\" or \"stringList\" or \"integerList\" or \"choiceList\".
+     */
+    parameterKind: 'flag' | 'choice' | 'string' | 'integer' | 'stringList' | 'integerList' | 'choiceList';
+    /**
+     * The name of the parameter (e.g. \"--verbose\").  This is a required field.
+     */
+    longName: string;
+    /**
+     * An optional short form of the parameter (e.g. \"-v\" instead of \"--verbose\").
+     */
+    shortName?: string;
+    /**
+     * A detailed description of the parameter, which appears when requesting help for the command (e.g. \"rush --help my-command\").
+     */
+    description: string;
+    /**
+     * A list of custom commands and/or built-in Rush commands that this parameter may be used with, by name.
+     */
+    associatedCommands?: string[];
+    /**
+     * A list of the names of the phases that this command-line parameter should be provided to.
+     */
+    associatedPhases?: string[];
+    /**
+     * If true, then this parameter must be included on the command line.
+     */
+    required?: boolean;
+}
+/**
+ * A custom command-line parameter whose presence acts as an on/off switch.
+ * @public
+ */
+export interface IFlagParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a flag (boolean) parameter.
+     */
+    parameterKind: 'flag';
+}
+/**
+ * Part of "choiceParameter" from command-line.schema.json
+ * @public
+ */
+export interface IChoiceParameterAlternativeJson {
+    /**
+     * A token that is one of the alternatives that can be used with the choice parameter, e.g. \"vanilla\" in \"--flavor vanilla\".
+     */
+    name: string;
+    /**
+     * A detailed description for the alternative that will be shown in the command-line help.
+     */
+    description: string;
+}
+/**
+ * A custom command-line parameter whose argument must be chosen from a list of allowable alternatives.
+ * @public
+ */
+export interface IChoiceParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a choice parameter.
+     */
+    parameterKind: 'choice';
+    /**
+     * A list of alternative argument values that can be chosen for this parameter.
+     */
+    alternatives: IChoiceParameterAlternativeJson[];
+    /**
+     * If the parameter is omitted from the command line, this value will be inserted by default.
+     */
+    defaultValue?: string;
+}
+/**
+ * A custom command-line parameter whose value is interpreted as a string.
+ * @public
+ */
+export interface IStringParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a string parameter.
+     */
+    parameterKind: 'string';
+    /**
+     * The name of the argument for this parameter.
+     */
+    argumentName: string;
+}
+/**
+ * A custom command-line parameter whose value is interpreted as a integer.
+ * @public
+ */
+export interface IIntegerParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a string parameter.
+     */
+    parameterKind: 'integer';
+    /**
+     * The name of the argument for this parameter.
+     */
+    argumentName: string;
+}
+/**
+ * A custom command-line parameter whose presence acts as a list of string
+ * @public
+ */
+export interface IStringListParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a string list parameter.
+     */
+    parameterKind: 'stringList';
+    /**
+     * The name of the argument for this parameter.
+     */
+    argumentName: string;
+}
+/**
+ * A custom command-line parameter whose presence acts as a list of integer
+ * @public
+ */
+export interface IIntegerListParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a integer list parameter.
+     */
+    parameterKind: 'integerList';
+    /**
+     * The name of the argument for this parameter.
+     */
+    argumentName: string;
+}
+/**
+ * A custom command-line parameter whose presence acts as a list of choice
+ * @public
+ */
+export interface IChoiceListParameterJson extends IBaseParameterJson {
+    /**
+     * Denotes that this is a choice list parameter.
+     */
+    parameterKind: 'choiceList';
+    /**
+     * A list of alternative argument values that can be chosen for this parameter.
+     */
+    alternatives: IChoiceParameterAlternativeJson[];
+}
+export declare type ParameterJson = IFlagParameterJson | IChoiceParameterJson | IStringParameterJson | IIntegerParameterJson | IStringListParameterJson | IIntegerListParameterJson | IChoiceListParameterJson;
+/**
+ * Interfaces for the file format described by command-line.schema.json
+ */
+export interface ICommandLineJson {
+    commands?: CommandJson[];
+    phases?: IPhaseJson[];
+    parameters?: ParameterJson[];
+}
+//# sourceMappingURL=CommandLineJson.d.ts.map

package/lib/api/CommandLineJson.js

@@ -0,0 +1 @@
+module.exports = require("../../lib-shim/index")._rushSdk_loadInternalModule("api/CommandLineJson");

package/lib/api/CommonVersionsConfiguration.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Part of the ICommonVersionsJson structure.
+ */
+export declare interface ICommonVersionsJsonVersionMap {
+    /**
+     * The key is the name of a dependency.  The value is a Semantic Versioning (SemVer)
+     * range specifier.
+     */
+    [dependencyName: string]: string;
+}
+/**
+ * Part of the ICommonVersionsJson structure.
+ */
+export declare interface ICommonVersionsJsonVersionsMap {
+    /**
+     * The key is the name of a dependency.  The value is a list of Semantic Versioning (SemVer)
+     * range specifiers.
+     */
+    [dependencyName: string]: string[];
+}
+/**
+ * Use this class to load and save the "common/config/rush/common-versions.json" config file.
+ * This config file stores dependency version information that affects all projects in the repo.
+ * @public
+ */
+export declare class CommonVersionsConfiguration {
+    private static _jsonSchema;
+    private _preferredVersions;
+    private _allowedAlternativeVersions;
+    private _modified;
+    /**
+     * Get the absolute file path of the common-versions.json file.
+     */
+    readonly filePath: string;
+    /**
+     * When set to true, for all projects in the repo, all dependencies will be automatically added as preferredVersions,
+     * except in cases where different projects specify different version ranges for a given dependency.  For older
+     * package managers, this tended to reduce duplication of indirect dependencies.  However, it can sometimes cause
+     * trouble for indirect dependencies with incompatible peerDependencies ranges.
+     *
+     * If the value is `undefined`, then the default value is `true`.
+     */
+    readonly implicitlyPreferredVersions: boolean | undefined;
+    /**
+     * A table that specifies a "preferred version" for a given NPM package.  This feature is typically used
+     * to hold back an indirect dependency to a specific older version, or to reduce duplication of indirect dependencies.
+     *
+     * @remarks
+     * The "preferredVersions" value can be any SemVer range specifier (e.g. `~1.2.3`).  Rush injects these values into
+     * the "dependencies" field of the top-level common/temp/package.json, which influences how the package manager
+     * will calculate versions.  The specific effect depends on your package manager.  Generally it will have no
+     * effect on an incompatible or already constrained SemVer range.  If you are using PNPM, similar effects can be
+     * achieved using the pnpmfile.js hook.  See the Rush documentation for more details.
+     *
+     * After modifying this field, it's recommended to run `rush update --full` so that the package manager
+     * will recalculate all version selections.
+     */
+    readonly preferredVersions: Map<string, string>;
+    /**
+     * A table that stores, for a given dependency, a list of SemVer ranges that will be accepted
+     * by "rush check" in addition to the normal version range.
+     *
+     * @remarks
+     * The "rush check" command can be used to enforce that every project in the repo
+     * must specify the same SemVer range for a given dependency.  However, sometimes
+     * exceptions are needed.  The allowedAlternativeVersions table allows you to list
+     * other SemVer ranges that will be accepted by "rush check" for a given dependency.
+     * Note that the normal version range (as inferred by looking at all projects in the repo)
+     * should NOT be included in this list.
+     */
+    readonly allowedAlternativeVersions: Map<string, ReadonlyArray<string>>;
+    private constructor();
+    /**
+     * Loads the common-versions.json data from the specified file path.
+     * If the file has not been created yet, then an empty object is returned.
+     */
+    static loadFromFile(jsonFilename: string): CommonVersionsConfiguration;
+    private static _deserializeTable;
+    private static _serializeTable;
+    /**
+     * Get a sha1 hash of the preferred versions.
+     */
+    getPreferredVersionsHash(): string;
+    /**
+     * Writes the "common-versions.json" file to disk, using the filename that was passed to loadFromFile().
+     */
+    save(): boolean;
+    /**
+     * Returns preferredVersions.
+     */
+    getAllPreferredVersions(): Map<string, string>;
+    private _onSetPreferredVersions;
+    private _onSetAllowedAlternativeVersions;
+    private _serialize;
+}
+//# sourceMappingURL=CommonVersionsConfiguration.d.ts.map

package/lib/api/CommonVersionsConfiguration.js

@@ -0,0 +1 @@
+module.exports = require("../../lib-shim/index")._rushSdk_loadInternalModule("api/CommonVersionsConfiguration");