Module cache 

Image processing cache for incremental builds.

AVIF encoding is the bottleneck of the build pipeline — a single image at three responsive sizes can take several seconds through rav1e. This module lets the process stage skip encoding when the source image and encoding parameters haven’t changed since the last build.

Design

The cache targets only the expensive encoding operations (create_responsive_images and create_thumbnail). Everything else — dimension reads, IPTC metadata extraction, title/description resolution — always runs. This means metadata changes (e.g. updating an IPTC title in Lightroom) are picked up immediately without a cache bust.

Cache keys

Each output file (e.g. NY/001-Storm_1400.avif) is keyed by two values:

• source_hash: SHA-256 of the source file contents. Content-based rather than mtime-based so it survives git checkout (which resets modification times). Computed once per source file and shared across all its output variants.

• params_hash: SHA-256 of the encoding parameters. For responsive variants this includes (target width, quality). For thumbnails it includes (aspect ratio, short edge, quality, sharpening). If any config value changes, the params hash changes and the image is re-encoded.

A cache hit requires all four conditions:

1. Entry exists in the manifest
2. source_hash matches
3. params_hash matches
4. Output file exists on disk

Storage

The cache manifest is a JSON file at <output_dir>/.cache-manifest.json. It lives alongside the processed images so it travels with the output directory when cached in CI (e.g. actions/cache on dist/).

Bypassing the cache

Pass --no-cache to the build or process command to force a full rebuild. This loads an empty manifest, so every image is re-encoded. The old output files are overwritten naturally.

Structs

CacheEntry

A single cached output file.

CacheManifest

On-disk cache manifest mapping output paths to their cache entries.

CacheStats

Summary of cache performance for a build run.

Functions

hash_file

SHA-256 hash of a file’s contents, returned as a hex string.

hash_responsive_params

SHA-256 hash of encoding parameters for a responsive variant.

hash_thumbnail_params

SHA-256 hash of encoding parameters for a thumbnail.

manifest_path

Resolve the cache manifest path for an output directory.