@rushstack/rush-sdk 5.76.1 → 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",
     /**
@@ -1440,7 +1446,7 @@ export declare interface IStopwatchResult {
 export declare interface ITelemetryData {
     /**
      * Command name
-     * @example 'build'
+     * @example `"build"`
      */
     readonly name: string;
     /**
@@ -1452,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
@@ -2876,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.76.1",
+  "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.50.1",
+    "@rushstack/node-core-library": "3.51.1",
     "@types/node-fetch": "1.6.9",
     "tapable": "2.2.1"
   },
   "devDependencies": {
-    "@microsoft/rush-lib": "5.76.1",
+    "@microsoft/rush-lib": "5.77.0",
     "@rushstack/eslint-config": "3.0.0",
-    "@rushstack/heft": "0.47.0",
-    "@rushstack/heft-node-rig": "1.10.0",
-    "@rushstack/stream-collator": "4.0.193",
+    "@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.62",
+    "@rushstack/terminal": "0.3.67",
     "@types/heft-jest": "1.0.1",
     "@types/semver": "7.3.5",
     "@types/webpack-env": "1.13.0"