mirror of
https://github.com/kuhyx/testsAndMisc.git
synced 2026-11-21 19:02:19 +01:00
Confirmed live (not dead code) via the dead-code check-in before any code
was touched -- the last two candidates this pattern was tried on were both
archived instead. Kept run_one/cleanup/log_size/main together in the entry
script: a prior session (2527fb3) already proved splitting run_one out
produces a real SC2153/SC2034 pair since PACMAN_PID/LAST_ELAPSED cross the
EXIT trap, not a suppressible false positive.
Fixed a real bug found while writing tests: print_summary's inline awk had
a dead `NR == 0` guard (printf on an empty array still emits one blank
line), reachable via `-n 0`. Refactored mem_available_mb, descendant_pids/
kill_tree, capture_stall's two output blocks, and print_summary's median
calc after confirming empirically (bash -x tracing) that kcov's
xtrace-based coverage can never see a `done <redirect>`, `} >redirect`, or
inline-awk line -- user chose to fix the code over the coverage tool.
descendant_pids specifically needed an explicit-fd process substitution
(not a pipe) to keep its array mutation in the current shell.
Made PACMAN_BIN/PACMAN_LOG/CACHE_DIR/PACMAN_LOCK/LOAD_FLOOR_MB/
LOAD_MIN_FREE_MB env-overridable for testing. Caught and fixed, before it
ran unbounded, a --with-load test that would have dd'd 13-20+ GB into
/dev/shm using this box's real available memory.
56 lib-level + 13 entry-level PATH-shim/subprocess assertions, 0 failed.
The entry test itself grew past 250 lines while adding coverage and had to
be split into a shared harness plus two test files, mid-session.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
271 lines
15 KiB
Markdown
271 lines
15 KiB
Markdown
# Next session: §3's next restructure — setup_hosts_guard.sh
|
|
|
|
> **Paste this whole file into a fresh Claude session opened in `~/testsAndMisc`.**
|
|
> It is self-contained. Do not go looking for the previous session's context.
|
|
|
|
Over-cap: **12** (11 shell, 2 kotlin, 1 dart). Working tree clean, `main` in
|
|
sync as of the diagnose_pacman_hook_stall.sh split commit (see §0.5).
|
|
|
|
Two standing decisions from the user, already made — do **not** re-litigate:
|
|
|
|
1. **100% line coverage on what you extract** — same bar every session so far
|
|
has applied.
|
|
2. **Split blind where there is no device.** Do not deploy to the phone, do
|
|
not ask to. Prove splits with tests, hashes and real runs instead.
|
|
|
|
---
|
|
|
|
## 0. What just happened (read this, don't repeat it)
|
|
|
|
Two sessions ago: `install_plagiarism_tools.sh` was split (534→94 lines +
|
|
3 libs, 100% coverage) — then the user said they no longer use the
|
|
plagiarism tools at all, so the whole thing was archived to
|
|
`kuhyx/testsAndMisc-archive` with full git history via `git filter-repo`.
|
|
One session ago: the same one-line "do you still use this?" check-in was
|
|
asked about `libre_translate.sh` _before_ any code was touched, and got the
|
|
same answer — also archived, not split.
|
|
|
|
**Lesson (2 for 2, now reinforced a third way):** keep asking the check-in
|
|
before every future §3/§4 split. It is not a formality; it has changed scope
|
|
in both of the two times it's been tried.
|
|
|
|
## 0.5. What just happened (this session) — diagnose_pacman_hook_stall.sh split, confirmed live
|
|
|
|
Asked the dead-code check-in first, per §0's lesson. User confirmed this
|
|
script **is** still in active use (unlike the last two candidates) — so the
|
|
split proceeded as originally planned. 493 lines → 249 (entry) + 6 libs
|
|
(pacman_hook_stall_setup.sh, _load.sh, _capture.sh, _watch.sh, _usage.sh,
|
|
_summary.sh), all at 100% line coverage, plus a PATH-shim test suite (56
|
|
lib-level + 13 entry-level subprocess assertions, 0 failed).
|
|
|
|
**Two things worth knowing before touching this area again:**
|
|
|
|
1. `run_one`/`cleanup`/`log_size`/`main` had to stay together in the entry
|
|
script — they share `PACMAN_PID`/`LAST_ELAPSED` across the `EXIT` trap,
|
|
and a prior session (commit `2527fb3`) already proved that splitting
|
|
`run_one` into a lib produces a **real** SC2153/SC2034 pair (not a
|
|
suppressible false positive), because a sourced lib has no way to declare
|
|
where its globals come from. If a future split looks like it wants to
|
|
move a function that both writes a global the entry script reads AND
|
|
reads a global only the entry script sets, do the same scratch
|
|
shellcheck-dry-run check (with `.shellcheckrc`'s `external-sources=true` /
|
|
`source-path=SCRIPTDIR`, which is what the real hook uses) **before**
|
|
committing to a lib boundary, not after.
|
|
2. **kcov cannot see `done <redirect>`, `} >redirect`, or lines inside an
|
|
inline awk script**, no matter how thoroughly the code executes (verified
|
|
empirically with `bash -x` on isolated repros — those lines never emit a
|
|
trace event). If a coverage gap on a future file's line list looks
|
|
suspiciously like a loop-closing or group-closing line, or an awk block,
|
|
check whether it's this exact class before assuming the test is weak. The
|
|
user was asked and chose "refactor the code" over "fix the coverage
|
|
tool" — that decision holds for this repo going forward unless
|
|
re-raised.
|
|
3. **Test files are not exempt from the 250-line cap.** The entry-script
|
|
subprocess test grew to 295 lines while adding coverage and had to be
|
|
split itself, mid-session, after `check_file_length.sh --all` caught it.
|
|
Budget for this: a test file that drives real subprocess timing (unshare,
|
|
real sleep, multiple flag combinations) grows fast — split its fixture
|
|
setup into a shared harness early rather than after it's already over.
|
|
4. Evidence + contract:
|
|
`docs/superpowers/evidence/split-diagnose-pacman-hook-stall-2026-08-18.json`
|
|
and the matching `contracts/` file are the current format reference —
|
|
more detailed than the plagiarism-tools pair since this split involved
|
|
several genuine (not mechanical) function rewrites, all individually
|
|
justified there.
|
|
|
|
## 1. This session's task: `setup_hosts_guard.sh`
|
|
|
|
Location:
|
|
`linux_configuration/scripts/periodic_background/hosts/guard/setup_hosts_guard.sh`
|
|
(576 lines).
|
|
|
|
**Ask the dead-code check-in first** (see §0.5) — the streak is 2-for-3 so
|
|
far (2 archived, 1 confirmed live); don't assume either outcome.
|
|
|
|
**Before you start**, confirm scope hasn't drifted: `git status --short` and
|
|
`wc -l` on the target file, and re-run
|
|
`bash meta/scripts/check_file_length.sh --all` to get the current exact
|
|
list — files change size between sessions, and this file's line count may
|
|
not still be 576.
|
|
|
|
Check what this file references before planning a split boundary —
|
|
`hosts_guard_migrate.sh`/`hosts_guard_rollback.sh` already exist as siblings
|
|
in `linux_configuration/scripts/single_use/fixes/lib/`, and
|
|
`fixes/migrate_hosts_guard_to_guard_lib.sh` is the entry script that
|
|
migrated _to_ this guard-lib system. Read that migration script's header
|
|
comment first — it explains what guard-lib actually does and may reveal
|
|
whether `setup_hosts_guard.sh` itself is now redundant with the migrated
|
|
state, which is exactly the kind of thing the dead-code check-in is for.
|
|
|
|
## 3. §4 — do not touch this session
|
|
|
|
`install_leechblock.sh` (485) and `block_compulsive_opening.sh` (705) are
|
|
copied to `/usr/local/…`, and `pacman_wrapper.sh:831` prefers the deployed
|
|
copy on **every pacman invocation**. Splitting them naively breaks every
|
|
`pacman -S` on this machine. Out of scope until `setup_hosts_guard.sh` is
|
|
done (or archived) and the user explicitly says to continue into §4.
|
|
|
|
You cannot run `sudo pacman -S` from the Bash tool — it deadlocks on
|
|
`db.lck`. Hand the user a `! sudo pacman -S <pkg>` line plus the expected
|
|
output if `pacman_wrapper.sh` ever needs live verification.
|
|
|
|
## 4. Out of scope until the user says otherwise
|
|
|
|
`setup_midnight_shutdown.sh` (1734), `check_and_enable_services.sh` (1301),
|
|
`generate_study_materials.sh` (1017), `pacman_wrapper.sh` (929),
|
|
`setup_night_lockdown.sh` (918), `hosts/install.sh` (912),
|
|
`EnforcementRunner.kt` (564), `DevicePolicyBridge.kt` (415),
|
|
`status_page_state.dart` (307) — check `check_file_length.sh --all` for the
|
|
current exact list before assuming this is still accurate, since files
|
|
change size between sessions.
|
|
|
|
`pacman_wrapper.sh` carries the same live-deployment trap as §3/§4. The
|
|
Kotlin and Dart files need a different verification stack — `focus_owner`
|
|
gradle needs `JAVA_HOME=/usr/lib/jvm/java-21-openjdk` and `--rerun-tasks`; a
|
|
plain `gradlew test` reports `UP-TO-DATE` and proves nothing.
|
|
|
|
## 5. Rules that will bite you (carried forward, still true)
|
|
|
|
- **Ask before large scope changes.** Two of the last three sessions turned
|
|
into archive-and-delete mid-session because the user volunteered new
|
|
information partway through (or, this session, confirmed the file WAS
|
|
still live). That is fine and expected — just don't assume silence means
|
|
"keep going as originally scoped" if something about the target file's
|
|
relevance seems worth a quick check.
|
|
- **No suppressions, ever.** No `# noqa`, no per-file-ignore added without
|
|
asking every time, no shellcheck disable beyond what's already justified
|
|
inline. If a coverage or lint finding looks like it fundamentally
|
|
conflicts with the file's purpose, ask before working around it — this
|
|
session's kcov-blind-spot finding (§0.5.2) is the exact pattern: verify
|
|
the finding is real (bash -x trace check) before assuming it's a tool
|
|
limitation to route around vs. a real behavioral gap to test.
|
|
- **A file must not assign a global it never reads** (SC2034). The hook runs
|
|
`shellcheck` with **no `-x`**, but `.shellcheckrc`'s
|
|
`external-sources=true` + `source-path=SCRIPTDIR` means a `source=`
|
|
annotation on the _sourcing_ file still resolves correctly — the failure
|
|
mode that actually breaks is a _lib_ file trying to reference a global
|
|
only the entry script sets, since a lib has no annotation pointing
|
|
"upward" to whoever sources it. Constants travel with their readers; a
|
|
global genuinely written on both sides of a seam stays in the entry
|
|
script.
|
|
- **New sourced libs need a shebang AND the executable bit**, even though
|
|
they're sourced, not executed — `lib/hosts_guard_migrate.sh` and this
|
|
session's 6 new libs both carry `100755` in the git index, matching
|
|
convention. The hook reads the **git index**: stage with
|
|
`git add --chmod=+x`, and note that a plain `git add` afterwards resets
|
|
it.
|
|
- `pre-commit run --files <changed>` before committing, but run it **after**
|
|
`git add`, not before — index-mode checks (executable bit) only fire
|
|
against what's staged. **`prettier` and `ci-mirror` run on pre-push.**
|
|
`npx prettier --write` any `.md`/`.json` you touch (evidence/contract files
|
|
included — they are JSON and prettier will reformat them).
|
|
- **Every commit touching code needs evidence** in
|
|
`docs/superpowers/evidence/<slug>-<date>.json`. Staging **≥4 code files
|
|
also needs** a fresh `docs/superpowers/contracts/*.json`. Put the
|
|
**measured** coverage number in it, not a rounded-up one. This session's
|
|
pair (`split-diagnose-pacman-hook-stall-2026-08-18.json` in both
|
|
`evidence/` and `contracts/`) is the current best format reference —
|
|
it documents several genuine mid-session findings (a real bug, a
|
|
memory-safety catch, a test-file-too-long split) as they happened, which
|
|
is the level of detail to aim for when the session isn't a pure mechanical
|
|
move.
|
|
- Work directly on `main`. `git stash` and branch creation are blocked; use
|
|
`git worktree add --detach` for a clean baseline (but NEVER `git filter-repo`
|
|
inside a worktree — it shares the object store with the main repo and will
|
|
corrupt it; always a throwaway `git clone` for that).
|
|
- **Do not wire the file-length hook into pre-commit.** It lands last, once
|
|
`check_file_length.sh --all` exits 0.
|
|
- Watch `jscpd` (fails above 2%). Measure in a **clean HEAD worktree**
|
|
(`git worktree add --detach <tmp> HEAD`, copy the new files in, run jscpd
|
|
there, remove the worktree) — the working tree reads higher because of
|
|
vendored `.venv`, and several near-identical test files sharing a fixture
|
|
preamble is exactly the shape that trips this gate.
|
|
- Cap pytest memory:
|
|
`systemd-run --user --scope -p MemorySwapMax=0 -p MemoryMax=2G`.
|
|
- **Never let a test allocate unbounded real memory.** This session's
|
|
`--with-load` entry test would have `dd`ed 13-20+ GB into `/dev/shm` using
|
|
this box's real available memory before it was caught in review — any
|
|
script under test that computes an allocation size from real
|
|
`/proc/meminfo` needs its floor/ceiling constants made env-overridable
|
|
(`: "${VAR:=default}"`, not a bare or `readonly` assignment) so tests can
|
|
pin them to a small, bounded amount instead of trusting the live system
|
|
state to stay favorable.
|
|
|
|
## 6. Tooling reference
|
|
|
|
**`meta/scripts/check_file_length.sh --all`** — the 250-line gate. Run
|
|
**before every commit**. Applies to test files too, not just the file
|
|
you're splitting.
|
|
|
|
**`meta/scripts/shell_coverage.sh <test> <subject> [min]`** — kcov wrapper,
|
|
100% minimum. Hand it the test script **directly**; `bash script.sh`
|
|
instruments the bash binary and silently reports 0/0. If a test suite for
|
|
one subject is split across multiple test files, `shell_coverage.sh` only
|
|
takes one at a time — run kcov manually into the same output dir for each
|
|
test file, then call `meta/scripts/shell_coverage_report.py <outdir> <subject> <min>`
|
|
once to get the merged number (it sums hits per line-number across every
|
|
`cov.xml` it finds, so multiple runs against the same subject combine
|
|
correctly).
|
|
|
|
**`meta/scripts/extract_shell_functions.py`** — moves functions
|
|
brace-by-brace. **Never slice by line range**. **Do not trust where it puts
|
|
the source line** — verify with `grep -c` on the anchor and check placement.
|
|
The `--header` text is written **verbatim, uncommented** — pass a full
|
|
`#!/bin/bash\n# comment` string, not bare prose, or the generated lib won't
|
|
parse.
|
|
|
|
**`meta/scripts/verify_shell_split.sh <pre-split-rev> <old> <new>...`** —
|
|
proves a split moved every function verbatim (hashes function bodies only,
|
|
blind to top-level code). For a **partial** split list the old path among the
|
|
new paths too, or it reports a false `DIFFERENCE`. A function that was
|
|
genuinely rewritten (not moved) will legitimately show as `DIFFERENCE` —
|
|
that's expected, not a bug; explain it in evidence rather than trying to make
|
|
the tool agree.
|
|
|
|
**`meta/scripts/mutate_shell.py <spec>`** — mutation testing against specs in
|
|
`meta/scripts/fixtures/mutations/`. No spec exists for anything outside
|
|
`phone_focus_mode/`; optional, not required — 100% line coverage with real
|
|
assertions is the stated bar.
|
|
|
|
## 7. Testing pattern to follow
|
|
|
|
The established pattern for `single_use/`-adjacent shell scripts with no
|
|
prior test coverage (now used across three splits):
|
|
|
|
- A `lib/tests/` directory sibling to the split libs.
|
|
- A `*_harness.sh` file (sourced, not executed) with `_t_pass`/`_t_fail`/
|
|
`_t_eq` helpers, `mktemp -d` + `trap cleanup EXIT`, and PATH-shim fakes for
|
|
any external tool the code shells out to (record invocation to a file,
|
|
minimum realistic behavior).
|
|
- One `test_<lib>.sh` per lib, sourcing the harness, asserting against real
|
|
function calls (not mocks at the call-site level).
|
|
- A `test_<entry-script>.sh` that runs the **actual entry script as a
|
|
subprocess** against the same fakes, since `verify_shell_split.sh` and kcov
|
|
are blind to code that only lives in the entry script's `main()`. If this
|
|
test file threatens to grow past 250 lines (it will, once you're covering
|
|
several arg combinations and timing branches), split the fixture setup
|
|
into its own `*_entry_harness.sh` early and write two or more thinner test
|
|
files against it — this session had to do this mid-stream and it's
|
|
cheaper to plan for upfront.
|
|
- Sharp edges hit and fixed across sessions, watch for all of them again:
|
|
- `local a="$1" b="${a}"` **fails under `set -u`** — bash evaluates all
|
|
RHS expressions in the new scope before any assignment lands. Split into
|
|
separate `local` statements.
|
|
- A function that calls `exit` (not `return`) on a fatal condition will
|
|
kill the whole test script if called directly inside an `if` condition.
|
|
Run it in a subshell: `if (fn args); then ...`.
|
|
- A backgrounded process needs `disown` before `kill`/`wait` reliably
|
|
affects only it, not the calling job — this bit both a `stop_load` test
|
|
and the entry script's SIGTERM test this session.
|
|
- **SIGINT delivery to a backgrounded job was unreliable in this
|
|
environment; SIGTERM was not.** If a script's trap handles both signals
|
|
identically (`trap handler EXIT INT TERM`), prefer testing via SIGTERM.
|
|
- If a script under test computes a real resource allocation (memory,
|
|
disk) from live system state, make the relevant constants
|
|
env-overridable and pin them to something tiny in every test — never
|
|
trust "the box currently has enough headroom" to stay true.
|
|
|
|
Check the target file for anything that shells out (pacman? systemctl?
|
|
journalctl? guardctl?) before assuming a prior session's fakes apply — each
|
|
file is a different domain, so the PATH-shim list will differ.
|