Module touch_cache 

On-disk cache for per-function git touch metrics.

Cache key: "{sha}:{file}:{start}:{end}" where file is a repo-relative path and start/end are 1-based line numbers. Value: (touch_count_30d, days_since_last_change).

Line range shift behavior: If surrounding code changes and a function’s line range moves, the cache key will not match (start/end differ) — it is a miss. This is correct: the function’s git history in its new position must be re-queried. An unchanged function in an unchanged file hits the parent commit’s cache entry exactly. Do not “fix” this with content hashing — the miss behavior is intentional.

Eviction: After writing, entries whose SHA prefix is not in the provided set are dropped. At most MAX_CACHED_SHAS distinct SHAs are retained to bound file size.

Warm-run speedup (SQ-1d benchmark, hyperfine, this repo, ~200 functions): cold run 6.2 s ± 0.02 s (one git log -L subprocess per function) warm run 230 ms ± 3 ms (all cache hits — no subprocesses) file-level 268 ms ± 3 ms (batched git log per file) Warm is ~27× faster than cold and ~15% faster than file-level. Target was warm ≤ 2× file-level; this repo achieves 0.86× (warm per-function beats file-level).

Functions

cache_key

Build a cache lookup key from its components.

evict_old_entries

Evict cache entries whose SHA is not among known_shas.

read_touch_cache

Load the touch cache from disk.

write_touch_cache

Write the touch cache to disk (zstd level 3).

Type Aliases

TouchCache

In-memory touch cache: maps key to (touch_count_30d, days_since_last_change).