@rushstack/rush-sdk 5.75.0 → 5.77.0

package/dist/rush-lib.d.ts

@@ -517,12 +517,12 @@ export declare enum EnvironmentVariableNames {
      */
     RUSH_GLOBAL_FOLDER = "RUSH_GLOBAL_FOLDER",
     /**
-     * Provides a credential for a remote build cache, if configured. Setting this environment variable
-     * overrides whatever credential has been saved in the local cloud cache credentials using
-     * `rush update-cloud-credentials`.
+     * Provides a credential for a remote build cache, if configured.  This credential overrides any cached credentials.
      *
      * @remarks
-     * This credential overrides any cached credentials.
+     * Setting this environment variable overrides whatever credential has been saved in the
+     * local cloud cache credentials using `rush update-cloud-credentials`.
+     *
      *
      * If Azure Blob Storage is used to store cache entries, this must be a SAS token serialized as query
      * parameters.
@@ -532,22 +532,28 @@ export declare enum EnvironmentVariableNames {
     RUSH_BUILD_CACHE_CREDENTIAL = "RUSH_BUILD_CACHE_CREDENTIAL",
     /**
      * Setting this environment variable overrides the value of `buildCacheEnabled` in the `build-cache.json`
-     * configuration file. Specify `1` to enable the build cache or `0` to disable it.
+     * configuration file.
+     *
+     * @remarks
+     * Specify `1` to enable the build cache or `0` to disable it.
      *
      * If set to `0`, this is equivalent to passing the `--disable-build-cache` flag.
+     *
+     * If there is no build cache configured, then this environment variable is ignored.
      */
     RUSH_BUILD_CACHE_ENABLED = "RUSH_BUILD_CACHE_ENABLED",
     /**
-     * Setting this environment variable overrides the value of `isCacheWriteAllowed` in the `build-cache.json`
-     * configuration file. Specify `1` to allow cache write and `0` to disable it.
+     * Overrides the value of `isCacheWriteAllowed` in the `build-cache.json` configuration file. The value of this
+     * environment variable must be `1` (for true) or `0` (for false). If there is no build cache configured, then
+     * this environment variable is ignored.
      */
     RUSH_BUILD_CACHE_WRITE_ALLOWED = "RUSH_BUILD_CACHE_WRITE_ALLOWED",
     /**
-     * Allows the git binary path to be explicitly specified.
+     * Explicitly specifies the path for the Git binary that is invoked by certain Rush operations.
      */
     RUSH_GIT_BINARY_PATH = "RUSH_GIT_BINARY_PATH",
     /**
-     * Allows the tar binary path to be explicitly specified.
+     * Explicitly specifies the path for the `tar` binary that is invoked by certain Rush operations.
      */
     RUSH_TAR_BINARY_PATH = "RUSH_TAR_BINARY_PATH",
     /**
@@ -1240,6 +1246,11 @@ export declare interface _IPnpmOptionsJson extends IPackageManagerOptionsJsonBas
     useWorkspaces?: boolean;
 }
 
+declare interface IRawRepoState {
+    projectState: Map<RushConfigurationProject, Map<string, string>> | undefined;
+    rootDir: string;
+}
+
 /**
  * Information about the currently executing command provided to plugins.
  * @beta
@@ -1288,7 +1299,8 @@ declare interface IRushConfigurationProjectJson {
     packageName: string;
     projectFolder: string;
     reviewCategory?: string;
-    cyclicDependencyProjects: string[];
+    decoupledLocalDependencies: string[];
+    cyclicDependencyProjects?: string[];
     versionPolicyName?: string;
     shouldPublish?: boolean;
     skipRushCheck?: boolean;
@@ -1373,8 +1385,8 @@ declare interface IRushRepositoryJsonMultipleUrls extends IRushRepositoryJsonBas
     /**
      * Remote url(s) of the repository. If a value is provided, \"rush change\" will
      * use one of these to find the right remote to compare against. Specifying multiple URLs
-     * is useful if a GitHub repository is renamed or for "<projectName>.visualstudio.com" vs
-     * "dev.azure.com/<projectName>" URLs.
+     * is useful if a GitHub repository is renamed or for `<projectName>.visualstudio.com` versus
+     * `dev.azure.com/<projectName>` URLs.
      */
     urls?: string[];
 }
@@ -1434,7 +1446,7 @@ export declare interface IStopwatchResult {
 export declare interface ITelemetryData {
     /**
      * Command name
-     * @example 'build'
+     * @example `"build"`
      */
     readonly name: string;
     /**
@@ -1446,25 +1458,86 @@ export declare interface ITelemetryData {
      */
     readonly result: 'Succeeded' | 'Failed';
     /**
-     * The timestamp of the telemetry logging
+     * The millisecond-resolution timestamp of the telemetry logging
      * @example 1648001893024
      */
-    readonly timestamp?: number;
+    readonly timestampMs?: number;
     /**
-     * The platform the command was executed on, reads from process.platform
-     * @example darwin, win32, linux...
+     * The platform the command was executed on, based on the Node.js `process.platform()` API
+     * @example `"darwin"`, `"win32"`, `"linux"`
      */
     readonly platform?: string;
     /**
-     * The rush version
-     * @example 5.63.0
+     * The Rush version
+     * @example `5.63.0`
      */
     readonly rushVersion?: string;
+    /**
+     * Detailed information about the host machine.
+     */
+    readonly machineInfo?: ITelemetryMachineInfo;
+    /**
+     * Only applicable to phased commands. Provides detailed results by operation.
+     * Keys are operation names, values contain result, timing information, and dependencies.
+     */
+    readonly operationResults?: Record<string, ITelemetryOperationResult>;
     readonly extraData?: {
         [key: string]: string | number | boolean;
     };
 }
 
+/**
+ * @beta
+ */
+export declare interface ITelemetryMachineInfo {
+    /**
+     * The CPU architecture
+     * @example `"AMD64"`
+     */
+    machineArchitecture: string;
+    /**
+     * The CPU model
+     * * @example `"AMD Ryzen 7 3700X 8-Core Processor"`
+     */
+    machineCpu: string;
+    /**
+     * The number of logical CPU cores.
+     */
+    machineCores: number;
+    /**
+     * The total amount of RAM on the machine, in MiB.
+     */
+    machineTotalMemoryMiB: number;
+    /**
+     * The amount of free RAM on the machine at the end of execution, in MiB.
+     */
+    machineFreeMemoryMiB: number;
+}
+
+/**
+ * @beta
+ */
+export declare interface ITelemetryOperationResult {
+    /**
+     * The names of operations that this operation depends on.
+     */
+    dependencies: string[];
+    /**
+     * The status code for the operation.
+     */
+    result: string;
+    /**
+     * A timestamp in milliseconds (from `performance.now()`) when the operation started.
+     * If the operation was blocked, will be `undefined`.
+     */
+    startTimestampMs?: number;
+    /**
+     * A timestamp in milliseconds (from `performance.now()`) when the operation finished.
+     * If the operation was blocked, will be `undefined`.
+     */
+    endTimestampMs?: number;
+}
+
 /**
  * Options for `RushConfiguration.tryFindRushJsonLocation`.
  * @public
@@ -2050,6 +2123,10 @@ export declare class ProjectChangeAnalyzer {
      * @internal
      */
     _tryGetProjectDependenciesAsync(project: RushConfigurationProject, terminal: ITerminal): Promise<Map<string, string> | undefined>;
+    /**
+     * @internal
+     */
+    _ensureInitialized(terminal: ITerminal): IRawRepoState | undefined;
     /**
      * The project state hash is calculated in the following way:
      * - Project dependencies are collected (see ProjectChangeAnalyzer.getPackageDeps)
@@ -2442,14 +2519,14 @@ export declare class RushConfiguration {
      * The minimum allowable folder depth for the projectFolder field in the rush.json file.
      * This setting provides a way for repository maintainers to discourage nesting of project folders
      * that makes the directory tree more difficult to navigate.  The default value is 2,
-     * which implements a standard 2-level hierarchy of <categoryFolder>/<projectFolder>/package.json.
+     * which implements a standard 2-level hierarchy of `<categoryFolder>/<projectFolder>/package.json`.
      */
     get projectFolderMinDepth(): number;
     /**
      * The maximum allowable folder depth for the projectFolder field in the rush.json file.
      * This setting provides a way for repository maintainers to discourage nesting of project folders
      * that makes the directory tree more difficult to navigate.  The default value is 2,
-     * which implements on a standard convention of <categoryFolder>/<projectFolder>/package.json.
+     * which implements on a standard convention of `<categoryFolder>/<projectFolder>/package.json`.
      */
     get projectFolderMaxDepth(): number;
     /**
@@ -2506,8 +2583,8 @@ export declare class RushConfiguration {
     /**
      * Remote URL(s) of the repository. If a value is provided, \"rush change\" will
      * use one of these to find the right remote to compare against. Specifying multiple URLs
-     * is useful if a GitHub repository is renamed or for "<projectName>.visualstudio.com" vs
-     * "dev.azure.com/<projectName>" URLs.
+     * is useful if a GitHub repository is renamed or for `<projectName>.visualstudio.com` versus
+     * `dev.azure.com/<projectName>` URLs.
      */
     get repositoryUrls(): string[];
     /**
@@ -2702,7 +2779,7 @@ export declare class RushConfigurationProject {
     private readonly _packageJsonEditor;
     private readonly _tempProjectName;
     private readonly _unscopedTempProjectName;
-    private readonly _cyclicDependencyProjects;
+    private readonly _decoupledLocalDependencies;
     private readonly _versionPolicyName;
     private readonly _shouldPublish;
     private readonly _skipRushCheck;
@@ -2761,6 +2838,16 @@ export declare class RushConfigurationProject {
      *
      * These are package names that would be found by RushConfiguration.getProjectByName().
      */
+    get decoupledLocalDependencies(): Set<string>;
+    /**
+     * A list of local projects that appear as devDependencies for this project, but cannot be
+     * locally linked because it would create a cyclic dependency; instead, the last published
+     * version will be installed in the Common folder.
+     *
+     * These are package names that would be found by RushConfiguration.getProjectByName().
+     *
+     * @deprecated Use `decoupledLocalDependencies` instead, as it better describes the purpose of the data.
+     */
     get cyclicDependencyProjects(): Set<string>;
     /**
      * An array of projects within the Rush configuration which directly depend on this package.
@@ -2856,7 +2943,13 @@ export declare class RushConfigurationProject {
      */
     get isMainProject(): boolean;
     /**
-     * The set of tags applied to this project.
+     * An optional set of custom tags that can be used to select this project.
+     *
+     * @remarks
+     * For example, adding `my-custom-tag` will allow this project to be selected by the
+     * command `rush list --only tag:my-custom-tag`.  The tag name must be one or more words separated
+     * by hyphens, where a word may contain lowercase letters, digits, and the period character.
+     *
      * @beta
      */
     get tags(): ReadonlySet<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rush-sdk",
-  "version": "5.75.0",
+  "version": "5.77.0",
   "description": "An API for interacting with the Rush engine",
   "repository": {
     "type": "git",
@@ -12,18 +12,18 @@
   "typings": "dist/rush-lib.d.ts",
   "license": "MIT",
   "dependencies": {
-    "@rushstack/node-core-library": "3.48.0",
+    "@rushstack/node-core-library": "3.51.1",
     "@types/node-fetch": "1.6.9",
     "tapable": "2.2.1"
   },
   "devDependencies": {
-    "@microsoft/rush-lib": "5.75.0",
-    "@rushstack/eslint-config": "2.6.2",
-    "@rushstack/heft": "0.45.14",
-    "@rushstack/heft-node-rig": "1.9.15",
-    "@rushstack/stream-collator": "4.0.184",
-    "@rushstack/ts-command-line": "4.12.1",
-    "@rushstack/terminal": "0.3.53",
+    "@microsoft/rush-lib": "5.77.0",
+    "@rushstack/eslint-config": "3.0.0",
+    "@rushstack/heft": "0.47.5",
+    "@rushstack/heft-node-rig": "1.10.5",
+    "@rushstack/stream-collator": "4.0.198",
+    "@rushstack/ts-command-line": "4.12.2",
+    "@rushstack/terminal": "0.3.67",
     "@types/heft-jest": "1.0.1",
     "@types/semver": "7.3.5",
     "@types/webpack-env": "1.13.0"