@rushstack/rush-sdk 5.134.0 → 5.135.0

package/dist/rush-lib.d.ts

@@ -256,6 +256,11 @@ export declare class CobuildConfiguration {
      * to improve the performance in CI validations and the leaf projects have not enabled cache.
      */
     readonly cobuildLeafProjectLogOnlyAllowed: boolean;
+    /**
+     * If true, operations can opt into leveraging cobuilds without restoring from the build cache.
+     *  Operations will need to us the allowCobuildWithoutCache flag to opt into this behavior per phase.
+     */
+    readonly cobuildWithoutCacheAllowed: boolean;
     private _cobuildLockProvider;
     private readonly _cobuildLockProviderFactory;
     private readonly _cobuildJson;
@@ -1428,6 +1433,12 @@ export declare interface IExperimentsJson {
      * ignore normal discussion group messages or don't know to subscribe.
      */
     rushAlerts?: boolean;
+    /**
+     * Allow cobuilds without using the build cache to store previous execution info. When setting up
+     *  distributed builds, Rush will allow uncacheable projects to still leverage the cobuild feature.
+     * This is useful when you want to speed up operations that can't (or shouldn't) be cached.
+     */
+    allowCobuildWithoutCache?: boolean;
 }
 
 /**
@@ -1543,6 +1554,38 @@ declare interface ILockStepVersionJson extends IVersionPolicyJson {
     mainProject?: string;
 }
 
+/**
+ * Information about the log files for an operation.
+ *
+ * @alpha
+ */
+export declare interface ILogFilePaths {
+    /**
+     * The absolute path to the folder containing the text log files.
+     * Provided as a convenience since it is an intermediary value of producing the text log file path.
+     */
+    textFolder: string;
+    /**
+     * The absolute path to the folder containing the JSONL log files.
+     * Provided as a convenience since it is an intermediary value of producing the jsonl log file path.
+     */
+    jsonlFolder: string;
+    /**
+     * The absolute path to the merged (interleaved stdout and stderr) text log.
+     * ANSI escape codes have been stripped.
+     */
+    text: string;
+    /**
+     * The absolute path to the stderr text log.
+     * ANSI escape codes have been stripped.
+     */
+    error: string;
+    /**
+     * The absolute path to the JSONL log. ANSI escape codes are left intact to be able to reproduce the console output.
+     */
+    jsonl: string;
+}
+
 /**
  * @beta
  */
@@ -1645,6 +1688,10 @@ export declare interface IOperationExecutionResult {
      * The id of the runner which actually runs the building process in cobuild mode.
      */
     readonly cobuildRunnerId: string | undefined;
+    /**
+     * The paths to the log files, if applicable.
+     */
+    readonly logFilePaths: ILogFilePaths | undefined;
 }
 
 /**
@@ -1849,6 +1896,10 @@ export declare interface IOperationSettings {
      *  determined by the -p flag.
      */
     weight?: number;
+    /**
+     * If true, this operation can use cobuilds for orchestration without restoring build cache entries.
+     */
+    allowCobuildWithoutCache?: boolean;
 }
 
 /**
@@ -2241,15 +2292,9 @@ export declare interface IRushPhaseSharding {
      */
     outputFolderArgumentFormat?: string;
     /**
-     * Configuration for the shard operation. All other configuration applies to the collator operation.
+     * @deprecated Create a separate operation settings object for the shard operation settings with the name `{operationName}:shard`.
      */
-    shardOperationSettings?: {
-        /**
-         * How many concurrency units this operation should take up during execution. The maximum concurrent units is
-         *  determined by the -p flag.
-         */
-        weight?: number;
-    };
+    shardOperationSettings?: unknown;
 }
 
 /**

package/lib/api/CobuildConfiguration.d.ts

@@ -53,6 +53,11 @@ export declare class CobuildConfiguration {
      * to improve the performance in CI validations and the leaf projects have not enabled cache.
      */
     readonly cobuildLeafProjectLogOnlyAllowed: boolean;
+    /**
+     * If true, operations can opt into leveraging cobuilds without restoring from the build cache.
+     *  Operations will need to us the allowCobuildWithoutCache flag to opt into this behavior per phase.
+     */
+    readonly cobuildWithoutCacheAllowed: boolean;
     private _cobuildLockProvider;
     private readonly _cobuildLockProviderFactory;
     private readonly _cobuildJson;

package/lib/api/ExperimentsConfiguration.d.ts

@@ -83,6 +83,12 @@ export interface IExperimentsJson {
      * ignore normal discussion group messages or don't know to subscribe.
      */
     rushAlerts?: boolean;
+    /**
+     * Allow cobuilds without using the build cache to store previous execution info. When setting up
+     *  distributed builds, Rush will allow uncacheable projects to still leverage the cobuild feature.
+     * This is useful when you want to speed up operations that can't (or shouldn't) be cached.
+     */
+    allowCobuildWithoutCache?: boolean;
 }
 /**
  * Use this class to load the "common/config/rush/experiments.json" config file.

package/lib/api/RushProjectConfiguration.d.ts

@@ -47,15 +47,9 @@ export interface IRushPhaseSharding {
      */
     outputFolderArgumentFormat?: string;
     /**
-     * Configuration for the shard operation. All other configuration applies to the collator operation.
-     */
-    shardOperationSettings?: {
-        /**
-         * How many concurrency units this operation should take up during execution. The maximum concurrent units is
-         *  determined by the -p flag.
-         */
-        weight?: number;
-    };
+     * @deprecated Create a separate operation settings object for the shard operation settings with the name `{operationName}:shard`.
+     */
+    shardOperationSettings?: unknown;
 }
 /**
  * @alpha
@@ -115,6 +109,10 @@ export interface IOperationSettings {
      *  determined by the -p flag.
      */
     weight?: number;
+    /**
+     * If true, this operation can use cobuilds for orchestration without restoring build cache entries.
+     */
+    allowCobuildWithoutCache?: boolean;
 }
 /**
  * Use this class to load the "config/rush-project.json" config file.

package/lib/index.d.ts

@@ -41,6 +41,7 @@ export type { IOperationRunner, IOperationRunnerContext } from './logic/operatio
 export type { IExecutionResult, IOperationExecutionResult } from './logic/operations/IOperationExecutionResult';
 export { type IOperationOptions, Operation } from './logic/operations/Operation';
 export { OperationStatus } from './logic/operations/OperationStatus';
+export type { ILogFilePaths } from './logic/operations/ProjectLogWritable';
 export { RushSession, type IRushSessionOptions, type CloudBuildCacheProviderFactory, type CobuildLockProviderFactory } from './pluginFramework/RushSession';
 export { type IRushCommand, type IGlobalCommand, type IPhasedCommand, RushLifecycleHooks } from './pluginFramework/RushLifeCycle';
 export { type ICreateOperationsContext, type IExecuteOperationsContext, PhasedCommandHooks } from './pluginFramework/PhasedCommandHooks';

package/lib/logic/operations/CacheableOperationPlugin.d.ts

@@ -1,8 +1,7 @@
-import { type ITerminal } from '@rushstack/terminal';
+import { type TerminalWritable, type ITerminal } from '@rushstack/terminal';
 import { CobuildLock } from '../cobuild/CobuildLock';
 import { ProjectBuildCache } from '../buildCache/ProjectBuildCache';
 import { type IOperationSettings } from '../../api/RushProjectConfiguration';
-import { ProjectLogWritable } from './ProjectLogWritable';
 import type { CobuildConfiguration } from '../../api/CobuildConfiguration';
 import { DisjointSet } from '../cobuild/DisjointSet';
 import { PeriodicCallback } from './PeriodicCallback';
@@ -26,7 +25,7 @@ export interface IOperationBuildCacheContext {
     cobuildLock: CobuildLock | undefined;
     cobuildClusterId: string | undefined;
     buildCacheTerminal: ITerminal | undefined;
-    buildCacheProjectLogWritable: ProjectLogWritable | undefined;
+    buildCacheTerminalWritable: TerminalWritable | undefined;
     periodicCallback: PeriodicCallback;
     cacheRestored: boolean;
     isCacheReadAttempted: boolean;
@@ -48,7 +47,7 @@ export declare class CacheableOperationPlugin implements IPhasedCommandPlugin {
     private _tryGetLogOnlyProjectBuildCacheAsync;
     private _tryGetCobuildLockAsync;
     private _createBuildCacheTerminalAsync;
-    private _tryGetBuildCacheProjectLogWritableAsync;
+    private _tryGetBuildCacheTerminalWritableAsync;
 }
 export declare function clusterOperations(initialClusters: DisjointSet<Operation>, operationBuildCacheMap: Map<Operation, {
     cacheDisabledReason: string | undefined;

package/lib/logic/operations/IOperationExecutionResult.d.ts

@@ -2,6 +2,7 @@ import type { StdioSummarizer } from '@rushstack/terminal';
 import type { OperationStatus } from './OperationStatus';
 import type { Operation } from './Operation';
 import type { IStopwatchResult } from '../../utilities/Stopwatch';
+import type { ILogFilePaths } from './ProjectLogWritable';
 /**
  * The `IOperationExecutionResult` interface represents the results of executing an {@link Operation}.
  * @alpha
@@ -39,6 +40,10 @@ export interface IOperationExecutionResult {
      * The id of the runner which actually runs the building process in cobuild mode.
      */
     readonly cobuildRunnerId: string | undefined;
+    /**
+     * The paths to the log files, if applicable.
+     */
+    readonly logFilePaths: ILogFilePaths | undefined;
 }
 /**
  * The `IExecutionResult` interface represents the results of executing a set of {@link Operation}s.

package/lib/logic/operations/OperationExecutionRecord.d.ts

@@ -7,6 +7,7 @@ import { Stopwatch } from '../../utilities/Stopwatch';
 import { OperationMetadataManager } from './OperationMetadataManager';
 import type { IPhase } from '../../api/CommandLineConfiguration';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
+import { type ILogFilePaths } from './ProjectLogWritable';
 export interface IOperationExecutionRecordContext {
     streamCollator: StreamCollator;
     onOperationStatusChanged?: (record: OperationExecutionRecord) => void;
@@ -74,6 +75,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
     readonly associatedPhase: IPhase | undefined;
     readonly associatedProject: RushConfigurationProject | undefined;
     readonly _operationMetadataManager: OperationMetadataManager | undefined;
+    logFilePaths: ILogFilePaths | undefined;
     private readonly _context;
     private _collatedWriter;
     private _status;

package/lib/logic/operations/ProjectLogWritable.d.ts

@@ -1,68 +1,122 @@
 import { TerminalWritable, type ITerminalChunk } from '@rushstack/terminal';
-import type { CollatedTerminal } from '@rushstack/stream-collator';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
 export interface IProjectLogWritableOptions {
-    project: RushConfigurationProject;
-    terminal: CollatedTerminal;
-    logFilenameIdentifier: string;
+    logFilePaths: ILogFilePaths;
     enableChunkedOutput?: boolean;
 }
+export interface ILogFileNames {
+    textFileName: string;
+    jsonlFileName: string;
+    errorFileName: string;
+}
+/**
+ * Information about the log files for an operation.
+ *
+ * @alpha
+ */
 export interface ILogFilePaths {
-    logFolderPath: string;
-    logChunksFolderPath: string;
-    logPath: string;
-    logChunksPath: string;
-    errorLogPath: string;
-    relativeLogPath: string;
-    relativeErrorLogPath: string;
-    relativeLogChunksPath: string;
+    /**
+     * The absolute path to the folder containing the text log files.
+     * Provided as a convenience since it is an intermediary value of producing the text log file path.
+     */
+    textFolder: string;
+    /**
+     * The absolute path to the folder containing the JSONL log files.
+     * Provided as a convenience since it is an intermediary value of producing the jsonl log file path.
+     */
+    jsonlFolder: string;
+    /**
+     * The absolute path to the merged (interleaved stdout and stderr) text log.
+     * ANSI escape codes have been stripped.
+     */
+    text: string;
+    /**
+     * The absolute path to the stderr text log.
+     * ANSI escape codes have been stripped.
+     */
+    error: string;
+    /**
+     * The absolute path to the JSONL log. ANSI escape codes are left intact to be able to reproduce the console output.
+     */
+    jsonl: string;
 }
 export interface IGetLogFilePathsOptions {
-    project: RushConfigurationProject;
+    project: Pick<RushConfigurationProject, 'projectFolder' | 'packageName'>;
     logFilenameIdentifier: string;
 }
-export declare class ProjectLogWritable extends TerminalWritable {
-    private readonly _terminal;
+/**
+ * A terminal stream that writes all log chunks to a JSONL format so they can be faithfully reconstructed
+ *  during build cache restores. This is used for adding warning + error messages in cobuilds where the original
+ *  logs cannot be completely restored from the existing `all.log` and `error.log` files.
+ *
+ * Example output:
+ * libraries/rush-lib/.rush/temp/operations/rush-lib._phase_build.chunks.jsonl
+ * ```
+ * {"kind":"O","text":"Invoking: heft run --only build -- --clean \n"}
+ * {"kind":"O","text":" ---- build started ---- \n"}
+ * {"kind":"O","text":"[build:clean] Deleted 0 files and 5 folders\n"}
+ * {"kind":"O","text":"[build:typescript] Using TypeScript version 5.4.2\n"}
+ * {"kind":"O","text":"[build:lint] Using ESLint version 8.57.0\n"}
+ * {"kind":"E","text":"[build:lint] Warning: libraries/rush-lib/src/logic/operations/LogChunksWritable.ts:15:7 - (@typescript-eslint/typedef) Expected test to have a type annotation.\n"}
+ * {"kind":"E","text":"[build:lint] Warning: libraries/rush-lib/src/logic/operations/LogChunksWritable.ts:15:7 - (@typescript-eslint/no-unused-vars) 'test' is assigned a value but never used.\n"}
+ * {"kind":"O","text":"[build:typescript] Copied 1138 folders or files and linked 0 files\n"}
+ * {"kind":"O","text":"[build:webpack] Using Webpack version 5.82.1\n"}
+ * {"kind":"O","text":"[build:webpack] Running Webpack compilation\n"}
+ * {"kind":"O","text":"[build:api-extractor] Using API Extractor version 7.43.1\n"}
+ * {"kind":"O","text":"[build:api-extractor] Analysis will use the bundled TypeScript version 5.4.2\n"}
+ * {"kind":"O","text":"[build:copy-mock-flush-telemetry-plugin] Copied 1260 folders or files and linked 5 files\n"}
+ * {"kind":"O","text":" ---- build finished (6.856s) ---- \n"}
+ * {"kind":"O","text":"-------------------- Finished (6.858s) --------------------\n"}
+ * ```
+ */
+export declare class JsonLFileWritable extends TerminalWritable {
+    readonly logPath: string;
+    private _writer;
+    constructor(logPath: string);
+    writeChunk(chunk: ITerminalChunk): void;
+    protected onWriteChunk(chunk: ITerminalChunk): void;
+    protected onClose(): void;
+}
+/**
+ * A terminal stream that writes two text log files: one with interleaved stdout and stderr, and one with just stderr.
+ */
+export declare class SplitLogFileWritable extends TerminalWritable {
     readonly logPath: string;
     readonly errorLogPath: string;
-    readonly logChunksPath: string;
-    readonly relativeLogPath: string;
-    readonly relativeErrorLogPath: string;
-    readonly relativeLogChunksPath: string;
     private _logWriter;
     private _errorLogWriter;
-    /**
-     * A new terminal stream that writes all log chunks to a JSON format so they can be faithfully reconstructed
-     *  during build cache restores. This is used for adding warning + error messages in cobuilds where the original
-     *  logs cannot be completely restored from the existing `all.log` and `error.log` files.
-     *
-     * Example output:
-     * libraries/rush-lib/.rush/temp/operations/rush-lib._phase_build.chunks.jsonl
-     * ```
-     * {"kind":"O","text":"Invoking: heft run --only build -- --clean \n"}
-     * {"kind":"O","text":" ---- build started ---- \n"}
-     * {"kind":"O","text":"[build:clean] Deleted 0 files and 5 folders\n"}
-     * {"kind":"O","text":"[build:typescript] Using TypeScript version 5.4.2\n"}
-     * {"kind":"O","text":"[build:lint] Using ESLint version 8.57.0\n"}
-     * {"kind":"E","text":"[build:lint] Warning: libraries/rush-lib/src/logic/operations/LogChunksWritable.ts:15:7 - (@typescript-eslint/typedef) Expected test to have a type annotation.\n"}
-     * {"kind":"E","text":"[build:lint] Warning: libraries/rush-lib/src/logic/operations/LogChunksWritable.ts:15:7 - (@typescript-eslint/no-unused-vars) 'test' is assigned a value but never used.\n"}
-     * {"kind":"O","text":"[build:typescript] Copied 1138 folders or files and linked 0 files\n"}
-     * {"kind":"O","text":"[build:webpack] Using Webpack version 5.82.1\n"}
-     * {"kind":"O","text":"[build:webpack] Running Webpack compilation\n"}
-     * {"kind":"O","text":"[build:api-extractor] Using API Extractor version 7.43.1\n"}
-     * {"kind":"O","text":"[build:api-extractor] Analysis will use the bundled TypeScript version 5.4.2\n"}
-     * {"kind":"O","text":"[build:copy-mock-flush-telemetry-plugin] Copied 1260 folders or files and linked 5 files\n"}
-     * {"kind":"O","text":" ---- build finished (6.856s) ---- \n"}
-     * {"kind":"O","text":"-------------------- Finished (6.858s) --------------------\n"}
-     * ```
-     */
-    private _chunkWriter;
-    private _enableChunkedOutput;
-    private constructor();
-    static initializeAsync({ project, terminal, logFilenameIdentifier, enableChunkedOutput }: IProjectLogWritableOptions): Promise<ProjectLogWritable>;
-    static getLogFilePaths({ project: { projectFolder, packageName }, logFilenameIdentifier }: IGetLogFilePathsOptions): ILogFilePaths;
+    constructor(logPath: string, errorLogPath: string);
     writeChunk(chunk: ITerminalChunk): void;
     protected onWriteChunk(chunk: ITerminalChunk): void;
     protected onClose(): void;
 }
+/**
+ * Initializes the project log files for a project. Produces a combined log file, an error log file, and optionally a
+ * chunks file that can be used to reconstrct the original console output.
+ * @param options - The options to initialize the project log files.
+ * @returns The terminal writable stream that will write to the log files.
+ */
+export declare function initializeProjectLogFilesAsync(options: IProjectLogWritableOptions): Promise<TerminalWritable>;
+/**
+ * @internal
+ *
+ * @param packageName - The raw package name
+ * @param logFilenameIdentifier - The identifier to append to the log file name (typically the phase name)
+ * @returns The base names of the log files
+ */
+export declare function getLogfileBaseNames(packageName: string, logFilenameIdentifier: string): ILogFileNames;
+/**
+ * @internal
+ *
+ * @param projectFolder - The absolute path of the project folder
+ * @returns The absolute paths of the log folders for regular and chunked logs
+ */
+export declare function getProjectLogFolders(projectFolder: string): Pick<ILogFilePaths, 'textFolder' | 'jsonlFolder'>;
+/**
+ * @internal
+ *
+ * @param options - The options to get the log file paths
+ * @returns All information about log file paths for the project and log identifier
+ */
+export declare function getProjectLogFilePaths(options: IGetLogFilePathsOptions): ILogFilePaths;
 //# sourceMappingURL=ProjectLogWritable.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rush-sdk",
-  "version": "5.134.0",
+  "version": "5.135.0",
   "description": "An API for interacting with the Rush engine",
   "repository": {
     "type": "git",
@@ -43,13 +43,13 @@
     "@types/semver": "7.5.0",
     "@types/webpack-env": "1.18.0",
     "webpack": "~5.82.1",
+    "@microsoft/rush-lib": "5.135.0",
     "@rushstack/heft": "0.67.2",
-    "local-node-rig": "1.0.0",
     "@rushstack/heft-webpack5-plugin": "0.10.11",
-    "@microsoft/rush-lib": "5.134.0",
-    "@rushstack/ts-command-line": "4.22.8",
     "@rushstack/stream-collator": "4.1.67",
-    "@rushstack/webpack-preserve-dynamic-require-plugin": "0.11.66"
+    "@rushstack/webpack-preserve-dynamic-require-plugin": "0.11.66",
+    "@rushstack/ts-command-line": "4.22.8",
+    "local-node-rig": "1.0.0"
   },
   "scripts": {
     "build": "heft build --clean",