fix(key): key env vars that steer proc-macro expansion (#635)

[jleni]

Fixes #635.

The problem

rustc records an env var in dep-info only when a crate reads it through env!/option_env!. A proc macro calling std::env::var while expanding leaves no trace at all: the rustc command line, the source hashes and the --extern set are byte-identical whether or not the var is set, while the emitted artifact is not. Both compiles key the same, and the second one restores the first one's expansion.

In the reported case a two-phase build ran the same crate graph twice, once with BOLTFFI_BINDING_EXPANSION=1 (where the #[export] macro strips itself from dependency crates and emits no trait impls) and once without. The dependency crate's invocation was identical in both phases, so the normal build restored the stripped 264 KiB artifact instead of building the 620 KiB one and failed with a missing trait impl. The same mechanism can just as easily produce a wrong binary that builds cleanly.

proc_macro::tracked_env would let a macro register these reads with the compiler and make this unnecessary, but it is still unstable, so the vars have to be declared.

The fix

[cache] key_env_vars / KACHE_KEY_ENV_VARS: a list of env var names to fold into every rustc and cc cache key. Entries are exact names or a trailing-* prefix glob, matched ASCII case-insensitively so a Windows environment behaves like a Unix one.

[cache]
key_env_vars = ["BOLTFFI_*"]

Two things are folded, and both are load-bearing:

• the declared patterns, so turning the feature on re-keys the crate. Without this the build that leaves the vars unset would fold nothing, land on its old key, and restore the very entry the declaration was meant to escape. By the time anyone reaches for this setting the poisoned entry is already in their cache.
• the matched NAME=VALUE pairs, sorted by name, which separates the two modes going forward.

Values are folded exactly, as their raw OS bytes — deliberately not through the PathNormalizer and not via a lossy UTF-8 conversion. A declared variable is an opaque semantic input: a macro may paste its value straight into the code it emits, so two checkout paths that collapse to the same <BASE_DIR> sentinel can still produce different artifacts. Normalizing them would reintroduce the wrong-hit this setting exists to prevent. This matches the policy env_dep_is_safe_to_normalize already applies to reported env! deps: normalize only where a value is proven to be nothing but a locator, which for a proc-macro read can never be proven. The cost is that a declared variable holding a machine-local path makes that crate's key machine-specific, so the docs steer toward declaring the switch a macro branches on rather than a glob that sweeps in path variables.

Properties:

• An empty list leaves keys byte-identical to the undeclared case, so no CACHE_KEY_VERSION bump and no cold cache for anyone who does not use it.
• Union-only: a misdeclared pattern can cost a cache miss, never restore a wrong artifact.
• Declaration spelling does not matter — the list is upper-cased, sorted and deduplicated before folding, so BOLTFFI_* and boltffi_* in either order share a cache. Matched pairs are sorted too, so vars_os order cannot leak into the key. The one exception is a process carrying the same name twice (only constructible via a hand-built envp): getenv returns the first occurrence, which makes the order semantically observable, so environ order is preserved in that case.
• Env var names are ASCII case-folded on Windows only, where PATH and Path are one variable. On Unix they are genuinely different variables and the case is kept.
• Only names are logged at trace level, never values: a declared var may legitimately hold a token.

Tests

tests/proc_macro_env_key_test.rs builds a real proc-macro dylib whose expansion depends on an env var, compiles a consumer through kache four times, and reads the marker back out of the compiled rlib. Hit/miss counts prove the key moved; reading the artifact proves kache stopped serving the wrong expansion.

Confirmed non-vacuous — with the declaration removed the test fails exactly as reported:

assertion `left == right` failed: normal build must not restore the expansion-mode artifact
  left: 1
 right: 2

Plus unit coverage for the matcher (exact/prefix/case/interior-*), the identity property when unconfigured, set-vs-unset-vs-empty separation, equivalent pattern spellings folding identically, distinct path values staying distinct, non-UTF-8 values staying distinct on unix, config env-vs-file precedence including the ignore_env lockdown, and the TUI save path preserving key_env_vars (it has no form field, so a dropped field would silently disable the setting).

Review notes

The first pass path-normalized declared values to keep them portable across machines. A cross-model review flagged that as unsound for the reason above, and the second commit replaces it with exact folding. The same review turned up the lossy-OsString collision, the Windows name-casing split, the pattern-case split, the duplicate-name ordering hole, and an interior-* warning that claimed such patterns "can never match" (they match a variable literally named A*B, which is legal on Unix). All are fixed in the second commit.

Docs

New Env vars that steer expansion section with the semantics and the sharp edges, a settings-table row, and cross-references from the cache-key page. The doc also points at cache.exclude for anyone who would rather not cache the affected crate at all.

What this does not do

The report also suggested a per-project crate denylist and a strict mode hashing the whole environment. The denylist is already covered by cache.exclude (source-path globs, documented in the new section). A strict whole-environment mode is deliberately left out: it would fold PWD, job ids and timestamps into every key and disable caching wholesale.