testsAndMisc/refactor_claude_todo_resume.md
Krzysztof kuhy Rudnicki 8ce453690f Split wsg_grabber/cli.py under the 250-line cap
The `logs` subcommand's reporting -- show_logs() and summarise() -- is
read-only analysis of the JSONL session logs and shares nothing with the
scrape/review flow, so it moves to _logs_report.py.

cli.py re-exports both through __all__ so cli.show_logs / cli.summarise stay
valid for test_cli.py and the dispatch table. The PEP 484 `X as X` alias form
does NOT survive here: ruff flags it PLC0414, autofixes it away, and then
deletes the import as unused under F401 -- which would break cli.summarise
with lint still green. Recorded in the handoff so it is not re-derived.

cli.py 282 -> 247, new _logs_report.py 76. 277 wsg_grabber tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
2026-08-16 15:39:10 +02:00

168 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Resume: enforce the 250-line file cap
> **Paste this whole file to a fresh Claude session opened in `~/testsAndMisc`.**
> It is self-contained. Continues `refactor_claude_todo.md`, which is still the
> spec — read it too, but the decisions below override it where they differ.
## Where things stand
**192 files** over 250 lines (was 198). All work so far is committed and pushed
to `main`; `git status` is clean apart from pre-existing unrelated edits to
`README.md`, `billsplit/analysis_options.yaml`, `focus_owner/analysis_options.yaml`
— **leave those three alone, they are not yours.**
Done already (do not redo):
| Commit | What |
| --------- | -------------------------------------------------------------------- |
| `~/utils` | `plans/` + `sessions/` exempted from the cap (`specs/` still capped) |
| `17b20e5` | New `no-inline-python` pre-commit hook + the one violation fixed |
| `004b4b0` | `CLAUDE.md` 259 → 141 lines |
| `72a5e28` | `poker-stakes/` tracked in git (58 files) |
| `73b85f5` | `poker-stakes/` 4 violations → 0 |
## The live worklist
Do not work from a list in this file — it goes stale. Run:
```bash
bash ~/utils/scripts/check_file_length.sh --all
```
Current distribution: `linux_configuration` 84, `python_pkg` 50,
`phone_focus_mode` 13, `kcd2_dice_solver` 12, `focus_owner` 11, `billsplit` 6,
`reverse_survivors`/`meta`/`docs` 4 each, `.github`/`bucket_catch` 2 each.
**48 of them are near-misses at 251–300 lines** — highest count-drop per unit
of effort, do these first.
## Decisions already made (do not re-ask)
1. **Full clearance** to `--all` exit 0. When context runs out, write a fresh
handoff like this one rather than stopping mid-way.
2. **CI checks only files in the push/PR range**, not `--all`.
3. `docs/superpowers/plans/**` + `sessions/**` are exempt — already done.
4. `poker-stakes/` is tracked — already done.
5. For prose: automate what can be automated, delete the automated lines, keep
only HOW, never WHY.
6. Shell verification is `bash -n` + `shellcheck` + `systemctl cat` path checks.
**Never execute enforcement scripts that mutate the phone or the live system.**
7. One commit per logical unit.
## The constraint that will bite you
**Wire the file-length gate LAST**, only once `--all` already exits 0.
`meta/scripts/ci_mirror.sh:109` runs `pre-commit run --all-files` as a
**pre-push** hook, and `.github/workflows/pre-commit.yml:105` does the same in
CI. Registering the hook while violations remain makes **every `git push` fail**
until the last file is fixed. Do not scope around it with `exclude:`/`files:` —
that is the allowlist the spec forbids.
Final commit, once and only once the tree is clean:
```yaml
- id: file-length
name: file length <= 250 lines
entry: bash /home/kuhy/utils/scripts/check_file_length.sh
language: system
```
Plus `.github/workflows/file-length.yml` modelled on
`~/todo/.github/workflows/file-length.yml` (checks out `kuhyx/utils` into
`.utils`), scoped to changed files. Then prove it fails: stage a deliberately
251-line file, confirm `git commit` aborts, delete it.
## The Python re-export form — settled empirically, do not re-derive
When a split moves a **public** name out of a module that callers/tests still
reach through the old path, the re-export must be marked with `__all__`:
```python
from python_pkg.pkg._new_module import show_logs, summarise
__all__ = ["build_parser", "main", ..., "show_logs", "summarise"]
```
The PEP 484 alias form `from x import y as y` **does not work here**: ruff
raises `PLC0414` (useless-import-alias), auto-fixes it away, and then removes
the now-"unused" import under `F401` — silently breaking `cli.summarise`.
Verified on `wsg_grabber/cli.py`; `__all__` passes ruff + mypy + pylint clean.
Splits that only move **private** helpers (leading `_`, no external caller)
need no shim at all — check with grep first, as in `catalog.py`.
Coverage: `meta/pyproject.toml` sets `source = ["python_pkg"]`, so a new
sibling module is measured automatically. Confirmed: new modules show up in
the report at 100% rather than being silently skipped. Add no new branches
(no `if TYPE_CHECKING` guards beyond what moved, no defensive `try/except`).
## Split recipes
- **Shell** — extract into `lib/*.sh` sourced by a thin entry script,
`set -euo pipefail` in each. Follow `phone_focus_mode/lib/` and
`linux_configuration/scripts/lib/common.sh`.
- **Python** — extract cohesive helpers into sibling modules; keep the public
API stable by re-exporting.
- **TS/Dart** — extract components; re-export from the original path so no
importer changes.
- **Tests** — split by describe/test-group. Coverage must not drop.
Never game the cap: no one-lining, no deleting tests, no moving code into an
exempt extension, no suppressions.
## Traps that cost time in the last session
- **Test fixtures and coverage.** When splitting a test file, shared helpers
must go where the coverage config already excludes them (in `poker-stakes`
that is `src/test/**`, matched **by path**). Putting them beside the source
makes the coverage tool count them as production code and the 100% gate
fails. Move the file; do **not** add a `coverage.exclude` entry.
- **`end-of-file-fixer` aborts commits.** Files built with `sed`/`cat` often
lack a trailing newline. The hook fixes it and then fails the commit
("files were modified by this hook"). Just `git add` again and re-commit.
- **Formatters silently revert edits.** A PostToolUse formatter stripped an
added import twice. After editing, `grep` the file to confirm the change
survived before running anything.
- **Contracts.** Staging **≥4 code files** requires a _fresh_
`docs/superpowers/contracts/*.json` in that same commit, on top of the
per-commit `docs/superpowers/evidence/*.json`. Required keys: `title`,
`objective`, `acceptance_criteria`, `out_of_scope`, `verifier`. Validate with
`python3 meta/scripts/validate_contract.py <file>`.
- **`invariants.test.ts` in poker-stakes** flakes on its 5s timeout under
parallel coverage load. It passes standalone in ~2.6s. Not a regression —
do not "fix" it by weakening the test.
- **Long commands**: background anything over ~60s rather than blocking.
## `phone_focus_mode` — highest blast radius, do it LAST
Two silent failure modes:
1. **`deploy.sh` has a hardcoded flat push list** (search for `adb_cmd push`,
around lines 374–383) with **no `lib/` subdirectory**. Every new split lib
must be added there in the same commit, or the phone sources a missing file
at runtime — gate green, tests green, device broken.
2. **`config.sh` (556 lines) is sourced by 11 scripts.** Keep `config.sh` as
the entry point that re-sources its own parts, so all 11 callers keep
working untouched.
Static check after each split: grep `deploy.sh`'s push list and every
`source`/`.` line in `phone_focus_mode/*.sh` and confirm each new lib appears.
## Suggested order
1. The 48 near-misses (251–300) — mechanical, biggest count drop.
2. `python_pkg` (50) — `pytest-coverage` gates each changed package on commit.
3. `linux_configuration` (84) — largest; check systemd unit paths still resolve.
4. `kcd2_dice_solver`, `focus_owner`, `billsplit`, the rest.
5. `phone_focus_mode` (13) — with the guard above.
6. Gate wiring + CI workflow — last.
## Done condition
```bash
cd ~/testsAndMisc && bash ~/utils/scripts/check_file_length.sh --all # exit 0
pre-commit run --all-files # passes
```
Plus: a staged 251-line file makes `git commit` fail.