Files
claude-config/bin/larv_review/main.py
T

356 lines
20 KiB
Python

"""Hold larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's rounds and its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt.
usage: larv-review {commands}
The comprehension check records how hard a project is to read, two ways, and no score blocks a merge. In a
paired ruling, simulated readers, the seats, read the branch's head beside a base and vote better,
same or worse, overall and on each dimension. In a scoring run, four seats score the project from 1
to 10. Each seat names the places it found hard.
Run it inside a project checkout or one of its worktrees. Each command but review-folder,
record-ruling, places and agreement first fetches origin, when the checkout has that remote, and
takes origin's default branch, or else the local main or master, as the default branch. When the
fetch fails, round-count, reviewer-header and round-title read origin as last fetched and say so on
stderr; the other four exit 1.
The history is docs/comprehension-history.md in the checkout.
review-folder makes the chunk's review folder, where each reviewer writes its report, and prints its
path: ~/.local/state/larv-review/ followed by the worktree's path relative to ~, or to / outside it.
It leaves ~/.local/state/larv-review readable by you alone.
ruling-base prints the commit a paired ruling reads against, then which of these found it. The last
measured commit is the default branch's newest merged change that adds a paired ruling or a scoring
run to the history; a merge commit counts as one change against its first parent. With none, it is
the merge base of HEAD and the default branch.
round-count prints each pass's round count among the branch's commits since the default branch
whose titles open `Answer <pass> round <n>:`, ignoring case. It follows first parents, as
rule-hook's round-cap does. The count is the highest <n>, or the number of such commits when that
is more. At or past the cap of {cap} rounds, {release_cap} for architecture and principles, which run
only in the release review, it says the pass takes no more rounds. It also lists
each name in such a title that is not a pass.
needs-scoring-run takes the IDs of the todo.md items the chunk ships, none when it ships none, and
prints why the chunk is due a scoring run, or `No scoring run due.` It is due when the chunk ships
a floor item, one whose tagline opens with `Reach the comprehension floor:`. It is also due when the
chunk leaves a release with no item in the project's todo.md, once the shipped items are set aside, and work has landed
towards that release; bin/larv_review/plan.py's `work_landed` and `landed_towards` say when. A release the checkout's
todo.md marks renamed in its ## Renamed section, as `- 0.2.1 renamed to 0.3.0`, is due none.
A chunk is also due one while no scoring run in the default branch's history is newer than the
commit of its second-newest v* tag, so a release cut unmeasured is caught up by the next chunk. A project whose
docs/decisions.md opts out of the comprehension check is never due one.
scoring-run-owed prints `No scoring run owed.` or exits 1 naming the runs the chunk owes and has
not recorded. chunk-pr merge runs it and refuses to merge on exit 1, so a due line read earlier in
the chunk can't stand in for it. It applies needs-scoring-run's rule to the project's todo.md and the committed history, against the
merge base with the default branch, so a default branch that has moved on doesn't add anything: the items
the merge base's todo.md holds and the checkout's does not count as shipped. A chunk that empties a
release owes two runs, any other due chunk one. The chunk has recorded the scoring runs that its
committed docs/comprehension-history.md holds beyond the merge base's. A project that opts out or
has no todo.md items table owes none.
No commit holds a file the project's config puts outside the checkout. For such a todo.md or history,
scoring-run-owed says on stderr that it cannot tell whether a run is owed, and still prints
`No scoring run owed.`, so the merge goes on. For such a todo.md, needs-scoring-run and
record-scoring take only the IDs of items it still holds: run them before `todo-item finish`.
A second scoring run of one head names itself `<PR or branch> rerun at <commit>`, so record-scoring
does not refuse it as a repeat of the first.
A seats file's first line names what the seats read, `<PR or branch> at <commit>`, ending
`, against <base>` in a votes file. Each seat's line follows, opening with its label written
exactly: `Junior A:`, `Mid A:`, `Maintainability senior:` or `Inherited architect:`. Its places
follow it, one `- ` bullet each, as the history writes them. A votes file:
PR #231 at abc1234, against def5678
Mid A: Navigation better, Locality worse, Shape same, Self-sufficiency same, Overall better
- Navigation, Overall: `README.md:40` "Tools": names the tool a symptom leads to
- Locality: `bin/x.py:12` `run`: three branches to hold at once
Inherited architect: Navigation better, Locality worse, Shape same, Self-sufficiency same, Overall better
- Navigation: `README.md:40` "Tools": ...
- Locality: `bin/x.py:12` `run`: ...
A scores file holds Junior A's, Mid A's, the maintainability senior's and the inherited architect's
lines in that order, each `Navigation <n>, Locality <n>, Shape <n>, Self-sufficiency <n>, Overall
<n>`: each score from 1 to 10, and the overall at most 1 above the line's lowest dimension.
record-ruling takes Mid A's and the inherited architect's votes on each dimension and overall, each
better, same or worse. Each place opens with the names from the seat's line that it moves, joined by
`, ` and followed by `: `. A dimension's vote counts as same unless one of the seat's places opens
with that dimension and holds a `path:line` in backticks; the overall vote counts as same unless any
place holds one. The printed votes say so. When the two counted overall votes differ, it appends
no line and prints `Split:`, saying to add the maintainability senior's and Junior A's lines.
Otherwise the ruling is the overall vote that leads each other vote by two or more, else same. It
prints `Ruling:` and appends the ruling.
prepare-scoring sets up a scoring run in the chunk's review folder: a detached worktree of the
checkout's HEAD, which the seats read, and one prompt file per seat beside it, as
skills/comprehension-panel/seat-prompts.md builds them. It prints the worktree's path and each
prompt's. It takes {{language}}, {{kind}}, {{domain}}, {{domain docs}} and {{3am question}} from the
checkout's AGENTS.md → "Scoring run". claude-config keeps no AGENTS.md, so there it takes them from
seat-prompts.md → "claude-config's values". It fills the other placeholders from the worktree and
the panel's SKILL.md. Where any one of the five values is missing, it exits 1 and doesn't write
anything. Where a setup that record-scoring never removed is still there, it removes it first and
says so.
record-scoring takes the scores file of a run needs-scoring-run calls, whose first line names no
`, against`, and the same item IDs, and exits 1 when they call no run. It appends the seats' scores
and their means, rounded half up to two decimals, prints the means and, when a mean is under the
project's readability floor, a line opening `Floor:` naming each one and the floor. The config sets
the floor as `readability-floor`, {floor} where left out. A line opening `Next:` follows it. It
says to file a floor item aimed at the lowest of the four dimensions, and names the tagline's opening
`Reach the comprehension floor:`. Where the project's todo.md holds such an item other than those given, it says to
refresh that item instead. Then it ranks the project's todo.md as rank_todo.py does, since the
overall sets the weight of code health, the goal every project shares, and exits 1 where
rank_todo.py would, with the run recorded. Last, it removes what prepare-scoring set up, so a
second run of one head runs prepare-scoring again.
record-ruling and record-scoring append each entry to the history, created when missing, under a
heading of the current UTC time and the seats file's first line. Each commit that line names must be
in the checkout. Each exits 1 when the history already holds an entry on what that line reads.
places prints the places seats found hard since the newest scored commit: the places of each scoring
run on it, and,
in each later ruling, each place opening with a dimension, or Overall, that its seat voted worse.
A ruling recorded with scoring seats' places counts as a scoring run. Each entry's places come
under its heading, oldest first. With no scoring run, it reads every ruling.
agreement pairs the first two scoring runs recorded on one commit. In each pair, a seat's overall
score goes up, goes down or stays the same. It checks the assumption behind the paired ruling: Mid A
and the inherited architect vote alike overall in a paired ruling more often than their scores go the
same way in a pair. It prints both counts. It opens `Unchecked:` until the history holds {pairs} such
pairs and one paired ruling, then `Assumption holds:` or `Assumption fails:`, and exits 0 each time.
reviewer-header takes the name of a pass that an agent under agents/ reviews, spelled as round-count
prints it, such as stability. It prints the header of the prompt that launches the pass's reviewer
in its next round: the pass and round, the branch's open pull request at its pushed head, the
worktree and branch, the merge base of HEAD and the default branch, and the paths of the reviewer's
report, the branch diff, the folders of technical principles and review standards the project's
config sets, the goals and the plan and, for architecture and stability, the places. For a reviewer whose
definition under ~/.claude/agents/ has `omitClaudeMd: true`, it then names the file that holds the
project principles and decision titles, where the project keeps one. It writes the diff, from
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, writes what
places prints into places.md, and lists the plan's items into
plan.md, whatever store holds the plan; a file whose text is unchanged is left as it is. With --rerun, the
header names the report of a relaunch one rung up, in the same round, and the report that asked for
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when
the principles or standards folder is not a folder with a file in it, or, with --rerun, when the
report that asked is missing.
round-title takes a pass as reviewer-header does. It prints how the commit that answers the pass's
unanswered round opens its title, after any prefix the project's commit-title template adds, up to
and including the `;` before the summary, such as `Answer prose round 1: 0 🔴, 2 🟡 (0 misread);`. It
counts the findings in the round's report in the review folder, or in its rerun's where there is
one: each line that opens `### 🔴` or `### 🟡`, and of them each whose mark is followed by
`[misread]`. rule-hook's round-title-counts refuses a round title whose counts differ from that
report's. It exits 1 when the pass takes no more rounds, or the report is missing, unreadable or
says BLOCK without such a line.
reviewer-context is the SubagentStart hook. It reads the hook's input on stdin. For a reviewer
whose definition under ~/.claude/agents/ has `omitClaudeMd: true`, and so starts without CLAUDE.md,
it prints the hook reply that hands the agent the Shared goal, Prose and Vocabulary sections of
~/.claude/CLAUDE.md; for any other agent it doesn't print anything. Where it cannot read the file
or a section, the reply tells the reviewer to open its report with that failure, and it exits 0,
since Claude Code starts the subagent whatever the hook exits with.
Exit 1, saying why, on unknown arguments, an unknown item ID, a seats file it cannot read or that
breaks the shape above, a todo.md that fails rank_todo.py after record-scoring records a run, or
when git cannot start, finds no checkout or no default branch, cannot fetch origin for ruling-base,
needs-scoring-run, scoring-run-owed or record-scoring, or cannot read or write the history, todo.md, the review
folder or a file prepare-scoring reads.
"""
import pathlib
import re
import sys
import time
import typing
from git_cli.git_repo import branch_titles, default_branch, git, top
from review_rules.round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
from project_config.settings import DEFAULT_FLOOR
from failure import Failure
from larv_review.history_changes import history_changes
from review_rules.reviewer_context import hook_reply
from review_rules.review_folder import made_review_folder
from larv_review.ruling_base import measured_commit
from larv_review.agreement import MIN_PAIRS
from larv_review.owed import owed_scoring_run
from review_rules.review_passes import PASSES, REVIEWERS
from larv_review.plan import plan_reasons
from larv_review.scoring_setup import prepare_scoring
from larv_review.history_commands import read_agreement, read_places, record_ruling, record_scoring
from larv_review.reviewer_header import reviewer_header
from larv_review.round_title import round_title
from project_config.main import title_templates
class Command(typing.NamedTuple):
"""One subcommand: how the usage line spells it, whether the arguments after its name fit, and what it does with them. Where it ends in item IDs, ids_from is the number of arguments before them, so main can name the arguments that aren't IDs."""
shape: str
fits: typing.Callable[[list[str]], bool]
run: typing.Callable[[list[str]], Failure | None]
ids_from: int | None = None
ITEM_ID = re.compile(r"[0-9]+")
def no_arguments(given: list[str]) -> bool:
return not given
def are_ids(given: list[str]) -> bool:
return all(ITEM_ID.fullmatch(id_) for id_ in given)
def run_needs_scoring_run(given: list[str]) -> Failure | None:
return with_default_branch(lambda default: needs_scoring_run(default, [int(id_) for id_ in given], pathlib.Path.home()), stale_ok=False)
def fits_prepare_scoring(given: list[str]) -> bool:
return not given
def run_record_scoring(given: list[str]) -> Failure | None:
return with_default_branch(lambda default: record_scoring(default, pathlib.Path(given[0]), [int(id_) for id_ in given[1:]], pathlib.Path.home(), time.time(), print, warn), stale_ok=False)
def fits_reviewer_header(given: list[str]) -> bool:
return bool(given) and given[0] in REVIEWERS and given[1:] in ([], ["--rerun"])
def run_reviewer_header(given: list[str]) -> Failure | None:
return with_default_branch(lambda default: printed(reviewer_header(default, given[0], given[1:] == ["--rerun"], pathlib.Path.home())), stale_ok=True)
# One row per subcommand: main, USAGE and `--help` all read this table.
COMMANDS = {
"review-folder": Command("review-folder", no_arguments, lambda given: make_review_folder()),
"ruling-base": Command("ruling-base", no_arguments, lambda given: with_default_branch(lambda default: show_ruling_base(default, pathlib.Path.home()), stale_ok=False)),
"round-count": Command("round-count", no_arguments, lambda given: with_default_branch(round_count, stale_ok=True)),
"needs-scoring-run": Command("needs-scoring-run [<item ID>...]", are_ids, run_needs_scoring_run, ids_from=0),
"scoring-run-owed": Command("scoring-run-owed", no_arguments, lambda given: with_default_branch(lambda default: owed(default, pathlib.Path.home()), stale_ok=False)),
"record-ruling": Command("record-ruling <votes file>", lambda given: len(given) == 1, lambda given: printed(record_ruling(pathlib.Path(given[0]), pathlib.Path.home(), time.time()))),
"prepare-scoring": Command("prepare-scoring", fits_prepare_scoring, lambda given: prepared_scoring()),
"record-scoring": Command("record-scoring <scores file> [<item ID>...]", lambda given: bool(given) and are_ids(given[1:]), run_record_scoring, ids_from=1),
"places": Command("places", no_arguments, lambda given: printed(read_places(pathlib.Path.home()))),
"agreement": Command("agreement", no_arguments, lambda given: printed(read_agreement(pathlib.Path.home()))),
"reviewer-header": Command("reviewer-header <pass> [--rerun]", fits_reviewer_header, run_reviewer_header),
"round-title": Command("round-title <pass>", lambda given: len(given) == 1 and given[0] in REVIEWERS, lambda given: with_default_branch(lambda default: printed(round_title(default, given[0], pathlib.Path.home())), stale_ok=True)),
"reviewer-context": Command("reviewer-context", no_arguments, lambda given: printed(hook_reply(sys.stdin.read(), pathlib.Path.home()))),
}
SHAPES = " | ".join(command.shape for command in COMMANDS.values())
USAGE = f"usage: larv-review {SHAPES}"
def main(argv: list[str]) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip().format(commands=SHAPES, cap=CAP, release_cap=RELEASE_REVIEW_CAP, floor=DEFAULT_FLOOR, pairs=MIN_PAIRS))
return 0
if not argv:
print(USAGE, file=sys.stderr)
return 1
name, *given = argv
command = COMMANDS.get(name)
if command and command.fits(given):
done = command.run(given)
elif command and command.ids_from is not None and (named := [id_ for id_ in given[command.ids_from:] if not ITEM_ID.fullmatch(id_)]):
print(f"{name} takes item IDs, the numbers in todo.md's ID column, not {' '.join(named)}; {USAGE}", file=sys.stderr)
return 1
else:
print(f"unknown arguments {' '.join(argv)}; {USAGE}", file=sys.stderr)
return 1
if isinstance(done, Failure):
print(done.reason, file=sys.stderr)
return 1
return 0
def warn(line: str) -> None:
print(line, file=sys.stderr)
def printed(reply: str | Failure) -> Failure | None:
if isinstance(reply, Failure):
return reply
if reply:
print(reply)
return None
def with_default_branch(command: typing.Callable[[str], Failure | None], stale_ok: bool) -> Failure | None:
default = default_branch(stale_ok)
if isinstance(default, Failure):
return default
branch, note = default
if note:
print(note, file=sys.stderr)
return command(branch)
def prepared_scoring() -> Failure | None:
worktree = top()
return worktree if isinstance(worktree, Failure) else printed(prepare_scoring(worktree, pathlib.Path.home()))
def make_review_folder() -> Failure | None:
worktree = top()
if isinstance(worktree, Failure):
return worktree
folder = made_review_folder(worktree, pathlib.Path.home())
if isinstance(folder, Failure):
return folder
print(folder)
return None
def show_ruling_base(default: str, home: pathlib.Path) -> Failure | None:
changes = history_changes(default, home)
if isinstance(changes, Failure):
return changes
if found := measured_commit(changes):
print(f"{found}\nthe last measured commit")
return None
merge_base = git("merge-base", "HEAD", default)
if isinstance(merge_base, Failure):
return merge_base
print(f"{merge_base.strip()}\nthe merge base of HEAD and {default}")
return None
def round_count(default: str) -> Failure | None:
titles = branch_titles(default)
if isinstance(titles, Failure):
return titles
templates = title_templates(None, pathlib.Path.home())
if isinstance(templates, Failure):
return templates
for name, count in round_counts([templates.summary(title) for title in titles]).items():
print(f"{name}: {count}{cap_note(count, cap(name)) if name in PASSES else ', not a pass: check the commit title'}")
return None
def cap_note(count: int, most: int) -> str:
if count < most:
return ""
return f", {'at' if count == most else 'past'} the cap: no more rounds"
def owed(default: str, home: pathlib.Path) -> Failure | None:
unrecorded = owed_scoring_run(default, home, warn)
if unrecorded is None:
print("No scoring run owed.")
return unrecorded
def needs_scoring_run(default: str, ids: list[int], home: pathlib.Path) -> Failure | None:
reasons = plan_reasons(default, ids, home)
if isinstance(reasons, Failure):
return reasons
print(f"Scoring run due: the chunk {' and '.join(reasons)}." if reasons else "No scoring run due.")
return None