356 lines
20 KiB
Python
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
|