tools: add a guarded Zig-cache inspection/cleanup tool + docs (#53)

Repeated focused test builds relink the root test artifact under distinct
cache keys, and the repo-local `.zig-cache` has reached ~92 GB, tripping
LLVM `No space left on device`. Everything in `.zig-cache`/`zig-out` is
reproducible, so add a safe way to inspect and reclaim it.

`tools/zig-cache-tool.sh`:
  - `report` (default): total + per-subdir sizes, largest o/ artifacts, and
    the reclaimable total.
  - `prune [--dry-run] [--all]`: remove the reproducible bulk (o/, tmp/,
    zig-out; +h/ z/ with --all).

It accepts NO path arguments — every target is a fixed repository-relative
directory — and before each removal it resolves the target through symlinks
and refuses anything not inside `<repo>/.zig-cache` or `<repo>/zig-out`
(path-traversal like `.zig-cache/../src` is rejected). It finds the repo
from its own location via `git rev-parse`, so it never acts elsewhere.

Adds `docs/dev-cache.md` explaining inspection and safe cleanup, linked
from the baseline-JIT dev doc. Covers issue #53 acceptance criteria for the
documented, guarded cache-cleanup path; the focused per-module test
artifacts (criteria 1-3) intersect the active build.zig/JIT restructuring
and are left to that work.

Author: glennmichael123

docs/baseline-jit.md

@@ -161,3 +161,6 @@ Performance evidence uses the symmetric JSC protocol in
 the 1,232-sample publication matrix is rerun only after a meaningful batch of
 optimizations. A speedup is not accepted if checksums, supported rows, or
 execution accounting differ.
+
+Repeated focused test builds grow the reproducible `.zig-cache` quickly; see
+[`dev-cache.md`](dev-cache.md) for inspecting and safely reclaiming it.

docs/dev-cache.md

@@ -0,0 +1,65 @@
+# Inspecting and cleaning the Zig build cache
+
+Zig writes all build output into two repository-local directories:
+
+| Path          | Contents                                                        |
+| ------------- | --------------------------------------------------------------- |
+| `.zig-cache/` | compiled objects (`o/`), scratch (`tmp/`), hashes (`h/`, `z/`)  |
+| `zig-out/`    | installed artifacts (`zig build` `install` step outputs)        |
+
+**Everything in both directories is reproducible** — deleting them only forces
+the next build to recompile. Neither ever contains source or user-owned files.
+
+## Why it grows without bound
+
+Each distinct build configuration produces a distinct cache key and a fresh copy
+of the artifact. Repeated *focused* test runs are the usual culprit: a filtered
+build such as
+
+```sh
+zig build test -Dtest-filter=vm    # then ...=jit, ...=compiler, ...
+```
+
+relinks the whole root test binary under a new key for every filter string, so a
+day of baseline-JIT development can leave dozens of multi-hundred-MB artifacts
+behind. In practice `.zig-cache` has reached **~92 GB**, at which point LLVM
+fails with `No space left on device`. Clearing the reproducible cache recovers
+all of it.
+
+## Inspect
+
+```sh
+tools/zig-cache-tool.sh report        # (default) sizes, per-subdir breakdown,
+                                      # largest o/ artifacts, reclaimable total
+```
+
+## Clean
+
+```sh
+tools/zig-cache-tool.sh prune --dry-run   # preview exactly what would be removed
+tools/zig-cache-tool.sh prune             # remove .zig-cache/o, .zig-cache/tmp, zig-out
+tools/zig-cache-tool.sh prune --all       # additionally drop h/ and z/ (fully cold rebuild)
+```
+
+`prune` removes only the reproducible bulk (compiled objects, scratch, and the
+install tree) and keeps the small hash/manifest dirs so the next build can still
+reuse unchanged inputs; `--all` forces a completely cold rebuild.
+
+## Safety
+
+The tool is deliberately conservative and is the recommended way to clean the
+cache:
+
+- It accepts **no path arguments** — every target is a fixed repository-relative
+  directory (`.zig-cache/o`, `.zig-cache/tmp`, `.zig-cache/h`, `.zig-cache/z`,
+  `zig-out`), so there is no way to point it at anything else.
+- Before each removal it resolves the target through symlinks and refuses to
+  proceed unless the result is inside `<repo>/.zig-cache` or `<repo>/zig-out`.
+  Path-traversal attempts (e.g. a symlinked cache pointing outside the repo)
+  are rejected rather than followed.
+- It locates the repository from its own location via `git rev-parse`, so it
+  never acts on an unrelated directory even if run from elsewhere.
+
+The manual equivalent is `rm -rf .zig-cache zig-out` from the repo root, but the
+tool adds the reporting and the outside-the-repo guard, and never leaves the
+hash dirs in an inconsistent partial state.

tools/zig-cache-tool.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+#
+# zig-cache-tool.sh — inspect and safely prune the repository-local Zig caches.
+#
+# During baseline-JIT development, repeated focused `zig build ... -Dtest-filter`
+# runs relink the monolithic test artifact under distinct cache keys and the
+# repo-local `.zig-cache` has grown to ~92 GB, tripping LLVM `No space left on
+# device`. This tool reports what those reproducible caches hold and prunes them
+# without ever being able to touch source or user-owned files (issue #53).
+#
+# Usage:
+#   tools/zig-cache-tool.sh report            # (default) sizes + largest entries
+#   tools/zig-cache-tool.sh prune [--dry-run] # remove the reproducible cache (o/ tmp/) + zig-out
+#   tools/zig-cache-tool.sh prune --all [...]  # also remove h/ and z/ (hashes/manifests)
+#
+# Only ever operates on <repo>/.zig-cache and <repo>/zig-out — both are fully
+# reproducible from a build. It refuses any path that, after symlink resolution,
+# is not inside those two directories.
+
+set -euo pipefail
+
+# --- Locate the repository, whatever CWD the tool is invoked from. ------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+  echo "error: not inside a git repository (run from the zig-js checkout)" >&2
+  exit 1
+fi
+CACHE_DIR="$REPO_ROOT/.zig-cache"
+OUT_DIR="$REPO_ROOT/zig-out"
+
+# --- Safety guard: refuse anything outside the two reproducible output dirs. --
+# Resolves the target's parent through symlinks (the target itself may not
+# exist), then requires the absolute result to be exactly, or a child of,
+# CACHE_DIR or OUT_DIR. This is the hard boundary for issue #53's rule that no
+# cleanup can target paths outside the repository cache/build outputs.
+assert_within_outputs() {
+  local target="$1" parent base resolved
+  parent="$(dirname "$target")"
+  base="$(basename "$target")"
+  if ! resolved="$(cd "$parent" 2>/dev/null && printf '%s/%s' "$(pwd -P)" "$base")"; then
+    echo "refusing: cannot resolve '$target'" >&2
+    return 1
+  fi
+  case "$resolved" in
+    "$CACHE_DIR" | "$CACHE_DIR"/* | "$OUT_DIR" | "$OUT_DIR"/*) return 0 ;;
+    *)
+      echo "refusing to touch a path outside the repo cache/build outputs:" >&2
+      echo "  $resolved" >&2
+      return 1
+      ;;
+  esac
+}
+
+human_size() {
+  # Total apparent size of the arguments that exist, as a human string.
+  local existing=()
+  for p in "$@"; do [ -e "$p" ] && existing+=("$p"); done
+  if [ ${#existing[@]} -eq 0 ]; then
+    echo "0B"
+  else
+    du -sh -c "${existing[@]}" 2>/dev/null | tail -1 | cut -f1
+  fi
+}
+
+cmd_report() {
+  echo "repository: $REPO_ROOT"
+  echo
+  if [ -d "$CACHE_DIR" ]; then
+    echo ".zig-cache total: $(human_size "$CACHE_DIR")"
+    for sub in o tmp h z; do
+      [ -d "$CACHE_DIR/$sub" ] && printf '  %-4s %s\n' "$sub/" "$(human_size "$CACHE_DIR/$sub")"
+    done
+    if [ -d "$CACHE_DIR/o" ]; then
+      echo
+      echo "  largest o/ artifacts (compiled test/exe outputs — the reproducible bulk):"
+      du -sh "$CACHE_DIR"/o/* 2>/dev/null | sort -rh | head -8 | sed 's/^/    /'
+    fi
+  else
+    echo ".zig-cache: (none)"
+  fi
+  echo
+  if [ -d "$OUT_DIR" ]; then
+    echo "zig-out total: $(human_size "$OUT_DIR")"
+  else
+    echo "zig-out: (none)"
+  fi
+  echo
+  echo "reclaimable now: $(human_size "$CACHE_DIR/o" "$CACHE_DIR/tmp" "$OUT_DIR")"
+  echo "run 'tools/zig-cache-tool.sh prune' to reclaim it."
+}
+
+cmd_prune() {
+  local dry_run=0 all=0
+  for arg in "$@"; do
+    case "$arg" in
+      --dry-run) dry_run=1 ;;
+      --all) all=1 ;;
+      *) echo "unknown prune option: $arg" >&2; exit 2 ;;
+    esac
+  done
+
+  # The reproducible bulk: compiled outputs (o/), scratch (tmp/), and zig-out.
+  # --all additionally drops the small hash (h/) and manifest (z/) dirs, forcing
+  # a fully cold rebuild.
+  local targets=("$CACHE_DIR/o" "$CACHE_DIR/tmp" "$OUT_DIR")
+  if [ "$all" -eq 1 ]; then
+    targets+=("$CACHE_DIR/h" "$CACHE_DIR/z")
+  fi
+
+  local reclaim
+  reclaim="$(human_size "${targets[@]}")"
+  echo "would reclaim: $reclaim"
+
+  for t in "${targets[@]}"; do
+    assert_within_outputs "$t" || exit 1
+    if [ ! -e "$t" ]; then
+      continue
+    fi
+    if [ "$dry_run" -eq 1 ]; then
+      echo "  [dry-run] rm -rf $t"
+    else
+      echo "  removing $t"
+      rm -rf -- "$t"
+    fi
+  done
+
+  if [ "$dry_run" -eq 1 ]; then
+    echo "dry run: nothing was deleted."
+  else
+    echo "done. reclaimed ~$reclaim (rebuilds are fully reproducible)."
+  fi
+}
+
+case "${1:-report}" in
+  report) cmd_report ;;
+  prune) shift; cmd_prune "$@" ;;
+  -h | --help | help)
+    sed -n '2,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    ;;
+  *)
+    echo "unknown command: $1 (expected: report | prune | help)" >&2
+    exit 2
+    ;;
+esac