Merge pull request 'Move the run-heavy rule's command parsing into its own module' (#370) from item-223 into main

This commit was merged in pull request #370.
This commit is contained in:
2026-10-23 14:50:23 +02:00
5 changed files with 92 additions and 54 deletions
+53
View File
@@ -0,0 +1,53 @@
"""Whether a simple command is a heavy one, for the `run-heavy` rule: a docker build, or a run of a mutation tool."""
import posixpath
import re
# Launchers that run the tool named later in their words, such as uvx --with pytest mutmut run.
LAUNCHERS = frozenset({"bunx", "env", "nice", "npx", "pipx", "pnpm", "time", "uvx", "yarn"})
# Each mutation tool, and the words that make its call a mutation run when one of them follows it within two words; where the set is empty, every call is one.
MUTATORS = {"cargo": {"mutants"}, "infection": set(), "mutmut": {"run"}, "stryker": {"run"}}
# Flags with which a tool only prints its help, version or list, so a call that carries one is light. Not -h, which docker run reads as the container's hostname.
LIGHT_FLAGS = frozenset({"--help", "--list", "--version"})
# The options of docker and docker compose that take a value, so the value is not read as a subcommand.
DOCKER_VALUED = frozenset({"--ansi", "--config", "--context", "--env-file", "--file", "--host", "--log-level", "--parallel", "--profile", "--progress", "--project-directory", "--project-name", "-c", "-f", "-H", "-l", "-p"})
def tool_name(word: str) -> str:
"""The tool a word names, such as mutmut for `mutmut>=3,<4` or `.venv/bin/mutmut`; empty for a word that names none, such as a file name."""
named = re.fullmatch(r"([A-Za-z_-]+)(?:[<>=!~@].*)?", posixpath.basename(word))
return named.group(1) if named else ""
def heavy(words: list[str]) -> bool:
"""Whether the simple command, run directly or through a launcher, is a docker build or a mutation run, or runs one in a container, and is not under run-heavy."""
names = [tool_name(word) for word in words]
if not names or "run-heavy" in names or LIGHT_FLAGS & set(words):
return False
# Past a launcher, the tool may follow the launcher's own options and assignments, as in nice -n 19 docker build or uvx --with pytest mutmut run; without one, the command itself is the tool.
launched = names[0] in LAUNCHERS
reachable = names if launched else names[:1]
docker_at = reachable.index("docker") if "docker" in reachable else None
if docker_at is not None:
subcommand = docker_subcommand(words[docker_at + 1:])
return subcommand in (["build"], ["buildx", "build"], ["compose", "build"]) or (subcommand[-1:] in (["run"], ["exec"]) and mutation_run(names[docker_at + 1:]))
return (launched or names[0] in MUTATORS) and mutation_run(names)
def mutation_run(names: list[str]) -> bool:
return any(name in MUTATORS and (not MUTATORS[name] or MUTATORS[name] & set(names[i + 1:i + 3])) for i, name in enumerate(names))
def docker_subcommand(words: list[str]) -> list[str]:
"""The subcommand docker's words name, past its options: such as ["build"], ["compose", "run"] or ["buildx", "build"]."""
positional: list[str] = []
skip = False
for word in words:
if skip:
skip = False
elif word.startswith("-"):
skip = word in DOCKER_VALUED
else:
positional.append(word)
if positional[0] not in ("buildx", "compose") or len(positional) == 2:
break
return positional
+1 -50
View File
@@ -5,6 +5,7 @@ import typing
from round_titles import CAP, lacks_counts, past_cap
from git_command import commits
from rule_hook.heavy_command import heavy
from review_folder import REPORTS
from shell_command import Simple
@@ -100,56 +101,6 @@ class Checked:
overridden: list[tuple[Breach, str]]
# Launchers that run the tool named later in their words, such as uvx --with pytest mutmut run.
LAUNCHERS = frozenset({"bunx", "env", "nice", "npx", "pipx", "pnpm", "time", "uvx", "yarn"})
# Each mutation tool, and the words that make its call a mutation run when one of them follows it within two words; with no words, every call is one.
MUTATORS = {"cargo": {"mutants"}, "infection": set(), "mutmut": {"run"}, "stryker": {"run"}}
# Flags with which a tool only prints its help, version or list, so a call that carries one is light. Not -h, which docker run reads as the container's hostname.
LIGHT_FLAGS = frozenset({"--help", "--list", "--version"})
# The options of docker and docker compose that take a value, so the value is not read as a subcommand.
DOCKER_VALUED = frozenset({"--ansi", "--config", "--context", "--env-file", "--file", "--host", "--log-level", "--parallel", "--profile", "--progress", "--project-directory", "--project-name", "-c", "-f", "-H", "-l", "-p"})
def tool_name(word: str) -> str:
"""The tool a word names, such as mutmut for `mutmut>=3,<4` or `.venv/bin/mutmut`; empty for a word that names none, such as a file name."""
named = re.fullmatch(r"([A-Za-z_-]+)(?:[<>=!~@].*)?", posixpath.basename(word))
return named.group(1) if named else ""
def heavy(words: list[str]) -> bool:
"""Whether the simple command runs a docker build, or a mutation run directly, through a launcher or in a container, outside run-heavy."""
names = [tool_name(word) for word in words]
if not names or "run-heavy" in names or LIGHT_FLAGS & set(words):
return False
# Past a launcher, the tool may follow the launcher's own options and assignments, as in nice -n 19 docker build or uvx --with pytest mutmut run; without one, the command itself is the tool.
launched = names[0] in LAUNCHERS
docker = next((i for i, name in enumerate(names) if name == "docker"), None) if launched else (0 if names[0] == "docker" else None)
if docker is not None:
subcommand = docker_subcommand(words[docker + 1:])
return subcommand in (["build"], ["buildx", "build"], ["compose", "build"]) or (subcommand[-1:] in (["run"], ["exec"]) and mutation_run(names[docker + 1:]))
return (launched or names[0] in MUTATORS) and mutation_run(names)
def mutation_run(names: list[str]) -> bool:
return any(name in MUTATORS and (not MUTATORS[name] or MUTATORS[name] & set(names[i + 1:i + 3])) for i, name in enumerate(names))
def docker_subcommand(words: list[str]) -> list[str]:
"""The subcommand docker's words name, past its options: such as ["build"], ["compose", "run"] or ["buildx", "build"]."""
positional: list[str] = []
skip = False
for word in words:
if skip:
skip = False
elif word.startswith("-"):
skip = word in DOCKER_VALUED
else:
positional.append(word)
if positional[0] not in ("buildx", "compose") or len(positional) == 2:
break
return positional
def overrides(written: str) -> tuple[dict[str, str], list[str]]:
"""The rules the text overrides with their reasons, and the markers that name no rule or give no reason; a marker for a rule that takes no override is neither."""
given = [(rule, reason.strip().removesuffix("-->").strip()) for rule, reason in OVERRIDE.findall(written)]
+21
View File
@@ -2666,3 +2666,24 @@ Inherited architect, decided by:
- Shape: `bin/rule_hook/rules.py:103` `heavy`: argv parsing for docker and mutation tools joins the rule registry, breaking the pattern of a sibling module per non-trivial rule, and rules.py now mixes registry, file checks and a shell parser
- Shape: `bin/rule_hook/rules.py:126` `heavy`: a conditional nested in another decides where docker sits in the words, which a 3am reader unpicks by hand
## 2026-10-23T12:49:21Z, PR #370 at 686c1dc, against 64d4386
Ruling: better
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Mid A | better | better | better | same | better |
| Inherited architect | better | better | better | same | better |
Mid A, decided by:
- Navigation, Locality: `bin/rule_hook/heavy_command.py:1` `heavy_command`: the file name and docstring lead a cold reader to the code that decides the run-heavy rule, which sat in the middle of `rules.py:103-150` before
- Shape: `bin/rule_hook/rules.py:8` `rules`: the file drops from 256 to 207 lines and reaches the heavy-command logic through one import
- Shape, Locality: `bin/rule_hook/heavy_command.py:28` `heavy`: docker's position is two named steps, `reachable` and `docker_at`, where a nested conditional stood at `rules.py:126`
Inherited architect, decided by:
- Navigation, Shape: `bin/rule_hook/heavy_command.py:1` `heavy_command`: a file name in the `rule_hook/` listing points straight at the unit, which the base buried in the 256-line `rules.py:103-150`
- Locality: `bin/rule_hook/heavy_command.py:27` `heavy`: the rule "past a launcher docker can come anywhere, otherwise only first" reads from two plain lines, where the base held a nested conditional
- Locality, Shape: `bin/rule_hook/heavy_command.py:5` `LAUNCHERS`: the tables sit beside their only consumer, so extending them needs no search for other readers
+8
View File
@@ -855,3 +855,11 @@ Read most (opens and searches):
Read most (opens and searches):
- `skills/larv-review/SKILL.md` 2
## Reading cost, chunk 68b123f977ca, finished 2026-10-23T12:33:45Z
169569 new input tokens before the first commit.
Read most (opens and searches):
- `rules/decisions.md` 1
+9 -4
View File
@@ -6,16 +6,17 @@
`Bar = 0.1`
`Next ID = 225`
`Next ID = 227`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 223 | 0.4.0 | | | **Move the `run-heavy` rule's command parsing out of `bin/rule_hook/rules.py` into a module of its own, as `reviewer_rung.py` holds its rule, and pick docker's position in `heavy` without a nested conditional.** | 2 | 1 | 2 | 3 | 2 | code health by 2 | 12.0 |
| 226 | 0.4.0 | | question | **Answer whether rule-hook's `run-heavy` rule should also catch a mutation run or docker build behind `uv run`, `poetry run`, `python3 -m`, `sudo`, `docker image build` and `docker compose up --build`, or narrow the `machine load:` decision's wording.** | 2 | 2 | 3 | 5 | 3 | 1.2 by 2, 1.5 by 2 | 4.0 |
| 59 | 0.4.0 | | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 2 | 1 | 3 | 4 | 3 | 1.4 by 6 | 6.0 |
| 167 | 0.4.0 | | | **Refuse a `/security-review` or `/claude-security` Skill call below the project's rung, as rule-hook refuses such an Agent call.** | 3 | 2 | 3 | 6 | 2 | 1.1 by 4 | 5.6 |
| 6 | 0.4.0 | | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 3 | 3 | 3 | 7 | 3 | 1.1 by 5 | 5.3 |
| 225 | 0.4.0 | | | **Add the value-taking options of docker that `DOCKER_VALUED` lacks, so rule-hook's `run-heavy` rule reads their value as a value and not as the subcommand.** | 1 | 1 | 3 | 3 | 2 | 1.5 by 2 | 2.6 |
| 1 | 0.5.0 | | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 1 | 2 | 1 | 2 | 1 | | 0.0 |
| 219 | 0.5.0 | | | **Name the project's rung `project` in `bin/judge_replay/main.py`, `bin/subagent_rung/main.py` and `bin/review_replay/main.py`, in place of `anchor`, as `bin/model_routing/ladder.py` and `bin/loop_claude` name it.** | 1 | 1 | 3 | 3 | 2 | code health by 2 | 12.0 |
| 224 | 0.5.0 | | | **Split `docs/decisions.md` → `todo.md: one table of items, …`'s 420-word scoring paragraph into one paragraph per choice, and drop the sentences that tell how the goal weights changed.** | 1 | 1 | 1 | 1 | 2 | code health by 2 | 12.0 |
@@ -70,9 +71,9 @@
## Details
### 223. Move the `run-heavy` rule's command parsing out of `bin/rule_hook/rules.py` into a module of its own, as `reviewer_rung.py` holds its rule, and pick docker's position in `heavy` without a nested conditional.
### 226. Answer whether rule-hook's `run-heavy` rule should also catch a mutation run or docker build behind `uv run`, `poetry run`, `python3 -m`, `sudo`, `docker image build` and `docker compose up --build`, or narrow the `machine load:` decision's wording.
PR #366's paired ruling, at e05c54a against 4a0ba59, had Mid A and the inherited architect both rule Shape worse at `bin/rule_hook/rules.py:103` `heavy`. About 50 lines of command-word parsing (`LAUNCHERS`, `MUTATORS`, `DOCKER_VALUED`, `LIGHT_FLAGS`, `tool_name`, `heavy`, `mutation_run`, `docker_subcommand`) joined the module that holds the rule table, while the other non-trivial rules each have a sibling module. Both also named line 126, where a conditional nested in another picks docker's index. Make that place easier to read.
Found by review of PR #370. Today `uv run mutmut run`, `poetry run mutmut run`, `python3 -m mutmut run`, `sudo docker build .`, `docker image build .` and `docker compose up --build` pass the rule, which `docs/decisions.md` → `machine load: …` and `RULES["run-heavy"]` describe as blocking docker builds and mutation runs. The rule's own text says a gate script isn't checked since no program can tell it from a light one, so the human decides where the line sits. Say what the rule's "checked" text promises either way. Where the answer widens the rule, the change touches `heavy` in `bin/rule_hook/heavy_command.py`, which the comprehension seats found hard: make it easier to read.
### 59. Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.
@@ -86,6 +87,10 @@ rule-hook checks Agent calls (item 163) but no Skill calls. A worker that invoke
Claude Code owns that file and writes it. `trust` reads it, changes it and writes it back, so a write that lands in between is lost.
### 225. Add the value-taking options of docker that `DOCKER_VALUED` lacks, so rule-hook's `run-heavy` rule reads their value as a value and not as the subcommand.
Found by review of PR #370, against code that moved unchanged into `bin/rule_hook/heavy_command.py`. `DOCKER_VALUED` there lacks `--tlscacert`, `--tlscert` and `--tlskey`, so `docker --tlscacert ca.pem build .` is not blocked outside run-heavy, although `RULES["run-heavy"]` in `bin/rule_hook/rules.py` says a docker build is. It also lacks buildx's `--builder`, so `docker buildx --builder x build` gets through. Test first in `bin/rule_hook/test_rule_hook.py`. Also no test checks the "within two words" limit of `mutation_run`: a mutant that widens it survives mutmut; add one.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.