feat(toolkit/cache): add compression level support

[StephenHodgson]

• Added compression level support end-to-end: option plumbed through options/cache/cacheHttpClient/tar so tar creation sets gzip/zstd env and upload options carry the level.
• Expanded tests: updated saveCache/saveCacheV2 expectations for new parameter, added size-driven compression tests in tar suite, adjusted options tests for clamping/overrides, and kept tar tests prettier-compliant.
• Docs: refreshed cache README to describe compression-level behavior and defaults.
• closes Allow caching without compression #1535
• closes [Feature request] Allow configuration of zstd compression level #2050
• blocks add compression-level input for save step cache#1689

[Copilot]

Pull request overview

This PR adds configurable compression level support to the @actions/cache package, allowing users to control the trade-off between compression time and archive size when saving caches. The feature is implemented end-to-end from the API options through to the underlying tar compression commands.

Key changes:

• Added compressionLevel parameter (0-9, default 6) to UploadOptions with environment variable override support via CACHE_COMPRESSION_LEVEL
• Integrated compression level throughout the tar creation pipeline by setting appropriate environment variables (GZIP, ZSTD_CLEVEL) and command-line flags for both gzip and zstd compression methods
• Fixed several spelling errors in comments and documentation

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/cache/src/options.ts	Added compressionLevel field to UploadOptions interface with validation logic that clamps values to 0-9 range and supports environment variable override
packages/cache/src/internal/tar.ts	Extended createTar and related functions to accept and apply compression level via command-line flags and environment variables; fixed typo in comment
packages/cache/src/internal/cacheHttpClient.ts	Fixed spelling errors in comments ("achiveLocation" → "archiveLocation", "Commiting" → "Committing")
packages/cache/src/cache.ts	Updated saveCacheV1 and saveCacheV2 to pass compression level from upload options to createTar; fixed typo in comment
packages/cache/tests/tar.test.ts	Updated test expectations to include compression level in command-line flags and environment variables; added new tests verifying compression level affects archive size; modernized fs import
packages/cache/tests/saveCacheV2.test.ts	Updated all test expectations to include default compressionLevel: 6 in upload options and as parameter to createTar
packages/cache/tests/saveCache.test.ts	Updated test expectations to include compression level parameter and verify proper options object is passed to saveCache
packages/cache/tests/options.test.ts	Added tests for compression level defaults, overrides, clamping, and environment variable behavior; added cleanup in afterEach
packages/cache/README.md	Updated documentation to describe compression level feature with usage example; fixed typo ("succesfully" → "successfully")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated no new comments.

Files not reviewed (2)

• packages/artifact/package-lock.json: Language not supported
• packages/cache/package-lock.json: Language not supported

Comments suppressed due to low confidence (1)

packages/cache/src/internal/tar.ts:244

• The BSD_TAR_ZSTD check should explicitly check for zstd compression methods only. With the addition of CompressionMethod.Tar, the condition compressionMethod !== CompressionMethod.Gzip will incorrectly evaluate to true for Tar compression, potentially causing BSD tar to be invoked with zstd-specific flags for uncompressed tar archives.

The condition should be changed to explicitly check for zstd methods:
(compressionMethod === CompressionMethod.Zstd || compressionMethod === CompressionMethod.ZstdWithoutLong)

This matches the pattern used elsewhere in the file (lines 75-78, 161-165, 195-199).

  const BSD_TAR_ZSTD =
    tarPath.type === ArchiveToolType.BSD &&
    compressionMethod !== CompressionMethod.Gzip &&
    IS_WINDOWS

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated no new comments.

Files not reviewed (2)

• packages/artifact/package-lock.json: Language not supported
• packages/cache/package-lock.json: Language not supported

Comments suppressed due to low confidence (1)

packages/cache/src/internal/tar.ts:246

• The BSD_TAR_ZSTD condition check is inconsistent with the rest of the file. This should check for specific Zstd compression methods like in getTarArgs (lines 74-78) and getCommands (lines 161-165):

(compressionMethod === CompressionMethod.Zstd ||
 compressionMethod === CompressionMethod.ZstdWithoutLong)

The current logic compressionMethod !== CompressionMethod.Gzip would incorrectly match the new CompressionMethod.Tar case, potentially causing issues with the BSD tar handling logic for uncompressed tar files.

  const BSD_TAR_ZSTD =
    tarPath.type === ArchiveToolType.BSD &&
    compressionMethod !== CompressionMethod.Gzip &&
    IS_WINDOWS

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[planetmarshall]

#1877 Implements similar functionality

[StephenHodgson]

@planetmarshall similar but not the same.