SwiftPM Manifest Caching#

Tuist's swifterpm module caches the JSON output of swift package dump-package to avoid re-invoking the Swift compiler on every tuist generate run. There are two stacked caching layers — a per-package cache managed by ManifestLoader and a cross-package indexed cache managed by PackageInfoCacheWriter — consumed by SwiftPackageManagerGraphLoader in the CLI.

Cache Layers and File Layout#

Layer 1 — ManifestLoader (per-package): Caches a single package's dump at .build/swifterpm/manifests/package.json inside each package directory. On the next call, dumpPackageJSON reads this file before shelling out to swift package dump-package.

Layer 2 — PackageInfoCacheWriter (cross-package index): Writes a shared index at .build/swifterpm/package-info/index.json 1 containing an entry for every resolved package. Individual package dumps are stored under packages/ with filenames derived from the package identity and a hash:

• Remote (source-control / registry) packages: {safeIdentity}-{entryHash}.json, where entryHash = SHA256(location:version:revision)[:16] 2
• Local (fileSystem) packages: {safeIdentity}-{pathHash}.json, where pathHash = SHA256(absolutePackagePath)[:16] 3

The index records a schema_version field: v1 stores absolute paths, v2 stores paths relative to the scratch directory for portability across hosts 4.

Freshness Check (Timestamp-Based)#

Both layers use the same strategy: compare the lastModificationDate of the cached JSON file against the lastModificationDate of Package.swift. If cacheDate >= manifestDate, the entry is considered fresh 5 6.

Special case: registry packages may not have a Package.swift on disk (the manifest is served remotely). When the file is absent, the entry is treated as always-fresh for entries of kind == "registry" 7.

The CLI's SwifterPMPackageInfoCache.load silently drops any entry that fails the freshness check, falling back to a full swift package dump-package invocation for that package 8.

Known Cache Invalidation Issues#

Environment-Sensitive Manifests#

swift package dump-package evaluates Package.swift at runtime, so environment variables like CI=true can alter the manifest's output without changing the file's mtime. A real incident illustrates the risk: stephencelis/CSQLite@3.53.3 had a manifest that conditionally appended a SwiftToolchainCSQLiteDynamic product referencing a non-existent target — but only when CI=true. Because the registry served a stale snapshot of the manifest, cold swift package resolve calls failed in Linux CI while local dev succeeded silently 9. The timestamp-based freshness check cannot distinguish outputs produced under different environments.

Workaround: Pin to a known-clean version (exact: "3.50.4") while a registry re-sync is arranged.

Path-Based Keys for Local Packages#

Local (fileSystem) dependency cache filenames are keyed on the absolute path of the package directory 10, not its content. Moving the project to a new directory — common in CI workspaces or git worktrees — produces a different hash, causing an unnecessary cache miss on every run. Issue #7659 tracks this and proposes switching to content-based hashing using ContentHasher.hash(path:), already used in Tuist's binary cache 11.

Silent Manifest Changes#

When a manifest's rendered output changes without any detectable file mutation — for example when a constant in a code generator is not bumped — neither the timestamp check nor the path hash will notice. Issue #11608 documented a production incident where this type of silent drift caused a reconciler to remain wedged for ~6 hours 12. The proposed fix across both contexts is to derive cache/revision keys from a content hash of the manifest inputs rather than metadata.

Improvement Directions#

Two themes emerge from the open issues:

1. Content-based hashing: Replace mtime and path comparisons with SHA256 hashes of Package.swift content for freshness checks, and hash the package directory tree (or at least Package.swift) instead of the absolute path for local-package filenames. A higher-level cache (SwiftPackageManagerGraphCache, added in PR #11760) already does this — it hashes workspace-state.json, root manifest content, local package fingerprints, Swift/Tuist versions, and environment variables as its composite cache key 13.

2. Dynamic input tracking: Capture the environment variables consumed during dump-package execution and include them in the cache key. This would prevent environment-sensitive manifests (like those guarded by CI=true) from being served stale cached output to a different environment.