address code review feedback: improve type annotations and JSDoc

Agent-Logs-Url: https://github.com/microsoft/rushstack/sessions/050e10a7-3cad-4da4-93e5-9941453283b9

Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>

Author: Copilot

libraries/rush-lib/src/logic/buildCache/ICloudBuildCacheProvider.ts

@@ -24,6 +24,11 @@ export interface ICloudBuildCacheProvider {
    * If implemented, the build cache will prefer to use this method over
    * {@link ICloudBuildCacheProvider.trySetCacheEntryBufferAsync} to avoid loading the entire
    * cache entry into memory.
+   *
+   * @remarks
+   * Because the provided stream can only be consumed once, implementations should not
+   * attempt to retry the upload using the same stream. If retry logic is needed,
+   * consider buffering internally or returning `false` so the caller can retry.
    */
   trySetCacheEntryStreamAsync?(
     terminal: ITerminal,

libraries/rush-lib/src/logic/buildCache/OperationBuildCache.ts

@@ -3,7 +3,7 @@
 
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { createReadStream } from 'node:fs';
+import { type ReadStream, createReadStream } from 'node:fs';
 import type { Readable } from 'node:stream';
 
 import { FileSystem, type FolderItem, InternalError, Async } from '@rushstack/node-core-library';
@@ -333,7 +333,7 @@ export class OperationBuildCache {
 
       if (this._cloudBuildCacheProvider.trySetCacheEntryStreamAsync) {
         // Use streaming upload to avoid loading the entire cache entry into memory
-        const entryStream: import('node:fs').ReadStream = createReadStream(localCacheEntryPath);
+        const entryStream: ReadStream = createReadStream(localCacheEntryPath);
         setCloudCacheEntryPromise = this._cloudBuildCacheProvider.trySetCacheEntryStreamAsync(
           terminal,
           cacheId,

libraries/rush-lib/src/utilities/WebClient.ts

@@ -299,7 +299,8 @@ function _sendRequestBody(
   body: Buffer | Readable | undefined,
   reject: (error: Error) => void
 ): void {
-  if (body && typeof (body as Readable).pipe === 'function') {
+  const isStream: boolean = !!body && typeof (body as Readable).pipe === 'function';
+  if (isStream) {
     (body as Readable).on('error', reject);
     (body as Readable).pipe(req);
   } else {