[rush] Add experiment to omit macOS AppleDouble files from build cache

[iclanton]

Summary

When Rush builds run on macOS, AppleDouble metadata files (._*) can end up in build output folders and get uploaded to the shared build cache. These platform-specific files serve no purpose for build consumers and pollute the cache. This PR adds a new omitAppleDoubleFilesFromBuildCache experiment that filters these files out during cache archive creation.

Details

AppleDouble files (e.g. ._foo.js alongside foo.js) are automatically created by macOS to store extended attributes on filesystems that don't support them. They can appear in build output folders, particularly when output directories are on network shares or external volumes.

The filtering logic:

• Only activates when the experiment is enabled and process.platform === 'darwin'
• Only omits ._X files when a companion file X exists in the same directory, to avoid filtering files that legitimately start with ._
• Builds a Set<string> of sibling names per directory for efficient companion lookup
• Logs each omitted file at verbose level

The process.platform check is evaluated once in the OperationBuildCache constructor rather than per-file. Since this is a behavior change, it is gated behind an experiment flag.

No backwards compatibility concerns -- old cache entries with ._ files still restore fine, and the experiment must be explicitly opted into.

How it was tested

Added 6 unit tests covering:

• AppleDouble files with companions are omitted when enabled on macOS
• AppleDouble files without companions are preserved
• Filtering is disabled when the experiment is off
• Filtering is disabled on non-macOS platforms
• Edge case: files named exactly ._ (length 2) are not filtered
• Filtering works correctly in nested subdirectories

Build and all existing tests pass.

Impacted documentation

https://rushjs.io/pages/configs/experiments_json/#docusaurus_skipToContent_fallback

[Copilot]

Pull request overview

Adds a new Rush experiment to prevent macOS AppleDouble metadata files (._*) from being included in build cache archives, reducing cache pollution for cross-platform consumers.

Changes:

• Introduces omitAppleDoubleFilesFromBuildCache experiment (schema + typed config surface).
• Plumbs an internal filterAppleDoubleFiles option through cache-related plugins into OperationBuildCache.
• Implements and unit-tests AppleDouble filtering logic during cache archive file collection (macOS-only, companion-file guarded).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
rush-plugins/rush-bridge-cache-plugin/src/BridgeCachePlugin.ts	Passes the experiment-driven AppleDouble filter flag into cache operations performed by the bridge cache plugin.
libraries/rush-lib/src/schemas/experiments.schema.json	Adds the new experiment to the JSON schema.
libraries/rush-lib/src/logic/operations/CacheableOperationPlugin.ts	Threads the new filter flag through build cache creation paths.
libraries/rush-lib/src/logic/buildCache/test/OperationBuildCache.test.ts	Adds unit tests covering AppleDouble filtering behavior and edge cases.
libraries/rush-lib/src/logic/buildCache/OperationBuildCache.ts	Implements AppleDouble filtering during output path collection for cache archives (macOS-only, companion-file check).
libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts	Reads the experiment and passes it into the cacheable operation plugin options.
libraries/rush-lib/src/api/ExperimentsConfiguration.ts	Extends IExperimentsJson with the new experiment flag (typed surface).
libraries/rush-lib/assets/rush-init/common/config/rush/experiments.json	Adds the experiment to the rush-init template file.
common/reviews/api/rush-lib.api.md	Updates API review file for the new experiment flag and internal option surface.
common/changes/@microsoft/rush/omit-apple-doubles-from-cache_2026-02-16-05-38.json	Adds the Rush change file describing the experiment.