tools/README.md describes each tool, the tiered loops of fast-check (tier 1 cargo check and
unit tests of the edited tree, tier 2 other-platform type-check or clippy, nix builds as the
pre-landing gate), the prerequisites (jj, nix develop, jq, flock) and how the fake C compiler
works for the macOS type-check. The measured warm times come from the host README and are dated
2026-10-31 (revision c89651fa). Personal progress-log and scratchpad references are removed.
docs/dev/build-and-test.md gets a "Developer tools" section and links to tools/ where it named
fast-check, kde-closure-check and the fake-CC command (the macOS block now says
`tools/mac-check.sh`).
Verified: links and commands read against the committed scripts; nothing else run.
Optional helpers for a shared host: trim-target deletes stale test executables from the
persistent cargo target dirs, gate-lock is a FIFO flock for heavy and timing-sensitive gates,
lite-env sources debug-info-off cargo settings. Copies of the host-side scripts with these
differences:
- trim-target: the default scratch dir is `${XDG_CACHE_HOME:-$HOME/.cache}/komorebi-fast-check`
(was a /tmp/claude-1000/... scratchpad path), the same as fast-check;
- gate-lock: GATE_LOCK_DIR defaults to `${XDG_STATE_HOME:-$HOME/.local/state}/komorebi-gate`
(was /home/jado/komomono-work/.gate), in the header and in the code;
- gate-lock: "/proc/$pid/cmdline" is quoted and a shellcheck directive disables SC2012 and
SC2016 (ls of plain queue ticket names, and a bash -c script expanding its own $1);
- lite-env: a `# shellcheck shell=bash` first line.
Not committed: mini (host and credential specific), host-sample and jitter-probe (host
measurement), the .bak files.
Verified: bash -n and shellcheck clean. Not run: gate-lock was tested by its author with a scratch
GATE_LOCK_DIR before this change; the default path change is untested.
kde-closure-check fails when komorebi-for-kde/nix/root-crates.json differs from the KDE cargo
closure; e2e-needed says whether a diff touches anything the Windows e2e binaries are built
from. Copies of the host-side scripts with these differences only:
- kde-closure-check: none (it already finds the repository relative to the script); verbatim.
- e2e-needed: `tools/*` joins the paths that cannot change the binaries (docs, .github), so a
change to the tools is NO instead of "not understood: treated as needed";
- e2e-needed: `# shellcheck disable=SC2001` before `set` (the sed one-liners indent multi-line
output); no behaviour change.
Verified: bash -n and shellcheck clean; `tools/kde-closure-check .` prints "ok: 11 root crates
match the KDE cargo closure"; `tools/e2e-needed --since <rev>` gives the same output as the host
copy on a range without tools/ files, and NO for a tools-only range.
Runs only the checks a jj diff needs (KDE cargo check and tests, macOS type-check, Windows
clippy through the nix dev shell, native crate tests, nix evaluation only) with persistent
target dirs, and prints the time of each. Copy of the host-side script (the original stays
in use outside the repository) with these differences:
- FAST_CHECK_SCRATCH defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/komorebi-fast-check`
instead of a /tmp/claude-1000/... scratchpad path (usage text updated);
- the fake C compiler is `$HERE/cc-fake.sh` (the script directory, resolved with readlink -f)
instead of `$S/kfm/cc-fake.sh`;
- `tools/*` is classified like docs (no check), so a change to the tools alone prints
"nothing to run" instead of listing every file as unclassified;
- the second `case` arm lost the patterns `Cargo.toml | Cargo.lock | .cargo/*`, which an earlier
arm already catches (shellcheck SC2221/SC2222; no change in behaviour);
- header comment: "from anywhere inside a jj workspace of the repository", no mention of komomono.
Everything else is byte-identical (diff against the host copy).
Verified: bash -n and shellcheck clean; `tools/fast-check --list` from this workspace.
macOS cannot be built or linked on the Linux host; the way to type-check it is
`cargo check --target aarch64-apple-darwin --all-targets` with a fake C compiler so the
C -sys crates' build scripts succeed. That compiler was only a scratchpad file outside the
repository and mac-check.sh hardcoded a workspace path.
tools/cc-fake.sh: verbatim copy of the scratchpad cc-fake.sh (emits an empty object for
every compile, hands -E to the real gcc). No difference.
tools/mac-check.sh: new copy of the old script with these differences:
- no hardcoded `cd /home/jado/komomono-work/ws-step4/komorebi-for-mac`: the root comes from
`jj root` (fallback `git rev-parse --show-toplevel`);
- the fake CC is `$HERE/cc-fake.sh` (next to the script) instead of `$S/kfm/cc-fake.sh`;
- the target dir is `${FAST_CHECK_SCRATCH:-${XDG_CACHE_HOME:-$HOME/.cache}/komorebi-fast-check}/target-fast-mac`
instead of a /tmp/claude-1000 scratchpad;
- in the merged tree (komorebi-for-kde has its own Cargo.toml only in the old layout) it checks the
packages fast-check checks (-p komorebi -p komorebi-macos -p komorebic-macos
-p komorebi-client-macos -p komorebi-bar-macos) from the root; with the old separate workspace it
keeps `cd komorebi-for-mac` and --workspace;
- /bin/sh became bash with `set -euo pipefail`; the old script's omission of --locked is kept
(pass it as an extra argument).
Verified: bash -n and shellcheck clean. Not run: the check itself needs nix and the toolchain build.