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

1360 lines
91 KiB
Python

import contextlib
import decimal
import itertools
import json
import os
import pathlib
import subprocess
import sys
import tempfile
import textwrap
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from larv_review.agreement import agreement_report, ruling_agreement, run_agreement
from review_rules.comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
from larv_review.history_commands import appended_to
from larv_review.plan import checkout_plan, Emptied, EMPTIED_WORDS, landed_towards, plan_reasons, scoring_run_due
from review_rules import comprehension_history
from project_config.doubles import configured
from larv_review.ruling import counted, ruling, split, surplus, votes
from larv_review.history_commands import decided, rerank
from project_config.settings import DEFAULT_FLOOR
from failure import Failure
from plan_store.todo_md import FilePlan
from record_store.stores import FileStore
from larv_review.scoring import floor_step, means, under_floor
from record_store.held import Held
from test_env import isolated_env
from plan.todo_table import Item, items, NoItemsTable
from release_plan.release_standing import LastCut
from larv_review.ruling_base import measured_commit
from record_store.fakes import MemoryStore
from larv_review.seats import score_line, scores, seats_file, SeatsFile
from larv_review.owed import shortfall
TOOL = pathlib.Path(__file__).resolve().parents[1] / "larv-review"
SCORING = "## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mean | 7.00 |\n"
def paired(time: str, verdict: str, commit: str = "bbbbbbb") -> str:
return f"## {time}, PR #2 at {commit}, against aaaaaaa\n\nRuling: {verdict}\n"
def said(overall: str, locality: str = "same") -> str:
return f"Navigation same, Locality {locality}, Shape same, Self-sufficiency same, Overall {overall}"
def item(id_: int, release: tuple[int, int, int], tagline: str = "**Do it.**") -> Item:
return Item(id_, release, "", tagline, {"R": 1, "S": 1, "C": 3, "A": 1, "G": 1}, (("1", None),), ())
def todo(*rows: str) -> str:
return "## Items\n\n| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n" + "".join(f"{row}\n" for row in rows)
class Seats(unittest.TestCase):
def test_reads_each_seats_line_and_places_and_joins_a_wrapped_place(self):
given = seats_file(f"PR #2 at abc1234, against def5678\n\nMid A: {said('worse')}\n\n- `a.py:1` `f`: hard\n to read\n\nInherited architect: {said('same')}\n")
self.assertEqual(given.read, "PR #2 at abc1234, against def5678")
self.assertEqual(given.seats, [Seat("Mid A", said("worse"), ["`a.py:1` `f`: hard to read"]), Seat("Inherited architect", said("same"), [])])
def test_refuses_a_line_that_is_neither_a_seat_nor_a_place_and_a_seat_twice(self):
self.assertIsInstance(seats_file("PR #2 at abc1234\n\nMid A worse\n"), Failure)
self.assertIsInstance(seats_file("PR #2 at abc1234\n\nMid A: worse\n\nMid A: same\n"), Failure)
self.assertIsInstance(seats_file(""), Failure)
def test_counts_each_vote_of_a_seat_naming_no_place_as_same(self):
seats = [Seat("Mid A", said("worse", "worse"), ["Locality: the whole skill"]), Seat("Inherited architect", said("better"), ["Overall: `a.py:3` `f`: shorter"])]
written = votes(seats)
self.assertEqual(written, {"Mid A": ["same", "worse", "same", "same", "worse"], "Inherited architect": ["same", "same", "same", "same", "better"]})
self.assertEqual(counted(seats, written)["Mid A"], ["same"] * 5)
def test_counts_a_dimensions_vote_only_where_a_place_names_that_dimension(self):
seats = [Seat("Mid A", said("better", "worse"), ["Shape: `a.py:3` `f`: the Locality of it, reshaped"]), Seat("Inherited architect", said("better", "worse"), ["Locality, Shape: `a.py:3` `f`: held at once"])]
written = {seat.name: ["same", "worse", "same", "same", "better"] for seat in seats}
self.assertEqual(counted(seats, written), {"Mid A": ["same", "same", "same", "same", "better"], "Inherited architect": written["Inherited architect"]})
self.assertIsInstance(votes([Seat("Mid A", said("better"), ["Locality, self sufficiency: `a.py:3` `f`: x"]), seats[1]]), Failure)
self.assertIsInstance(votes([Seat("Mid A", said("better"), ["`a.py:3` `f`: Locality: x"]), seats[1]]), Failure)
self.assertEqual(votes(seats), {seat.name: written[seat.name] for seat in seats})
def test_reads_the_other_two_seats_even_when_the_first_two_agree_overall(self):
seats = [Seat(name, said(vote), ["Overall: `f.py:1` `f`: x"]) for name, vote in (("Mid A", "worse"), ("Inherited architect", "worse"), ("Maintainability senior", "better"), ("Junior A", "better"))]
self.assertEqual(list(votes(seats)), [seat.name for seat in seats])
def test_flags_seats_beyond_the_first_two_when_those_agree_overall(self):
self.assertTrue(surplus(["worse", "worse", "better", "better"]))
self.assertFalse(surplus(["worse", "worse"]))
self.assertFalse(surplus(["worse", "same", "better", "better"]))
def test_takes_the_first_two_seats_then_the_other_two_in_order_and_each_dimensions_vote(self):
first = [Seat("Mid A", said("same"), []), Seat("Inherited architect", said("same"), [])]
self.assertIsInstance(votes(first[::-1]), Failure)
self.assertIsInstance(votes(first + [Seat("Junior A", said("same"), [])]), Failure)
self.assertIsInstance(votes([first[0], Seat("Inherited architect", said("worst"), [])]), Failure)
self.assertIsInstance(votes([first[0], Seat("Inherited architect", "same", [])]), Failure)
def test_rules_by_a_lead_of_two_and_splits_two_seats_that_differ(self):
cases = [
(["worse", "worse"], "worse"),
(["same", "same"], "same"),
(["worse", "same"], None),
(["worse", "better", "worse", "worse"], "worse"),
(["worse", "same", "worse", "same"], "same"),
(["worse", "same", "worse", "better"], "same"),
(["better", "same", "better", "better"], "better"),
]
for counted, expected in cases:
with self.subTest(counted):
self.assertEqual(None if split(counted) else ruling(counted), expected)
def test_reads_four_seats_scores_and_refuses_an_overall_above_the_lowest_by_more_than_one(self):
line = "Navigation 7, Locality 6.5, Shape 7, Self-sufficiency 6.5, Overall 7"
seats = [Seat(name, line, []) for name in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect")]
self.assertEqual(scores(seats)["Mid A"], ["7", "6.5", "7", "6.5", "7"])
self.assertIsInstance(scores(seats[:3]), Failure)
self.assertIsInstance(scores([*seats[:3], Seat("Inherited architect", line.replace("Overall 7", "Overall 8"), [])]), Failure)
self.assertIsInstance(scores([*seats[:3], Seat("Inherited architect", line.replace("Shape 7", "Shape 11"), [])]), Failure)
self.assertEqual(score_line("Mean", "Navigation 7.38, Locality 7.38, Shape 8, Self-sufficiency 8, Overall 8.38")[-1], "8.38")
def test_rounds_each_mean_half_up_and_names_each_under_the_floor(self):
found = means([["7.5", "6.5", "7", "7", "7"], ["7.5", "7", "7", "6.5", "7"], ["7", "6.5", "7", "6.5", "6.5"], ["7.5", "6.5", "7", "6.5", "7"]])
self.assertEqual([str(mean) for mean in found], ["7.38", "6.63", "7.00", "6.63", "6.88"])
self.assertEqual(under_floor(found, DEFAULT_FLOOR), ["Locality 6.63", "Self-sufficiency 6.63", "Overall 6.88"])
self.assertEqual(under_floor([decimal.Decimal("7.00")] * 5, DEFAULT_FLOOR), [])
def test_names_only_the_means_under_the_floor_it_is_given_and_aims_the_next_item_at_it(self):
found = [decimal.Decimal(mean) for mean in ("6.50", "5.75", "6.00", "5.50", "5.94")]
self.assertEqual(under_floor(found, decimal.Decimal("6")), ["Locality 5.75", "Self-sufficiency 5.50", "Overall 5.94"])
self.assertEqual(under_floor(found, decimal.Decimal("5.5")), [])
self.assertIsNone(floor_step(found, [], [], decimal.Decimal("5.5")))
self.assertIn("until every mean reaches 6, ", floor_step(found, [], [], decimal.Decimal("6")))
def test_floor_step_files_one_item_at_the_lowest_dimension_unless_one_is_open(self):
found = [decimal.Decimal(mean) for mean in ("7.38", "6.63", "7.00", "6.50", "6.88")]
floor_item = item(5, (0, 2, 0), "**Reach the comprehension floor: restructure the reload, lifting Locality.**")
with self.subTest("none open"):
step = floor_step(found, [item(1, (0, 1, 0))], [], DEFAULT_FLOOR)
self.assertTrue(step.startswith("Next: file one floor item"), step)
self.assertIn("with a tagline that opens with `Reach the comprehension floor:`,", step)
self.assertIn(" Self-sufficiency, the lowest dimension,", step)
self.assertIn('"Floor item"', step)
with self.subTest("one open"):
step = floor_step(found, [item(1, (0, 1, 0)), floor_item], [], DEFAULT_FLOOR)
self.assertTrue(step.startswith("Next: refresh floor item 5 "), step)
self.assertIn(" Self-sufficiency, the lowest dimension,", step)
self.assertIn("file no other", step)
with self.subTest("the shipped one is not open"):
self.assertTrue(floor_step(found, [floor_item], [5], DEFAULT_FLOOR).startswith("Next: file one floor item"))
with self.subTest("a tie names both"):
tied = [decimal.Decimal(mean) for mean in ("7.38", "6.50", "7.00", "6.50", "6.88")]
self.assertIn(" Locality and Self-sufficiency, the lowest dimensions,", floor_step(tied, [], [], DEFAULT_FLOOR))
with self.subTest("a tagline that only mentions the floor is no floor item"):
quoting = item(6, (0, 2, 0), "**Rename the decision `comprehension floor: …` in the log.**")
self.assertTrue(floor_step(found, [quoting], [], DEFAULT_FLOOR).startswith("Next: file one floor item"))
with self.subTest("none under the floor"):
self.assertIsNone(floor_step([decimal.Decimal("7.00")] * 5, [floor_item], [], DEFAULT_FLOOR))
with self.subTest("only the overall under the floor"):
step = floor_step([decimal.Decimal("7.00")] * 4 + [decimal.Decimal("6.75")], [], [], DEFAULT_FLOOR)
self.assertIn(" Navigation, Locality, Shape and Self-sufficiency, the lowest dimensions,", step)
self.assertIn("until every mean reaches 7.0", step)
def test_checkout_plan_fails_on_a_missing_or_tableless_todo(self):
with tempfile.TemporaryDirectory() as checkout:
path = pathlib.Path(checkout, "todo.md")
plan = FilePlan(path, "todo.md", FileStore(pathlib.Path(checkout, "README.md"), None), MemoryStore(), MemoryStore(), DEFAULT_FLOOR)
with self.subTest("missing"):
self.assertEqual(checkout_plan(plan).reason, f"the project's plan: {path}: not found; every project keeps a todo.md, and rank_todo.py --help shows one")
with self.subTest("no items table"):
path.write_text("# todo\n", encoding="utf-8")
self.assertIn("no items table", checkout_plan(plan).reason)
with self.subTest("a malformed row"):
path.write_text(todo("| x | 0.1.0 |"), encoding="utf-8")
self.assertIn("the project's plan:", checkout_plan(plan).reason)
class History(unittest.TestCase):
def test_writes_the_sample_entry_its_parser_shows(self):
source = pathlib.Path(comprehension_history.__file__).read_text(encoding="utf-8").splitlines()
start = next(index for index, line in enumerate(source) if line.startswith("# ## "))
sample = [line.removeprefix("#").removeprefix(" ") for line in itertools.takewhile(lambda line: line.startswith("#"), source[start:])]
seat = Seat("Mid A", said("better", "worse"), ["Locality: `bin/x.py:12` `run`: three branches to hold at once"])
votes = {"Mid A": ["better", "worse", "same", "same", "better"]}
self.assertEqual(ruling_entry("2026-10-09T09:47:25Z, PR #232 at 324d650, against 12d6d75", [seat], votes, votes, "same"), "\n".join(sample) + "\n")
def test_reads_tables_whose_separators_hold_spaces_as_adf_codec_writes_them(self):
scoring = ScoringRun([Seat("Junior A", "", [])], {"Junior A": ["7", "6.5", "7", "7", "7"]}, [decimal.Decimal(mean) for mean in ("7.00", "6.50", "7.00", "7.00", "7.00")])
history = appended("", scoring_entry("2026-10-08T12:00:00Z, PR #1 at aaaaaaa", scoring))
spaced = "\n".join("| " + " | ".join(["---"] * line.count("---")) + " |" if line.startswith("|-") else line for line in history.splitlines())
self.assertNotEqual(spaced, history)
self.assertEqual(entries(spaced)[0].score_rows, entries(history)[0].score_rows)
self.assertIn("Mean", entries(spaced)[0].score_rows)
def test_reads_back_what_it_writes(self):
seats = [Seat("Mid A", said("better", "worse"), ["`bin/a.py:3` `f`: hard, with `:9` `g`"]), Seat("Inherited architect", said("worse", "worse"), [])]
written = {"Mid A": ["same", "worse", "same", "same", "better"], "Inherited architect": ["same", "worse", "same", "same", "worse"]}
scoring = ScoringRun([Seat("Junior A", "", ["`bin/b.py:4` `h`: long"])], {"Junior A": ["7", "6.5", "7", "7", "7"]}, [decimal.Decimal(mean) for mean in ("7.00", "6.50", "7.00", "7.00", "7.00")])
ruled = ruling_entry("2026-10-08T18:37:21Z, PR #2 at bbbbbbb, against aaaaaaa", seats, written, {**written, "Inherited architect": ["same"] * 5}, "worse")
history = appended(appended("", scoring_entry("2026-10-08T12:00:00Z, PR #1 at aaaaaaa", scoring)), ruled)
self.assertTrue(history.startswith("# Comprehension history\n\n## 2026-10-08T12:00:00Z"))
self.assertNotIn("Inherited architect, decided by:", history)
self.assertIn("| Inherited architect | same | same (voted worse, no place naming Locality) | same | same | same (voted worse, naming no place) |", history)
found = entries(history)
self.assertEqual([(entry.commit, entry.against, entry.ruling) for entry in found], [("aaaaaaa", None, None), ("bbbbbbb", "aaaaaaa", "worse")])
self.assertEqual((found[0].scored_places, found[1].ruled_places), ([Place("bin/b.py", "h")], [Place("bin/a.py", "f"), Place("bin/a.py", "g")]))
self.assertTrue(recorded(history, "PR #2 at bbbbbbb, against aaaaaaa"))
self.assertFalse(recorded(history, "PR #2 at bbbbbbb"))
self.assertIn("| Mean | 7.00 | 6.50 | 7.00 | 7.00 | 7.00 |\n\nJunior A, hardest first:", history)
self.assertEqual([entry.paired for entry in found], [False, True])
def test_names_the_places_found_hard_since_the_newest_entry_that_scored_the_project(self):
scored = "## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mean | 7.00 |\n\nJunior A, hardest first:\n\n- `bin/b.py:4` `h`: long\n and wrapped\n\nInherited architect, would restructure first:\n\n- `bin/c.py:1` `k`: tangled\n"
seats = [Seat("Mid A", "", ["Locality, Shape: `bin/a.py:3` `f`: held at once", "Navigation: `README.md:4` \"Tools\": easier to find"]), Seat("Inherited architect", "", ["Locality: `bin/d.py:2` `m`: deep"])]
said = {"Mid A": ["better", "same", "worse", "same", "worse"], "Inherited architect": ["same", "worse", "same", "same", "worse"]}
ruled = ruling_entry("2026-10-10T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa", seats, said, {**said, "Inherited architect": ["same"] * 5}, "same")
older = paired("2026-10-07T12:00:00Z", "worse") + "\n| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | same | worse | same | same | worse |\n\nMid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: old\n"
self.assertIsNone(latest_places(""))
self.assertIsNone(latest_places(appended("", paired("2026-10-07T12:00:00Z", "same"))))
self.assertIsNone(latest_places(appended("", paired("2026-10-07T12:00:00Z", "worse") + "\n| Seat | Vote | Locality |\n|---|---|---|\n| Mid A | same | worse |\n\n- Locality: `bin/k.py:1` `t`: before any label\n\nMid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: old\n")))
unscored = "## 2026-10-11T12:00:00Z, PR #4 at eeeeeee\n\n| Seat | Overall |\n|---|---|\n| Mean | 7.00 |\n"
self.assertIsNone(latest_places(appended(appended("", scored), unscored)))
hard_since = "## 2026-10-10T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nMid A, decided by:\n\n- Locality, Shape: `bin/a.py:3` `f`: held at once\n"
self.assertEqual(latest_places(appended(appended(appended("", older), ruled), scored)), "## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\nJunior A, hardest first:\n\n- `bin/b.py:4` `h`: long\n and wrapped\n\nInherited architect, would restructure first:\n\n- `bin/c.py:1` `k`: tangled\n\n" + hard_since)
self.assertEqual(latest_places(appended(appended("", ruled), older)), "## 2026-10-07T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nMid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: old\n\n" + hard_since)
wrapped = "## 2026-10-09T12:00:00Z, PR #3 at ccccccc\n\nJunior A, hardest first:\n\n an indented line before any bullet\n- `bin/f.py:1` `p`: long,\n like `bin/g.py:2` `q`\n"
calm = paired("2026-10-09T13:00:00Z", "same", "ddddddd") + "\n| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | same | same | same | same | same |\n\nMid A, decided by:\n\n- Locality: `bin/h.py:1` `r`: as before\n"
history = appended(appended(appended("", wrapped), calm), ruled)
self.assertEqual(entries(history)[0].scored_places, [Place("bin/f.py", "p")])
self.assertEqual(latest_places(history), "## 2026-10-09T12:00:00Z, PR #3 at ccccccc\n\nJunior A, hardest first:\n\n- `bin/f.py:1` `p`: long,\n like `bin/g.py:2` `q`\n\n" + hard_since)
fell = ruled.replace("2026-10-10T12:00:00Z", "2026-10-09T12:00:00Z") + "\n| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | 7 | 6 | 7 | 7 | 7 |\n| Mean | 7 | 6 | 7 | 7 | 7 |\n\nJunior A, hardest first:\n\n- `bin/j.py:5` `s`: wide\n"
self.assertEqual(latest_places(appended(appended("", scored), fell)), hard_since.replace("2026-10-10T12:00:00Z", "2026-10-09T12:00:00Z") + "\nJunior A, hardest first:\n\n- `bin/j.py:5` `s`: wide\n")
def test_takes_a_seats_vote_from_the_votes_table_when_it_comes_first(self):
self.assert_votes_table_read(lambda votes, scores: votes + scores)
def test_takes_a_seats_vote_from_the_votes_table_when_it_comes_second(self):
self.assert_votes_table_read(lambda votes, scores: scores + votes)
def assert_votes_table_read(self, tables):
votes = "| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | same | worse | same | same | same |\n"
scores = "| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | 7 | 7 | 7 | 7 | 7 |\n| Mean | 7 | 7 | 7 | 7 | 7 |\n"
places = "Mid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: kept\n- Shape: `bin/f.py:2` `o`: dropped\n"
kept = "## 2026-10-07T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nMid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: kept\n"
self.assertEqual(latest_places(appended("", paired("2026-10-07T12:00:00Z", "worse") + tables(votes, scores) + places)), kept)
def test_keeps_every_bullet_of_a_listing_that_opens_with_a_dimension_voted_worse(self):
votes = "\n| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | same | worse | worse | same | same |\n"
places = "\nMid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: deep\n- Shape: `bin/f.py:2` `o`: wide\n"
expected = "## 2026-10-07T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nMid A, decided by:\n\n- Locality: `bin/e.py:1` `n`: deep\n- Shape: `bin/f.py:2` `o`: wide\n"
self.assertEqual(latest_places(appended("", paired("2026-10-07T12:00:00Z", "worse") + votes + places)), expected)
def test_drops_the_bullets_of_a_seat_with_no_row_in_the_votes_table(self):
votes = "\n| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |\n|---|---|---|---|---|---|\n| Mid A | same | worse | same | same | same |\n"
places = "\nJunior A, decided by:\n\n- Locality: `bin/e.py:1` `n`: deep\n"
self.assertIsNone(latest_places(appended("", paired("2026-10-07T12:00:00Z", "worse") + votes + places)))
def test_names_the_places_of_every_run_on_the_newest_scored_commit(self):
run = "## {time}, {pr} at {commit}\n\nJunior A, hardest first:\n\n- `bin/b.py:{line}` `h`: long\n"
first, rerun, other = (run.format(time=time, pr=pr, commit=commit, line=line) for time, pr, commit, line in (("2026-10-08T12:00:00Z", "PR #1", "aaaaaaa", 1), ("2026-10-08T13:00:00Z", "PR #1 rerun", "aaaaaaa", 2), ("2026-10-09T12:00:00Z", "PR #2", "bbbbbbb", 3)))
self.assertEqual(latest_places(appended(appended("", first), rerun)), first + "\n" + rerun)
self.assertEqual(latest_places(appended(appended(appended("", first), rerun), other)), other)
in_full = rerun.replace("aaaaaaa", "aaaaaaa" + "0" * 33)
self.assertEqual(latest_places(appended(appended("", first), in_full)), first + "\n" + in_full)
def scored(time: str, pr: str, commit: str, mid: str, architect: str) -> str:
"""A scoring run's entry as the history writes it, with the two seats' overall scores."""
run = ScoringRun([], {"Mid A": ["7", "7", "7", "7", mid], "Inherited architect": ["7", "7", "7", "7", architect]}, [decimal.Decimal("7.00")] * 5)
return scoring_entry(f"{time}, {pr} at {commit}", run)
def ruled(time: str, pr: str, mid: str, architect: str, voted: str | None = None) -> str:
"""A paired ruling's entry as the history writes it; `voted` is what Mid A said overall when it counted as `mid`."""
counts = {"Mid A": ["same"] * 4 + [mid], "Inherited architect": ["same"] * 4 + [architect]}
said = {**counts, "Mid A": ["same"] * 4 + [voted or mid]}
return ruling_entry(f"{time}, {pr} at ccccccc, against aaaaaaa", [Seat("Mid A", "", []), Seat("Inherited architect", "", [])], said, counts, "same")
def pairs_of_runs(alike: int, apart: int) -> list[str]:
"""Each pair is two runs on one commit: Mid A and the architect both up, or Mid A up and the architect not moving."""
return [scored(f"2026-10-02T00:{index:02d}:{later}Z", "PR #1 rerun" if later else "PR #1", f"{index:07x}", "7.5" if later else "7", "7.5" if later and index < alike else "7") for index in range(alike + apart) for later in (0, 1)]
class Agreement(unittest.TestCase):
def test_counts_the_rulings_whose_two_seats_voted_alike_overall(self):
old = "## 2026-10-08T18:37:21Z, PR #228 at 2682668, against 8c9bf09\n\nRuling: worse\n\n| Seat | Vote |\n|---|---|\n| Mid A | worse |\n| Inherited architect | worse |\n"
history = "\n".join([ruled("2026-10-01T00:00:00Z", "PR #1", "same", "same"), ruled("2026-10-02T00:00:00Z", "PR #2", "same", "same", voted="worse"), ruled("2026-10-03T00:00:00Z", "PR #3", "worse", "better"), old])
self.assertEqual(ruling_agreement(entries(history)), [True, True, False, True])
def test_compares_the_two_seats_across_the_first_two_runs_on_one_commit(self):
both_up = [scored("2026-10-01T00:00:00Z", "PR #1", "aaaaaaa", "7", "7"), scored("2026-10-02T00:00:00Z", "PR #1 rerun", "aaaaaaa", "7.5", "7.5")]
one_up = [scored("2026-10-03T00:00:00Z", "PR #2", "bbbbbbb", "7", "7"), scored("2026-10-04T00:00:00Z", "PR #2 rerun", "bbbbbbb", "7.5", "7")]
self.assertEqual(run_agreement(entries("\n".join([*both_up, *one_up]))), [True, False])
def test_counts_opposite_moves_and_a_move_against_none_as_different(self):
opposite = [scored("2026-10-01T00:00:00Z", "PR #1", "aaaaaaa", "7", "7"), scored("2026-10-02T00:00:00Z", "PR #1 rerun", "aaaaaaa", "7.5", "6.5")]
down_and_none = [scored("2026-10-03T00:00:00Z", "PR #2", "bbbbbbb", "7", "7"), scored("2026-10-04T00:00:00Z", "PR #2 rerun", "bbbbbbb", "6.5", "7")]
both_down = [scored("2026-10-05T00:00:00Z", "PR #3", "ccccccc", "7", "7"), scored("2026-10-06T00:00:00Z", "PR #3 rerun", "ccccccc", "6.5", "6.5")]
self.assertEqual(run_agreement(entries("\n".join([*opposite, *down_and_none, *both_down]))), [False, False, True])
def test_leaves_out_commits_scored_once_and_runs_of_one_pr_on_different_commits(self):
history = "\n".join([scored("2026-10-01T00:00:00Z", "PR #1", "aaaaaaa", "7", "7"), scored("2026-10-02T00:00:00Z", "PR #1", "bbbbbbb", "7.5", "7.5")])
self.assertEqual(run_agreement(entries(history)), [])
def test_takes_the_two_earliest_runs_of_a_commit_whatever_order_the_file_holds_them(self):
history = "\n".join([scored("2026-10-03T00:00:00Z", "PR #1 again", "aaaaaaa", "6", "7"), scored("2026-10-01T00:00:00Z", "PR #1", "aaaaaaa", "7", "7"), scored("2026-10-02T00:00:00Z", "PR #1 rerun", "aaaaaaa", "7.5", "7.5")])
self.assertEqual(run_agreement(entries(history)), [True])
def test_skips_a_run_whose_table_lists_neither_seat(self):
mean_only = scoring_entry("2026-10-01T12:00:00Z, PR #1 at aaaaaaa", ScoringRun([], {}, [decimal.Decimal("7.00")] * 5))
history = "\n".join([mean_only, scored("2026-10-01T00:00:00Z", "PR #1 rerun", "aaaaaaa", "7", "7"), scored("2026-10-02T00:00:00Z", "PR #1 again", "aaaaaaa", "7.5", "7.5")])
self.assertEqual(run_agreement(entries(history)), [True])
def test_skips_an_entry_listing_one_seat_or_an_empty_overall(self):
one_seat = "## 2026-10-01T00:00:00Z, PR #1 at aaaaaaa, against bbbbbbb\n\nRuling: same\n\n| Seat | Overall |\n|---|---|\n| Mid A | same |\n"
empty = "## 2026-10-02T00:00:00Z, PR #2 at ccccccc, against bbbbbbb\n\nRuling: same\n\n| Seat | Overall |\n|---|---|\n| Mid A | same |\n| Inherited architect | |\n"
self.assertEqual(ruling_agreement(entries("\n".join([one_seat, empty]))), [])
half = "## 2026-10-03T00:00:00Z, PR #3 at ddddddd\n\n| Seat | Overall |\n|---|---|\n| Mid A | 7 |\n"
self.assertEqual(run_agreement(entries("\n".join([half, half.replace("PR #3", "PR #3 rerun").replace("T00:00:00Z", "T01:00:00Z")]))), [])
def test_records_a_rerun_beside_the_run_it_repeats(self):
history = appended("", scored("2026-10-01T00:00:00Z", "PR #1", "aaaaaaa", "7", "7"))
self.assertTrue(recorded(history, "PR #1 at aaaaaaa"))
self.assertFalse(recorded(history, "PR #1 rerun at aaaaaaa"))
def test_gives_no_verdict_before_ten_pairs_of_runs_and_a_ruling(self):
ruling = ruled("2026-10-20T00:00:00Z", "PR #2", "same", "same")
self.assertIn("Unchecked: ", agreement_report("\n".join([*pairs_of_runs(9, 0), ruling])))
self.assertIn("Unchecked: ", agreement_report("\n".join(pairs_of_runs(10, 0))))
def test_holds_when_the_seats_agree_in_a_higher_share_of_rulings_than_of_pairs_of_runs(self):
rulings = [ruled(f"2026-10-20T00:00:0{index}Z", f"PR #{index + 2}", "same", "same") for index in range(3)]
report = agreement_report("\n".join([*pairs_of_runs(5, 5), *rulings]))
self.assertEqual(report.split(":")[0], "Assumption holds")
self.assertIn("3 of 3 paired rulings", report)
self.assertIn("5 of 10 pairs", report)
def test_fails_when_the_two_shares_are_equal(self):
rulings = [ruled("2026-10-20T00:00:00Z", "PR #2", "same", "same"), ruled("2026-10-20T00:00:01Z", "PR #3", "worse", "same")]
self.assertEqual(agreement_report("\n".join([*pairs_of_runs(5, 5), *rulings])).split(":")[0], "Assumption fails")
def test_fails_when_the_seats_agree_in_a_lower_share_of_rulings_than_of_pairs_of_runs(self):
rulings = [ruled("2026-10-20T00:00:00Z", "PR #2", "same", "same"), ruled("2026-10-20T00:00:01Z", "PR #3", "same", "same"), ruled("2026-10-20T00:00:02Z", "PR #4", "worse", "same")]
self.assertEqual(agreement_report("\n".join([*pairs_of_runs(8, 2), *rulings])).split(":")[0], "Assumption fails")
class Decided(unittest.TestCase):
AT = 1_700_000_000.0
HISTORY = (MemoryStore(label="history.md"), "")
def test_heads_the_entry_with_the_time_it_is_given(self):
decided_on = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, self.HISTORY)
self.assertEqual(decided_on, (comprehension_history.Heading("2023-11-14T22:13:20Z, PR #2 at abcdef1", "PR #2", "abcdef1", None), SeatsFile("PR #2 at abcdef1", [])))
def test_fails_on_a_commit_the_check_denies_and_names_only_that_commit(self):
named = "PR #2 at abcdef1, against 1234567\n"
self.assertEqual(decided(named, self.AT, True, lambda commit: commit == "abcdef1", self.HISTORY), Failure("the seats file names 1234567, which is no commit in this checkout"))
self.assertEqual(decided(named, self.AT, True, lambda commit: commit == "1234567", self.HISTORY), Failure("the seats file names abcdef1, which is no commit in this checkout"))
self.assertEqual(decided(named, self.AT, True, lambda commit: False, self.HISTORY), Failure("the seats file names abcdef1, 1234567, which is no commit in this checkout"))
def test_fails_where_the_history_already_holds_an_entry_on_the_file(self):
held = scored("2023-11-14T22:13:20Z", "PR #2", "abcdef1", "7", "7")
failed = decided("PR #2 at abcdef1\n", self.AT, False, lambda commit: True, (MemoryStore(label="history.md"), appended("", held)))
self.assertEqual(failed, Failure("history.md already holds an entry on PR #2 at abcdef1; record each ruling or run once"))
def test_fails_on_a_seats_file_that_does_not_parse_without_asking_about_a_commit(self):
failed = decided("", self.AT, False, lambda commit: self.fail("asked"), self.HISTORY)
self.assertEqual(failed, Failure("the seats file is empty; its first line names what the seats read: <PR or branch> at <commit>"))
class Base(unittest.TestCase):
def test_takes_the_newest_change_adding_an_entry(self):
older = HistoryChange("old", "", SCORING)
same = HistoryChange("same", SCORING, SCORING + paired("2026-10-08T13:00:00Z", "same"))
self.assertEqual(measured_commit([same, older]), "same")
worse = HistoryChange("worse", SCORING, SCORING + paired("2026-10-08T14:00:00Z", "worse"))
self.assertEqual(measured_commit([worse, older]), "worse")
self.assertEqual(measured_commit([HistoryChange("none", SCORING, SCORING + "\nAn edit outside any entry.\n"), older]), "old")
self.assertIsNone(measured_commit([HistoryChange("none", SCORING, SCORING)]))
class ScoringRunDue(unittest.TestCase):
def test_reads_each_rows_id_release_and_tagline(self):
self.assertEqual(items(todo("| 3 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")), [item(3, (0, 1, 0))])
self.assertEqual(items("# todo\n"), NoItemsTable("todo.md holds no items table"))
self.assertIsInstance(items("# todo\n"), Failure)
self.assertIsInstance(items(todo("| 0 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")), Failure)
def test_is_not_due_for_an_item_whose_tagline_only_mentions_the_floor(self):
plan = [item(1, (0, 1, 0), "**Call a scoring run for an item whose tagline makes the comprehension floor its target.**"), item(2, (0, 1, 0))]
self.assertEqual(scoring_run_due(plan, plan, [1], (0, 1, 0), set()), [])
def test_is_due_for_a_floor_item(self):
plan = [item(1, (0, 1, 0), "**Reach the comprehension floor: lift the project.**"), item(2, (0, 1, 0))]
self.assertEqual(scoring_run_due(plan, plan, [1], (0, 1, 0), set()), ["ships item 1, a floor item"])
self.assertIsInstance(scoring_run_due(plan, plan, [9], (0, 1, 0), set()), Failure)
def test_is_due_when_the_chunk_ships_a_releases_last_item(self):
plan = [item(1, (0, 1, 0)), item(2, (0, 2, 0))]
self.assertEqual(scoring_run_due(plan, plan, [1], None, set()), ["leaves release 0.1.0 with no plan item"])
self.assertEqual(scoring_run_due(plan, plan + [item(3, (0, 1, 0))], [1], (0, 1, 0), set()), [])
def test_is_due_when_the_chunk_removes_the_next_releases_last_item_after_work_landed(self):
before = [item(1, (0, 1, 0)), item(2, (0, 1, 0)), item(3, (0, 2, 0))]
after = [item(2, (0, 1, 0)), item(3, (0, 2, 0))]
self.assertEqual(scoring_run_due(before, after, [2], (0, 1, 0), set()), ["leaves release 0.1.0 with no plan item"])
self.assertEqual(scoring_run_due(before, after, [], (0, 1, 0), set()), [])
emptied = [item(3, (0, 2, 0))]
self.assertEqual(scoring_run_due(before, emptied, [2], None, set()), ["leaves release 0.1.0 with no plan item"])
self.assertEqual(scoring_run_due(before, emptied, [], (0, 1, 0), set()), ["leaves release 0.1.0 with no plan item"])
self.assertEqual(scoring_run_due(before, emptied, [], None, set()), [])
def test_is_not_due_when_the_chunk_marks_the_next_release_renamed(self):
before = [item(1, (0, 2, 1)), item(2, (0, 3, 0))]
renamed = {(0, 2, 1)}
self.assertEqual(scoring_run_due(before, [item(1, (0, 3, 0)), item(2, (0, 4, 0))], [], (0, 2, 1), renamed), [])
self.assertEqual(scoring_run_due(before, [item(1, (0, 3, 0)), item(2, (0, 3, 0))], [], (0, 2, 1), renamed), [])
dropped = [item(1, (0, 2, 1)), item(3, (0, 2, 1)), item(2, (0, 3, 0))]
self.assertEqual(scoring_run_due(dropped, [item(1, (0, 3, 0)), item(2, (0, 3, 0))], [], (0, 2, 1), renamed), [])
def test_is_due_when_the_chunk_defers_the_next_releases_last_items_unmarked(self):
before = [item(1, (0, 2, 1)), item(2, (0, 3, 0))]
self.assertEqual(scoring_run_due(before, [item(1, (0, 3, 0)), item(2, (0, 3, 0))], [], (0, 2, 1), set()), ["leaves release 0.2.1 with no plan item"])
def test_words_the_emptied_release_reason_as_skill_md_s_second_run_quotes_it(self):
skill = (pathlib.Path(__file__).resolve().parents[2] / "skills" / "larv-review" / "SKILL.md").read_text()
self.assertIn("`leaves release … with no plan item`", skill)
reasons = scoring_run_due([item(1, (0, 1, 0))], [], [], (0, 1, 0), set())
self.assertRegex(reasons[0], r"^leaves release [0-9.]+ with no plan item$")
def test_is_not_due_when_a_later_release_loses_its_last_item_unshipped(self):
before = [item(1, (0, 1, 0)), item(3, (0, 2, 0))]
self.assertEqual(scoring_run_due(before, before[:1], [], (0, 1, 0), set()), [])
class LandedTowards(unittest.TestCase):
def test_names_the_next_release_only_where_a_change_is_unreleased(self):
plan = [item(1, (0, 2, 0))]
changelog = "# Changelog\n\n## Unreleased\n\n- Did a thing.\n"
self.assertEqual(landed_towards(plan, LastCut("v0.1.0", changelog, 0, [])), (0, 2, 0))
self.assertEqual(landed_towards(plan, LastCut("v0.1.0", "# Changelog\n\n## Unreleased\n", 3, [])), None)
self.assertEqual(landed_towards(plan, LastCut("v0.1.0", "", 3, [])), (0, 2, 0))
self.assertEqual(landed_towards(plan, LastCut(None, "", 0, [])), None)
def test_names_no_release_where_the_plan_files_items_under_the_last_cut_or_names_none_after_it(self):
changelog = "# Changelog\n\n## Unreleased\n\n- Did a thing.\n"
self.assertIsNone(landed_towards([item(1, (0, 1, 0))], LastCut("v0.1.0", changelog, 0, [])))
self.assertIsNone(landed_towards([], LastCut("v0.1.0", changelog, 0, [""])))
def test_names_the_next_release_where_the_plan_holds_no_item_for_it(self):
named = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n| 1 | 0.2.0 | | | **Do 1.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10.0 |\n"
changelog = "# Changelog\n\n## Unreleased\n\n- Did a thing.\n"
self.assertEqual(landed_towards([item(2, (0, 3, 0))], LastCut("v0.1.0", changelog, 0, [f"## Items\n\n{named}"])), (0, 2, 0))
def test_fails_where_the_changes_or_the_next_release_cannot_be_read(self):
plan = [item(1, (0, 2, 0))]
self.assertIsInstance(landed_towards(plan, LastCut("v0.1.0", Failure("unreadable"), Failure("count unreadable"), [])), Failure)
self.assertIsInstance(landed_towards([], LastCut("v0.1.0", "", 3, Failure("log unreadable"))), Failure)
self.assertEqual(landed_towards(plan, LastCut(Failure("fatal: bad object"), "", 3, [])), Failure("could not tell the next release: the default branch's tags cannot be read: fatal: bad object"))
class AppendedTo(unittest.TestCase):
def test_writes_the_entry_over_the_version_the_history_was_read_at(self):
history = MemoryStore(label="history.md", version=5)
self.assertEqual(appended_to(history, Held("", "5"), "PR #2 at abcdef1\n", "## an entry\n"), "Appended to history.md.")
self.assertEqual(history.overs, ["5"])
class Shortfall(unittest.TestCase):
def test_skill_md_names_the_words_that_end_the_reason_a_release_empties(self):
self.assertIn(EMPTIED_WORDS, (pathlib.Path(__file__).resolve().parents[2] / "skills" / "larv-review" / "SKILL.md").read_text(encoding="utf-8"))
def test_a_chunk_that_empties_a_release_owes_two_runs_and_any_other_reason_one(self):
emptied = [Emptied("leaves release 0.1.0 with no plan item")]
floor = ["ships item 2, a floor item"]
# The type, not the words, makes a reason call two runs.
self.assertIn("owes 1 scoring run and", shortfall(["leaves release 0.1.0 with no plan item"], 0).reason)
self.assertIsInstance(scoring_run_due([item(1, (0, 1, 0))], [], [], (0, 1, 0), set())[0], Emptied)
self.assertIn("owes 2 scoring runs and the branch's committed history records 1", shortfall(emptied + floor, 1).reason)
self.assertIn("owes 1 scoring run and", shortfall(floor, 0).reason)
self.assertIn("records 0:", shortfall(floor, -1).reason)
self.assertIsNone(shortfall(emptied, 2))
self.assertIsNone(shortfall(floor, 1))
PROJECT_CONFIG = """checkout = "~/proj"
plan = "checkout:todo.md"
working-rules = "checkout:AGENTS.md"
decisions = "checkout:docs/decisions.md"
score-anchors = "checkout:docs/score-anchors.md"
comprehension-history = "checkout:docs/comprehension-history.md"
reading-cost = "checkout:docs/reading-cost.md"
changelog = "checkout:CHANGELOG.md"
goals-and-audience = "checkout:README.md"
principles = "~/principles"
standards = "~/standards"
"""
class LarvReviewTool(unittest.TestCase):
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
root = pathlib.Path(os.path.realpath(temp.name))
self.env = {**isolated_env(), "GIT_CONFIG_GLOBAL": os.devnull, "HOME": str(root)}
self.checkout = root / "proj"
subprocess.run(["git", "init", "-q", "--bare", "-b", "main", str(root / "origin.git")], check=True, env=self.env)
subprocess.run(["git", "clone", "-q", str(root / "origin.git"), str(self.checkout)], check=True, env=self.env, capture_output=True)
self.commit("start", {"todo.md": todo("| 1 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 2 | 0.2.0 | | **Then this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")})
self.git("push", "-q", "origin", "HEAD:main")
self.git("remote", "set-head", "origin", "main")
self.git("switch", "-q", "-c", "chunk")
self.start = self.git("rev-parse", "--short", "HEAD").strip()
self.config = root / ".claude-projects" / "proj" / "config.toml"
self.config.parent.mkdir(parents=True)
self.config.write_text(PROJECT_CONFIG)
(root / "principles").mkdir()
(root / "principles" / "technical-principles.md").write_text("# Principles\n")
(root / "standards").mkdir()
(root / "standards" / "quality.md").write_text("# Quality\n")
def git(self, *args):
return subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], cwd=self.checkout, check=True, env=self.env, capture_output=True, text=True).stdout
def commit(self, title, files=None):
for name, text in (files or {}).items():
(self.checkout / name).parent.mkdir(parents=True, exist_ok=True)
(self.checkout / name).write_text(text)
self.git("add", name)
self.git("commit", "-q", "--allow-empty", "-m", title)
def run_tool(self, *args, cwd=None):
return subprocess.run([sys.executable, str(TOOL), *args], capture_output=True, cwd=cwd or self.checkout, env=self.env, text=True)
def seats_file(self, text, name="seats.md"):
path = self.checkout.parent / name
path.write_text(textwrap.dedent(text))
return str(path)
def test_takes_the_merge_base_until_a_merged_change_records_an_entry_and_finds_it_from_a_subfolder(self):
start = self.git("rev-parse", "HEAD").strip()
self.commit("work")
ran = self.run_tool("ruling-base")
self.assertEqual((ran.returncode, ran.stdout.splitlines()[0]), (0, start), ran.stderr)
self.git("switch", "-q", "-c", "measured", "main")
self.commit("Merge a scoring run", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING})
self.git("push", "-q", "origin", "HEAD:main")
measured = self.git("rev-parse", "HEAD").strip()
self.commit("Fix a typo", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING + "\nA note.\n"})
self.git("push", "-q", "origin", "HEAD:main")
self.git("switch", "-q", "chunk")
self.assertEqual(self.run_tool("ruling-base").stdout.splitlines()[0], measured)
(self.checkout / "docs").mkdir(exist_ok=True)
self.assertEqual(self.run_tool("ruling-base", cwd=self.checkout / "docs").stdout.splitlines()[0], measured)
def test_counts_rounds_on_this_branch_alone(self):
self.commit("Answer stability round 1: a")
self.commit("Answer stability round 2: b")
self.commit("Answer prose round 1: c")
ran = self.run_tool("round-count")
self.assertIn("stability: 2, at the cap: no more rounds\n", ran.stdout)
self.commit("Answer stability round 3: d")
self.assertIn("stability: 3, past the cap: no more rounds\n", self.run_tool("round-count").stdout)
self.assertIn("prose: 1\n", ran.stdout)
self.assertIn("architecture: 0\n", ran.stdout)
def test_leaves_out_the_round_commits_of_a_branch_merged_in_as_the_hook_does(self):
self.git("switch", "-q", "-c", "sibling")
self.commit("Answer stability round 1: a")
self.commit("Answer stability round 2: b")
self.git("switch", "-q", "chunk")
self.git("merge", "-q", "--no-ff", "-m", "Merge sibling", "sibling")
self.assertIn("stability: 0\n", self.run_tool("round-count").stdout)
def test_says_whether_a_scoring_run_is_due_and_refuses_an_unknown_item(self):
self.assertEqual(self.run_tool("needs-scoring-run", "1").stdout, "Scoring run due: the chunk leaves release 0.1.0 with no plan item.\n")
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "No scoring run due.\n")
unknown = self.run_tool("needs-scoring-run", "9")
self.assertEqual(unknown.returncode, 1)
self.assertIn("item 9", unknown.stderr)
self.assertEqual(self.run_tool("needs-scoring-run").stdout, "No scoring run due.\n")
self.assertIn("todo.md's ID column", self.run_tool("needs-scoring-run", "item-85").stderr)
def test_a_scoring_run_that_a_release_ending_chunk_owes_is_refused_until_the_branch_records_two(self):
rest = ("| 2 | 0.2.0 | | **Then this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")
self.commit("Ship item 1", {"todo.md": todo(*rest)})
owed = self.run_tool("scoring-run-owed")
self.assertEqual(owed.returncode, 1)
self.assertIn("leaves release 0.1.0 with no plan item", owed.stderr)
self.assertIn("records 0:", owed.stderr)
history = "# Comprehension history\n\n" + SCORING
self.commit("Record a run", {"docs/comprehension-history.md": history})
self.assertIn("records 1:", self.run_tool("scoring-run-owed").stderr)
self.commit("Record a rerun", {"docs/comprehension-history.md": history + "\n" + SCORING.replace("PR #1 at", "PR #1 rerun at")})
done = self.run_tool("scoring-run-owed")
self.assertEqual((done.returncode, done.stdout), (0, "No scoring run owed.\n"), done.stderr)
def test_a_scoring_run_the_floor_calls_is_owed_once(self):
row = "| 1 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"
other = "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"
self.commit("Plan the floor item", {"todo.md": todo(row, "| 2 | 0.2.0 | | **Reach the comprehension floor: do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", other)})
self.git("push", "-q", "origin", "HEAD:main")
self.commit("Ship it", {"todo.md": todo(row, other)})
self.assertIn("a floor item", self.run_tool("scoring-run-owed").stderr)
self.commit("Record a run", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING})
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 0)
def test_plan_reasons_reads_the_plan_and_the_decisions_where_the_config_puts_them_outside_the_checkout(self):
# In this process, where the mutation tests see it: they leave out a test that starts the tool.
self.config.write_text(PROJECT_CONFIG.replace("checkout:todo.md", "folder:todo.md").replace("checkout:docs/decisions.md", "folder:decisions.md"))
row = "| 1 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"
(self.config.parent / "todo.md").write_text(todo(row, "| 2 | 0.2.0 | | **Reach the comprehension floor: do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"))
self.addCleanup(os.chdir, os.getcwd())
os.chdir(self.checkout)
home = self.config.parents[2]
self.assertEqual(plan_reasons("origin/main", [2], home), ["ships item 2, a floor item", "leaves release 0.2.0 with no plan item"])
(self.config.parent / "decisions.md").write_text("# Decisions\n\n## review opt-out: the comprehension check\n\nServes goal 1.\n")
self.assertEqual(plan_reasons("origin/main", [2], home), [])
(self.config.parent / "decisions.md").unlink()
gone = plan_reasons("origin/main", [1, 7], home)
assert isinstance(gone, Failure), gone
self.assertEqual(gone.reason, f"the plan as it stands holds no item 7, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {self.config.parent}/todo.md")
(self.config.parent / "todo.md").write_bytes(b"\xff")
unreadable = plan_reasons("origin/main", [2], home)
assert isinstance(unreadable, Failure), unreadable
self.assertEqual(unreadable.reason, f"the project's plan: {self.config.parent}/todo.md: not UTF-8")
ROW = "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"
def ship_item_1(self):
self.commit("Ship item 1", {"todo.md": todo(self.ROW)})
def test_no_scoring_run_is_owed_where_none_is_due(self):
self.commit("Ship item 2", {"todo.md": todo("| 1 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", self.ROW)})
self.assertEqual(self.run_tool("scoring-run-owed").stdout, "No scoring run owed.\n")
self.ship_item_1()
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 1)
def test_a_run_counts_only_as_committed_and_a_ruling_is_no_run(self):
self.ship_item_1()
(self.checkout / "docs").mkdir()
(self.checkout / "docs" / "comprehension-history.md").write_text("# Comprehension history\n\n" + SCORING)
self.assertIn("records 0", self.run_tool("scoring-run-owed").stderr)
self.commit("Record a ruling", {"docs/comprehension-history.md": "# Comprehension history\n\n" + paired("2026-10-08T12:00:00Z", "better")})
self.assertIn("records 0", self.run_tool("scoring-run-owed").stderr)
def test_a_project_that_opts_out_owes_none_and_is_never_due_one_but_a_branch_cannot_opt_itself_out(self):
self.ship_item_1()
self.commit("Opt out on the branch", {"docs/decisions.md": "## review opt-out: the comprehension check\n\n2026-11-10, lilleman.\n"})
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 1)
self.git("switch", "-q", "main")
self.commit("Opt out", {"docs/decisions.md": "## review opt-out: the comprehension check\n\n2026-11-10, lilleman.\n"})
self.git("push", "-q", "origin", "HEAD:main")
self.git("switch", "-q", "chunk")
self.git("merge", "-q", "main")
self.assertEqual(self.run_tool("scoring-run-owed").stdout, "No scoring run owed.\n")
self.assertEqual(self.run_tool("needs-scoring-run", "1").stdout, "No scoring run due.\n")
def test_reads_the_plan_and_the_history_from_the_folders_of_the_checkout_the_config_names(self):
self.config.write_text(PROJECT_CONFIG.replace("checkout:todo.md", "checkout:plan/todo.md").replace("checkout:docs/comprehension-history.md", "checkout:records/comprehension-history.md"))
rest = ("| 2 | 0.2.0 | | **Then this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")
self.commit("Move the plan", {"plan/todo.md": (self.checkout / "todo.md").read_text()})
self.git("push", "-q", "origin", "HEAD:main")
self.git("fetch", "-q", "origin")
self.commit("Ship item 1", {"plan/todo.md": todo(*rest), "todo.md": "the owners' own notes\n"})
self.assertIn("records 0:", self.run_tool("scoring-run-owed").stderr)
history = "# Comprehension history\n\n" + SCORING
self.commit("Record both runs", {"records/comprehension-history.md": history + "\n" + SCORING.replace("PR #1 at", "PR #1 rerun at")})
done = self.run_tool("scoring-run-owed")
self.assertEqual((done.returncode, done.stdout), (0, "No scoring run owed.\n"), done.stderr)
def test_a_history_outside_the_checkout_owes_none_and_has_no_ruling_base_each_saying_it_is_not_supported(self):
self.config.write_text(PROJECT_CONFIG.replace("checkout:docs/comprehension-history.md", "folder:comprehension-history.md"))
self.ship_item_1()
outside = self.config.parent / "comprehension-history.md"
owed = self.run_tool("scoring-run-owed")
self.assertEqual((owed.returncode, owed.stdout), (0, "No scoring run owed.\n"))
self.assertEqual(owed.stderr, f"larv-review doesn't support a comprehension history outside the checkout, so it cannot tell whether the chunk owes a scoring run: {outside}\n")
base = self.run_tool("ruling-base")
self.assertEqual((base.returncode, base.stdout), (1, ""))
self.assertIn(f"larv-review doesn't support a comprehension history outside the checkout: no commit holds {outside}", base.stderr)
def test_a_plan_outside_the_checkout_owes_none_saying_it_is_not_supported_whatever_the_chunk_shipped(self):
self.config.write_text(PROJECT_CONFIG.replace("checkout:todo.md", "folder:todo.md"))
plan = self.config.parent / "todo.md"
plan.write_text((self.checkout / "todo.md").read_text())
self.assertEqual(self.run_tool("needs-scoring-run", "1").stdout, "Scoring run due: the chunk leaves release 0.1.0 with no plan item.\n")
plan.write_text(todo(self.ROW))
self.commit("Ship item 1")
owed = self.run_tool("scoring-run-owed")
self.assertEqual((owed.returncode, owed.stdout), (0, "No scoring run owed.\n"))
self.assertEqual(owed.stderr, f"larv-review doesn't support a plan outside the checkout, so it cannot tell whether the chunk owes a scoring run: {plan}\n")
def test_a_project_with_no_plan_or_no_items_table_owes_none(self):
self.ship_item_1()
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 1)
self.commit("Reshape the plan", {"todo.md": "# Plan\n"})
self.assertEqual(self.run_tool("scoring-run-owed").stdout, "No scoring run owed.\n")
self.git("rm", "-q", "todo.md")
self.commit("Drop the plan")
self.assertEqual(self.run_tool("scoring-run-owed").stdout, "No scoring run owed.\n")
(self.checkout / "todo.md").write_bytes(b"\xff\xfe")
self.git("add", "todo.md")
self.commit("Break the plan")
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 1, "a plan that can't be read is no plan the gate may skip")
def test_a_default_branch_that_moved_on_since_the_branch_began_adds_no_owed_run(self):
self.git("switch", "-q", "main")
self.commit("Plan release 0.3.0", {"todo.md": todo("| 1 | 0.1.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 2 | 0.2.0 | | **Then this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", self.ROW, "| 4 | 0.3.0 | | **Later.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |"), "docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING})
self.git("push", "-q", "origin", "HEAD:main")
self.git("switch", "-q", "chunk")
self.commit("Do some work")
self.assertEqual(self.run_tool("needs-scoring-run").stdout, "No scoring run due.\n")
self.assertEqual(self.run_tool("scoring-run-owed").stdout, "No scoring run owed.\n")
self.ship_item_1()
self.commit("Ship item 1 and record a run", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING.replace("PR #1", "PR #7")})
self.assertIn("owes 2 scoring runs and the branch's committed history records 1:", self.run_tool("scoring-run-owed").stderr, "main's own run is no credit to the branch")
def release(self, tag, date, files=None):
"""Cut tag on the default branch at a commit dated date."""
self.env["GIT_COMMITTER_DATE"] = date
self.addCleanup(self.env.pop, "GIT_COMMITTER_DATE", None)
self.commit(f"Release {tag}", files)
self.git("tag", tag)
self.git("push", "-q", "origin", "HEAD:main")
def test_a_release_cut_with_no_scoring_run_since_the_one_before_it_calls_one_and_a_later_run_ends_that(self):
self.release("v0.0.1", "2026-10-09T12:00:00Z")
self.release("v0.0.2", "2026-10-20T12:00:00Z", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING})
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "Scoring run due: the chunk follows v0.0.2, cut with no scoring run since v0.0.1.\n")
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 1)
self.commit("Record a run", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING + "\n" + SCORING.replace("PR #1 at", "PR #2 at")})
self.assertEqual(self.run_tool("scoring-run-owed").returncode, 0)
self.release("v0.0.3", "2026-10-21T12:00:00Z", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING.replace("2026-10-08T12", "2026-10-20T18")})
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "No scoring run due.\n")
def test_a_run_ends_an_unmeasured_release_only_when_it_is_a_scoring_run_newer_than_the_tag_with_a_time_that_reads(self):
self.release("v0.0.1", "2026-10-09T12:00:00Z")
history = "# Comprehension history\n\n"
due = "Scoring run due: the chunk follows v0.0.2, cut with no scoring run since v0.0.1.\n"
self.release("v0.0.2", "2026-10-20T12:00:00Z", {"docs/comprehension-history.md": history + paired("2026-10-21T12:00:00Z", "better") + "\n" + SCORING.replace("2026-10-08T12:00:00Z", "2026-10-09T12:00:00Z")})
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, due, "a ruling, and a run at the earlier tag's own second, don't end anything")
self.release("v0.0.3", "2026-10-21T12:00:00Z", {"docs/comprehension-history.md": history + SCORING.replace("2026-10-08T12:00:00Z", "2026-10-30")})
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, due.replace("v0.0.2", "v0.0.3").replace("v0.0.1", "v0.0.2"), "a run whose time doesn't parse doesn't end anything")
def test_an_unmeasured_release_is_judged_by_the_default_branch_alone_and_names_a_release_over_its_candidate(self):
self.release("v0.0.1", "2026-10-09T12:00:00Z")
self.release("v0.0.2-rc.1", "2026-10-10T12:00:00Z")
self.release("v0.0.2", "2026-10-20T12:00:00Z")
self.git("switch", "-q", "-c", "side")
self.commit("Tag a side branch")
self.git("tag", "v0.9.0")
self.git("switch", "-q", "chunk")
self.commit("Record a run on the branch", {"docs/comprehension-history.md": "# Comprehension history\n\n" + SCORING.replace("2026-10-08T12", "2026-10-25T12")})
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "Scoring run due: the chunk follows v0.0.2, cut with no scoring run since v0.0.2-rc.1.\n")
def test_one_release_alone_calls_no_scoring_run_for_lacking_one(self):
self.release("v0.0.1", "2026-10-09T12:00:00Z")
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "No scoring run due.\n")
def test_calls_a_scoring_run_for_a_deferred_release_and_none_for_one_the_checkouts_plan_marks_renamed(self):
rows = ("| 1 | 0.2.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 2 | 0.2.0 | | **Then this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")
self.commit("Move 0.1.0's item to 0.2.0", {"todo.md": todo(*rows)})
self.assertEqual(self.run_tool("needs-scoring-run").stdout, "Scoring run due: the chunk leaves release 0.1.0 with no plan item.\n")
self.commit("Mark 0.1.0 renamed", {"todo.md": todo(*rows) + "\n## Renamed\n\n- 0.1.0 renamed to 0.2.0\n"})
self.assertEqual(self.run_tool("needs-scoring-run").stdout, "No scoring run due.\n")
def test_counts_work_landed_from_the_changelogs_unreleased_entries_where_it_has_that_section(self):
self.git("tag", "v0.0.1")
self.commit("Commit after the tag", {"CHANGELOG.md": "# Changelog\n\n## Unreleased\n\n## 0.0.1\n"})
self.git("push", "-q", "origin", "HEAD:main")
rows = ("| 1 | 0.2.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 2 | 0.2.0 | | **Then this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |", "| 3 | 0.2.0 | | **And this.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |")
self.commit("Move 0.1.0's item to 0.2.0 and log a change", {"todo.md": todo(*rows), "CHANGELOG.md": "# Changelog\n\n## Unreleased\n\n- The chunk's own change.\n\n## 0.0.1\n"})
self.assertEqual(self.run_tool("needs-scoring-run").stdout, "No scoring run due.\n")
self.git("reset", "-q", "--hard", "HEAD~1")
self.commit("Log a change", {"CHANGELOG.md": "# Changelog\n\n## Unreleased\n\n- Did a thing.\n\n## 0.0.1\n"})
self.git("push", "-q", "origin", "HEAD:main")
self.commit("Move 0.1.0's item to 0.2.0", {"todo.md": todo(*rows)})
self.assertEqual(self.run_tool("needs-scoring-run").stdout, "Scoring run due: the chunk leaves release 0.1.0 with no plan item.\n")
def test_refuses_where_the_default_branchs_unreleased_changes_cannot_be_read(self):
self.addCleanup(os.chdir, os.getcwd())
os.chdir(self.checkout)
self.assertIsInstance(plan_reasons("no-such-ref", [], pathlib.Path.home()), Failure)
def test_refuses_a_checkout_plan_whose_renamed_section_does_not_parse(self):
self.commit("Break the mark", {"todo.md": todo("| 1 | 0.2.0 | | **Do it.** | 1 | 1 | 3 | 1 | 1 | 1 | 9.0 |") + "\n## Renamed\n\nsoon\n"})
broken = self.run_tool("needs-scoring-run")
self.assertEqual(broken.returncode, 1)
self.assertIn("## Renamed", broken.stderr)
def test_reads_a_default_branch_plan_without_a_table_as_empty_and_refuses_a_checkout_without_one(self):
self.git("switch", "-q", "-c", "reshape", "main")
self.commit("Plan as a list", {"todo.md": "# todo\n\n- [ ] Do it.\n"})
self.git("push", "-q", "origin", "HEAD:main")
self.git("switch", "-q", "chunk")
self.assertEqual(self.run_tool("needs-scoring-run", "2").returncode, 0)
(self.checkout / "todo.md").write_text("# todo\n")
ran = self.run_tool("needs-scoring-run", "2")
self.assertEqual(ran.returncode, 1)
self.assertIn("the project's plan: ", ran.stderr)
def test_records_a_ruling_once_four_seats_settle_a_split(self):
lines = """\
PR #2 at {start}, against {start}
Mid A: {worse}
- Overall: `bin/a.py:3` `f`: three branches
Inherited architect: {same}
"""
lines = lines.replace("{start}", self.start).replace("{worse}", said("worse")).replace("{same}", said("same"))
split = self.run_tool("record-ruling", self.seats_file(lines))
self.assertEqual(split.returncode, 0, split.stderr)
self.assertTrue(split.stdout.startswith("Split: Mid A worse, Inherited architect same."))
history = self.checkout / "docs" / "comprehension-history.md"
self.assertFalse(history.exists())
lines += f"\n\t\t\tMaintainability senior: {said('worse')}\n\n\t\t\t- Overall: `bin/a.py:3` `f`: hard\n\n\t\t\tJunior A: {said('worse')}\n"
ran = self.run_tool("record-ruling", self.seats_file(lines))
self.assertEqual(ran.stdout.splitlines()[0], "Ruling: same. Overall votes as counted: Mid A worse, Inherited architect same, Maintainability senior worse, Junior A same (voted worse, naming no place).")
recorded = entries(history.read_text())
self.assertEqual([(entry.commit, entry.against, entry.ruling) for entry in recorded], [(self.start, self.start, "same")])
self.assertEqual(recorded[0].ruled_places, [Place("bin/a.py", "f")] * 2)
self.assertIn("| Junior A | same | same | same | same | same (voted worse, naming no place) |", history.read_text())
def test_refuses_the_other_seats_lines_once_the_first_two_agree_overall(self):
lines = f"PR #2 at {self.start}, against {self.start}\n\n" + "\n".join(f"{seat}: {said('worse')}\n\n- Overall: `bin/a.py:3` `f`: hard\n" for seat in ("Mid A", "Inherited architect", "Maintainability senior", "Junior A"))
ran = self.run_tool("record-ruling", self.seats_file(lines))
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn("both count as worse overall, which settles the ruling; drop the other seats' lines", ran.stderr)
self.assertFalse((self.checkout / "docs" / "comprehension-history.md").exists())
def test_records_a_ruling_whose_dimension_fell_and_takes_no_scores_file(self):
place = "\n\n- Locality, Overall: `bin/a.py:3` `f`: shorter\n\n"
votes_file = self.seats_file(f"PR #2 at {self.start}, against {self.start}\n\nMid A: {said('better', 'worse')}{place}Inherited architect: {said('better', 'worse')}{place}", "votes.md")
extra = self.run_tool("record-ruling", votes_file, votes_file)
self.assertEqual(extra.returncode, 1)
self.assertIn("unknown arguments", extra.stderr)
ran = self.run_tool("record-ruling", votes_file)
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertTrue(ran.stdout.startswith("Ruling: better. Overall votes as counted:"))
self.assertTrue(ran.stdout.endswith(f"\nAppended to {self.checkout / 'docs' / 'comprehension-history.md'}.\n"), ran.stdout)
again = self.run_tool("record-ruling", votes_file)
self.assertEqual((again.returncode, again.stdout), (1, ""))
self.assertIn("already holds an entry on", again.stderr)
self.assertEqual([entry.ruling for entry in entries((self.checkout / "docs" / "comprehension-history.md").read_text())], ["better"])
def test_leaves_a_history_it_cannot_read_as_it_is(self):
history = self.checkout / "docs" / "comprehension-history.md"
history.parent.mkdir(exist_ok=True)
history.write_bytes(b"# Comprehension history\n\xff\n")
votes_file = self.seats_file(f"PR #2 at {self.start}, against {self.start}\n\nMid A: {said('better')}\n\nInherited architect: {said('better')}\n", "votes.md")
ran = self.run_tool("record-ruling", votes_file)
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn(f"cannot read {history}: not UTF-8 on line 2", ran.stderr)
self.assertEqual(history.read_bytes(), b"# Comprehension history\n\xff\n")
def test_holds_a_scoring_run_to_the_readability_floor_the_config_sets(self):
line = "Navigation 7, Locality 6.5, Shape 7, Self-sufficiency 6.5, Overall 7"
seats = "".join(f"\n{seat}: {line}\n\n- `bin/a.py:3` `f`: long\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
self.plan()
self.config.write_text(PROJECT_CONFIG + "readability-floor = 6.5\n")
ran = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("\nMeans: ", ran.stdout)
self.assertNotIn("Floor:", ran.stdout)
self.config.write_text(PROJECT_CONFIG + "readability-floor = 6.8\n")
ran = self.run_tool("record-scoring", self.seats_file(f"PR #3 at {self.start}\n" + seats), "1")
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("\nFloor: Locality 6.50, Self-sufficiency 6.50 under the floor of 6.8.\nNext: file one floor item,", ran.stdout)
self.assertIn("until every mean reaches 6.8,", ran.stdout)
def test_records_a_scoring_run_with_its_means(self):
line = "Navigation 7, Locality 6.5, Shape 7, Self-sufficiency 6.5, Overall 7"
seats = "".join(f"\n{seat}: {line}\n\n- `bin/a.py:3` `f`: long\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
uncalled = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats))
self.assertEqual(uncalled.returncode, 1)
self.assertIn("no plan item or release calls this scoring run", uncalled.stderr)
self.plan()
ran = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertTrue(ran.stdout.startswith(f"Appended to {self.checkout / 'docs' / 'comprehension-history.md'}.\nMeans: "), ran.stdout)
self.assertIn("\nFloor: Locality 6.50, Self-sufficiency 6.50 under the floor of 7.0.\nNext: file one floor item, a refactor lifting Locality and Self-sufficiency, the lowest dimensions,", ran.stdout)
self.assertIn("not /", self.run_tool("record-scoring", "1", self.seats_file(f"PR #2 at {self.start}\n" + seats)).stderr)
text = (self.checkout / "docs" / "comprehension-history.md").read_text()
self.assertIn("| Mean | 7.00 | 6.50 | 7.00 | 6.50 | 7.00 |", text)
self.assertIn("Inherited architect, would restructure first:", text)
self.assertEqual(entries(text)[0].scored_places, [Place("bin/a.py", "f")] * 4)
def test_record_scoring_refreshes_the_open_floor_item_unless_the_chunk_ships_it(self):
line = "Navigation 7, Locality 6.5, Shape 7, Self-sufficiency 7, Overall 7"
seats = "".join(f"\n{seat}: {line}\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
self.plan(second="**Reach the comprehension floor: lift Locality.**")
ran = self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("\nNext: refresh floor item 2 to lift Locality, the lowest dimension,", ran.stdout)
shipped = self.run_tool("record-scoring", self.seats_file(f"PR #2 rerun at {self.start}\n" + seats), "1", "2")
self.assertEqual(shipped.returncode, 0, shipped.stderr)
self.assertIn("\nNext: file one floor item,", shipped.stdout)
def plan(self, readme="# P\n\n## Goals\n\n1. **Achieve:** A.\n", bar="0.1", second="**Do A.**"):
"""Commit and push the README.md and a todo.md whose item 1, alone in release 0.1.0, moves code health, each item scored as before any scoring run."""
header = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
# Before any scoring run code health weighs four times its weight at an overall of 7.0: 4 / 1.97 against goal 1's 0.97 / 1.97.
rows = f"| 1 | 0.1.0 | | | **Read easier.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 101.5 |\n| 2 | 0.2.0 | | | {second} | 1 | 1 | 1 | 1 | 1 | 1 by 3 | 73.9 |\n"
self.commit("Plan", {"README.md": readme, "todo.md": f"# todo\n\n## Scoring\n\n`Score = 100 * V / 2**S`\n\n`Bar = {bar}`\n\n`Next ID = 3`\n\n## Items\n\n" + header + rows})
self.git("push", "-q", "origin", "HEAD:main")
def test_says_no_ruling_and_no_means_where_the_history_cannot_be_written(self):
docs = self.checkout / "docs"
docs.mkdir(exist_ok=True)
(docs / "comprehension-history.md").unlink(missing_ok=True)
place = "\n\n- Locality, Overall: `bin/a.py:3` `f`: shorter\n\n"
votes_file = self.seats_file(f"PR #2 at {self.start}, against {self.start}\n\nMid A: {said('better', 'worse')}{place}Inherited architect: {said('better', 'worse')}{place}", "votes.md")
self.plan()
docs.chmod(0o500)
self.addCleanup(docs.chmod, 0o700)
for ran in (self.run_tool("record-ruling", votes_file), self.record_sevens()):
self.assertEqual((ran.returncode, ran.stdout), (1, ""), ran.stderr)
self.assertIn("cannot write", ran.stderr)
def record_sevens(self):
"""Run record-scoring for item 1 on a scores file in which every seat scores 7 throughout."""
line = "Navigation 7, Locality 7, Shape 7, Self-sufficiency 7, Overall 7"
seats = "".join(f"\n{seat}: {line}\n" for seat in ("Junior A", "Mid A", "Maintainability senior", "Inherited architect"))
return self.run_tool("record-scoring", self.seats_file(f"PR #2 at {self.start}\n" + seats), "1")
def test_record_scoring_removes_the_worktree_and_prompts_prepare_scoring_made(self):
self.commit("Values", {"AGENTS.md": "## Scoring run\n\n- Language: Python\n- Kind: a CLI\n- Domain: parsing\n- Domain docs: the spec\n- 3am question: the parse hangs\n"})
prepared = self.run_tool("prepare-scoring")
self.assertEqual(prepared.returncode, 0, prepared.stderr)
self.assertEqual(len(self.git("worktree", "list").splitlines()), 2)
self.plan()
ran = self.record_sevens()
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertFalse((self.checkout.parent / ".local" / "state" / "larv-review" / "proj" / "scoring").exists())
self.assertEqual(len(self.git("worktree", "list").splitlines()), 1)
VALUES = {"AGENTS.md": "## Scoring run\n\n- Language: Python\n- Kind: a CLI\n- Domain: parsing\n- Domain docs: the spec\n- 3am question: the parse hangs\n"}
def test_prepare_scoring_refuses_any_argument(self):
self.commit("Values", self.VALUES)
for given in (["--preloaded"], ["--preloaded", "text"], ["text"]):
with self.subTest(given=given):
ran = self.run_tool("prepare-scoring", *given)
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertTrue(ran.stderr.startswith("unknown arguments prepare-scoring"), ran.stderr)
def test_record_scoring_without_a_scores_file_and_an_empty_item_ID_print_the_usage_line(self):
bare = self.run_tool("record-scoring")
self.assertEqual(bare.returncode, 1)
self.assertTrue(bare.stderr.startswith("unknown arguments record-scoring; usage: larv-review "), bare.stderr)
empty = self.run_tool("needs-scoring-run", "")
self.assertEqual(empty.returncode, 1)
self.assertIn("takes item IDs", empty.stderr)
def test_the_commands_that_judge_a_branch_refuse_a_failed_fetch_instead_of_reading_origin_as_last_fetched(self):
self.git("remote", "set-url", "origin", str(self.checkout.parent / "gone.git"))
seats = self.seats_file(f"PR #2 at {self.start}\n")
for given in (["ruling-base"], ["needs-scoring-run"], ["needs-scoring-run", "1"], ["scoring-run-owed"], ["record-scoring", seats], ["record-scoring", seats, "1"]):
with self.subTest(given=given):
ran = self.run_tool(*given)
self.assertEqual(ran.returncode, 1)
self.assertNotIn("reading origin as last fetched", ran.stderr)
self.assertEqual(ran.stdout, "")
def test_reports_a_plan_it_cannot_read_yet_keeps_the_run(self):
# This checkout has no README.md beside its todo.md.
ran = self.record_sevens()
self.assertEqual(ran.returncode, 1)
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: {self.checkout / 'README.md'}: missing or empty", ran.stderr)
self.assertIn("not record-scoring again", ran.stderr)
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
def test_reports_a_plan_it_reads_but_cannot_rank_yet_keeps_the_run(self):
self.plan(readme="# P\n\n## Goals\n\n**Void:** code health, since it is a probe.\n\n1. **Achieve:** A.\n")
ran = self.record_sevens()
self.assertEqual(ran.returncode, 1)
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: item 1 names code health, which the goals file voids", ran.stderr)
self.assertIn("not record-scoring again", ran.stderr)
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
def test_a_plan_in_jira_is_not_reranked(self):
with tempfile.TemporaryDirectory() as temp:
checkout = pathlib.Path(temp, "acme")
checkout.mkdir()
config = configured(self, checkout) / "config.toml"
config.write_text(config.read_text().replace('"checkout:todo.md"', '"jira:https://acme.atlassian.net/browse/ABC-12"') + 'env-file = "~/acme.env"\njira-score-formula = "V"\njira-score-bar = 1\n')
(checkout / "todo.md").write_text("the owners' own notes\n")
self.enterContext(contextlib.chdir(checkout))
said: list[str] = []
self.assertIsNone(rerank(config.parents[2], said.append))
self.assertEqual((said, (checkout / "todo.md").read_text()), ([], "the owners' own notes\n"))
def test_reranks_todo_md_by_the_overall_it_records(self):
self.plan()
ran = self.record_sevens()
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("| code health by 1 | 25.4 |", (self.checkout / "todo.md").read_text())
def test_fails_once_its_re_rank_leaves_an_item_under_the_bar_yet_keeps_the_run(self):
self.plan(bar="30")
ran = self.record_sevens()
self.assertEqual(ran.returncode, 1)
todo = self.checkout / "todo.md"
# At an overall of 7.0 item 1 falls from 101.5 to 25.4.
self.assertIn(f"{todo}: item 1 scores 25.4, under the bar 30; delete it, or mark it with a reason the bar does not apply\n", ran.stderr)
self.assertIn("recorded the run", ran.stderr)
self.assertIn("not record-scoring again", ran.stderr)
self.assertIn("| code health by 1 | 25.4 |", todo.read_text())
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
def test_prints_the_places_seats_found_hard_since_the_newest_scoring_run(self):
self.assertEqual(self.run_tool("places").stdout, "Seats found no places hard.\n")
self.commit("Record a scoring run", {"docs/comprehension-history.md": appended("", SCORING + "\nJunior A, hardest first:\n\n- `bin/b.py:4` `h`: long\n")})
ran = self.run_tool("places")
self.assertEqual((ran.returncode, ran.stdout), (0, "## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\nJunior A, hardest first:\n\n- `bin/b.py:4` `h`: long\n"), ran.stderr)
self.assertIn("unknown arguments", self.run_tool("places", "x").stderr)
outside = subprocess.run([sys.executable, str(TOOL), "places"], capture_output=True, cwd=self.checkout.parent, env=self.env, text=True)
self.assertEqual((outside.returncode, outside.stdout), (1, ""))
def test_prints_how_often_seats_agree_in_rulings_and_across_runs_on_one_commit(self):
history = "\n".join([scored("2026-10-01T00:00:00Z", "PR #1", "aaaaaaa", "7", "7"), scored("2026-10-02T00:00:00Z", "PR #1 rerun", "aaaaaaa", "7.5", "7"), ruled("2026-10-03T00:00:00Z", "PR #2", "same", "same")])
self.commit("Record the checks", {"docs/comprehension-history.md": appended("", history)})
ran = self.run_tool("agreement")
self.assertEqual((ran.returncode, ran.stdout), (0, "Unchecked: Mid A and Inherited architect voted alike overall in 1 of 1 paired rulings, and their overall scores moved alike between two scoring runs on one commit in 0 of 1 pairs. A verdict needs 10 commits each scored twice and one paired ruling.\n"), ran.stderr)
self.assertIn("unknown arguments", self.run_tool("agreement", "x").stderr)
def test_refuses_a_ruling_file_that_names_no_base_or_a_commit_the_checkout_lacks(self):
ran = self.run_tool("record-ruling", self.seats_file(f"PR #2 at {self.start}\n\nMid A: {said('same')}\n\nInherited architect: {said('same')}\n"))
self.assertEqual(ran.returncode, 1)
self.assertIn("against <base>", ran.stderr)
lacking = self.run_tool("record-ruling", self.seats_file(f"PR #2 at {self.start}, against abcdef1\n\nMid A: {said('same')}\n\nInherited architect: {said('same')}\n"))
self.assertEqual(lacking.returncode, 1)
self.assertIn("abcdef1, which is no commit", lacking.stderr)
def test_states_its_rules_and_finds_origins_default_branch_where_the_clone_recorded_none(self):
helped = self.run_tool("--help")
self.assertEqual(helped.returncode, 0, helped.stderr)
self.assertIn("cap of 2 rounds", helped.stdout)
self.git("remote", "set-head", "origin", "--delete")
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "No scoring run due.\n")
def test_makes_and_prints_the_worktrees_review_folder_from_anywhere_in_it(self):
reports = self.checkout.parent / ".local" / "state" / "larv-review"
(self.checkout / "sub").mkdir()
ran = subprocess.run([sys.executable, str(TOOL), "review-folder"], capture_output=True, cwd=self.checkout / "sub", env=self.env, text=True)
self.assertEqual((ran.returncode, ran.stdout), (0, f"{reports}/proj\n"), ran.stderr)
self.assertTrue((reports / "proj").is_dir())
def test_leaves_the_reports_folder_readable_by_the_user_alone_where_it_was_not(self):
reports = self.checkout.parent / ".local" / "state" / "larv-review"
reports.mkdir(parents=True, mode=0o755)
self.assertEqual(self.run_tool("review-folder").returncode, 0)
self.assertEqual(reports.stat().st_mode & 0o777, 0o700)
def test_fails_where_it_cannot_make_the_review_folder(self):
(self.checkout.parent / ".local" / "state").mkdir(parents=True)
(self.checkout.parent / ".local" / "state" / "larv-review").write_text("")
ran = self.run_tool("review-folder")
self.assertEqual(ran.returncode, 1)
self.assertIn("could not make the review folder", ran.stderr)
def test_review_folder_fails_outside_a_checkout(self):
ran = subprocess.run([sys.executable, str(TOOL), "review-folder"], capture_output=True, cwd=self.checkout.parent, env=self.env, text=True)
self.assertEqual(ran.returncode, 1)
self.assertNotIn("Traceback", ran.stderr)
def test_review_folder_takes_no_arguments(self):
self.assertIn("unknown arguments", self.run_tool("review-folder", "x").stderr)
def assert_names_the_non_id(self, named, *args):
ran = self.run_tool(*args)
self.assertEqual(ran.returncode, 1)
self.assertIn(f"takes item IDs, the numbers in todo.md's ID column, not {named};", ran.stderr)
def test_needs_scoring_run_names_the_argument_that_is_not_an_item_id(self):
self.assert_names_the_non_id("x", "needs-scoring-run", "3", "x")
def test_record_scoring_names_the_argument_after_its_file_that_is_not_an_item_id(self):
self.assert_names_the_non_id("y1", "record-scoring", "scores.md", "4", "y1")
def test_help_and_the_usage_line_list_the_same_commands(self):
usage = next(line for line in self.run_tool("--help").stdout.splitlines() if line.startswith("usage: larv-review "))
listed = usage.removeprefix("usage: larv-review ").split(" | ")
self.assertEqual([shape.split()[0] for shape in listed], ["review-folder", "ruling-base", "round-count", "needs-scoring-run", "scoring-run-owed", "record-ruling", "prepare-scoring", "record-scoring", "places", "agreement", "reviewer-header", "round-title", "reviewer-context"])
self.assertIn(f"usage: larv-review {' | '.join(listed)}", self.run_tool().stderr)
def test_takes_a_local_main_without_origin_and_reads_origin_as_last_fetched_when_the_fetch_fails(self):
self.commit("Answer prose round 1: a")
self.git("remote", "set-url", "origin", str(self.checkout.parent / "gone.git"))
offline = self.run_tool("round-count")
self.assertEqual(offline.returncode, 0, offline.stderr)
self.assertIn("reading origin as last fetched", offline.stderr)
self.assertIn("prose: 1\n", offline.stdout)
self.git("remote", "remove", "origin")
self.assertIn("prose: 1\n", self.run_tool("round-count").stdout)
def fake_tea(self, number, head):
"""Puts a tea on PATH whose API lists one open pull request, number, from origin's chunk at head."""
pull = f'{{"number": {number}, "head": {{"ref": "chunk", "label": "chunk", "sha": "{head}", "repo": {{"full_name": "a/b"}}}}, "base": {{"repo": {{"full_name": "a/b"}}}}}}'
self.fake_tea_script(f"echo '[{pull}]'")
def fake_tea_script(self, body):
folder = self.checkout.parent / "fake-bin"
folder.mkdir(exist_ok=True)
(folder / "tea").write_text(f"#!/bin/sh\n{body}\n")
(folder / "tea").chmod(0o755)
if not self.env["PATH"].startswith(f"{folder}:"):
self.env["PATH"] = f"{folder}:{self.env['PATH']}"
def header_line(self, opening, *args):
ran = self.run_tool("reviewer-header", *args)
self.assertEqual(ran.returncode, 0, ran.stderr)
return next((line for line in ran.stdout.splitlines() if line.startswith(opening)), None)
def test_writes_the_branch_diff_and_the_places_and_prints_a_reviewers_header(self):
self.commit("Work", {"a.txt": "one\n"})
self.git("push", "-q", "-u", "origin", "chunk")
head = self.git("rev-parse", "HEAD").strip()
self.fake_tea(7, head)
self.commit("Unpushed fix", {"a.txt": "two\n"})
short = self.git("rev-parse", "--short", "HEAD").strip()
base = self.git("rev-parse", self.start).strip()
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
ran = self.run_tool("reviewer-header", "stability")
self.assertEqual((ran.returncode, ran.stdout), (0, (
"Pass: stability, round 1.\n"
"PR: #7.\n"
f"Worktree: {self.checkout}, on branch chunk.\n"
f"Base: {base}, the merge base of HEAD and origin/main.\n"
f"Report: write it to {folder}/stability-round-1.md.\n"
f"Diff: {folder}/branch-{short}.diff\n"
f"Technical principles: {self.checkout.parent}/principles\n"
f"Review standards: {self.checkout.parent}/standards\n"
f"Goals and audience: {self.checkout}/README.md\n"
f"Plan: {folder}/plan.md\n"
"Prose language: English.\n"
f"Places: {folder}/places.md\n"
)), ran.stderr)
self.assertEqual((folder / f"branch-{short}.diff").read_text(), self.git("diff", base, "HEAD"))
self.assertEqual((folder / "places.md").read_text(), self.run_tool("places").stdout)
self.assertEqual((folder / "plan.md").read_text(), (
f"# Plan, as {self.checkout}/todo.md holds it\n\n"
"## Item 1, release 0.1.0\n\n**Do it.**\n\n"
"## Item 2, release 0.2.0\n\n**Then this.**\n\n"
"## Item 3, release 0.2.0\n\n**And this.**\n"
))
def test_counts_the_round_from_the_branchs_answers_and_names_the_report_that_asked_for_a_rerun(self):
self.commit("Answer prose round 1: a")
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
missing = self.run_tool("reviewer-header", "prose", "--rerun")
self.assertEqual(missing.returncode, 1)
self.assertIn(f"{folder}/prose-round-2.md is missing", missing.stderr)
(folder / "prose-round-2.md").write_text("Asks for a rerun one rung up.\n")
ran = self.run_tool("reviewer-header", "prose", "--rerun")
self.assertEqual(ran.returncode, 0, ran.stderr)
lines = ran.stdout.splitlines()
self.assertEqual(lines[0], "Pass: prose, round 2.")
self.assertEqual(lines[1], "PR: none, the branch is not pushed.")
self.assertIn(f"Report: write it to {folder}/prose-round-2-rerun.md, in place of {folder}/prose-round-2.md, which asked for this rerun.", lines)
self.assertFalse(any(line.startswith("Places:") for line in lines), "only architecture and stability take the places")
def test_round_title_counts_the_unanswered_rounds_report_and_names_one_that_is_missing(self):
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
folder.mkdir(parents=True)
(folder / "prose-round-1.md").write_text("BLOCK\n\n### 🔴 [misread] `a.md:1`: wrong\n\n### 🟡 `b.md:2`: worse\n\n### 🟢 `c.md:3`: nit\n")
ran = self.run_tool("round-title", "prose")
self.assertEqual((ran.returncode, ran.stdout, ran.stderr), (0, "Answer prose round 1: 1 🔴, 1 🟡 (1 misread);\n", ""))
self.commit("Answer prose round 1: 1 🔴, 1 🟡 (1 misread); fix")
missing = self.run_tool("round-title", "prose")
self.assertEqual((missing.returncode, missing.stdout), (1, ""))
self.assertIn(f"no report at {folder}/prose-round-2.md", missing.stderr)
(folder / "prose-round-2.md").write_text("BLOCK\n\n### 🟡 a\n\nRerun one rung up\n")
(folder / "prose-round-2-rerun.md").write_text("APPROVE\n")
self.assertEqual(self.run_tool("round-title", "prose").stdout, "Answer prose round 2: 0 🔴, 0 🟡 (0 misread);\n", "the rerun's report stands in place of the one that asked")
for given in (["security"], ["Prose"], ["prose", "2"], []):
self.assertEqual(self.run_tool("round-title", *given).returncode, 1, given)
def test_reviewer_header_refuses_a_pass_at_its_cap_and_a_pass_no_agent_reviews(self):
self.commit("Answer stability round 1: a")
self.commit("Answer stability round 2: b")
capped = self.run_tool("reviewer-header", "stability")
self.assertEqual(capped.returncode, 1)
self.assertIn("stability takes no more rounds", capped.stderr)
for given in (["security"], ["Stability"], ["prose", "--again"], []):
self.assertEqual(self.run_tool("reviewer-header", *given).returncode, 1, given)
def test_reviewer_header_leaves_an_unchanged_diff_places_and_plan_untouched_so_an_earlier_rounds_replay_keeps_them(self):
self.commit("Work", {"a.txt": "one\n"})
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
self.assertEqual(self.run_tool("reviewer-header", "stability").returncode, 0)
written = [folder / f"branch-{self.git('rev-parse', '--short', 'HEAD').strip()}.diff", folder / "places.md", folder / "plan.md"]
for path in written:
os.utime(path, (0, 0))
self.assertEqual(self.run_tool("reviewer-header", "prose").returncode, 0)
self.assertEqual([path.stat().st_mtime for path in written], [0, 0, 0])
def test_reviewer_header_names_why_it_names_no_pull_request(self):
self.git("push", "-q", "-u", "origin", "chunk")
self.fake_tea(7, "0" * 40)
self.assertEqual(self.header_line("PR:", "prose"), "PR: none open at the pushed head.")
self.fake_tea_script("echo 'tea is down' >&2; exit 1")
self.assertTrue(self.header_line("PR:", "prose").startswith("PR: unknown, "))
self.git("remote", "rename", "origin", "upstream")
self.assertEqual(self.header_line("PR:", "prose"), "PR: unknown, the checkout has no origin remote.")
def test_reviewer_header_takes_the_merge_base_once_the_default_branch_moves_on(self):
base = self.git("rev-parse", "HEAD").strip()
self.commit("Work")
self.git("switch", "-q", "-c", "other", "main")
self.commit("Land something else")
self.git("push", "-q", "origin", "HEAD:main")
self.git("switch", "-q", "chunk")
self.assertEqual(self.header_line("Base:", "prose"), f"Base: {base}, the merge base of HEAD and origin/main.")
def test_reviewer_header_reads_origin_as_last_fetched_when_the_fetch_fails(self):
self.git("remote", "set-url", "origin", str(self.checkout.parent / "gone.git"))
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("reading origin as last fetched", ran.stderr)
def test_reviewer_header_refuses_a_detached_head_and_a_review_folder_it_cannot_make(self):
self.git("switch", "-q", "--detach")
detached = self.run_tool("reviewer-header", "prose")
self.assertEqual((detached.returncode, detached.stdout), (1, ""))
self.git("switch", "-q", "chunk")
(self.checkout.parent / ".local" / "state").mkdir(parents=True)
(self.checkout.parent / ".local" / "state" / "larv-review").write_text("")
unmade = self.run_tool("reviewer-header", "prose")
self.assertEqual(unmade.returncode, 1)
self.assertIn("could not make the review folder", unmade.stderr)
def test_reviewer_header_writes_a_diff_of_a_file_that_is_not_utf_8(self):
(self.checkout / "blob.txt").write_bytes(b"\xff\xfe text\n")
self.git("add", "blob.txt")
self.git("commit", "-q", "-m", "Add bytes")
self.assertIsNotNone(self.header_line("Diff:", "prose"))
def test_reviewer_header_names_the_principles_folder_the_projects_config_sets(self):
self.assertEqual(self.header_line("Technical principles:", "prose"), f"Technical principles: {self.checkout.parent}/principles")
def test_reviewer_header_names_the_review_standards_folder_the_projects_config_sets(self):
self.assertEqual(self.header_line("Review standards:", "prose"), f"Review standards: {self.checkout.parent}/standards")
def test_reviewer_header_names_the_language_and_counts_rounds_through_the_commit_title_the_projects_config_sets(self):
self.config.write_text(PROJECT_CONFIG + 'language = "Swedish"\ncommit-title = "PAY-{id} - {summary}"\n')
self.commit("PAY-7 - Answer prose round 1: 0 🔴, 1 🟡 (0 misread); a")
self.assertEqual(self.header_line("Prose language:", "prose"), "Prose language: Swedish.")
self.assertEqual(self.header_line("Pass:", "prose"), "Pass: prose, round 2.")
self.assertIn("prose: 1\n", self.run_tool("round-count").stdout)
def test_round_count_fails_naming_the_fault_of_a_config_it_cannot_read(self):
self.config.write_text(PROJECT_CONFIG + 'commit-title = "PAY-{id}"\n')
ran = self.run_tool("round-count")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn("`commit-title` is 'PAY-{id}'", ran.stderr)
def test_reviewer_header_names_the_goals_file_the_projects_config_sets(self):
self.config.write_text(PROJECT_CONFIG.replace('"checkout:README.md"', '"folder:goals.md"'))
self.assertEqual(self.header_line("Goals and audience:", "principles"), f"Goals and audience: {self.config.parent}/goals.md")
def test_reviewer_header_fails_naming_the_epic_where_it_cannot_read_goals_kept_in_jira(self):
# Port 1 on the loopback refuses the connection, so the read fails without leaving the machine.
epic = "jira:https://127.0.0.1:1/browse/ABC-12"
credentials = self.config.parents[2] / "acme.env"
credentials.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
credentials.chmod(0o600)
self.config.write_text(PROJECT_CONFIG.replace('"checkout:todo.md"', f'"{epic}"').replace('"checkout:README.md"', f'"{epic}"') + 'env-file = "~/acme.env"\njira-score-formula = "V"\njira-score-bar = 1\n')
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn("cannot read the epic ABC-12", ran.stderr)
def test_reviewer_header_fails_with_the_configs_message_where_it_sets_no_principles_or_standards_folder(self):
for setting in ("principles", "standards"):
with self.subTest(setting=setting):
self.config.write_text(PROJECT_CONFIG.replace(f'{setting} = "~/{setting}"\n', ""))
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn(f"`{setting}` is missing", ran.stderr)
def test_reviewer_header_fails_where_no_config_names_the_checkout(self):
self.config.unlink()
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn(f"no config names the checkout {self.checkout}", ran.stderr)
def test_reviewer_header_fails_where_the_principles_or_standards_folder_is_missing_or_empty(self):
for setting, file in (("principles", "technical-principles.md"), ("standards", "quality.md")):
with self.subTest(setting=setting):
folder = self.checkout.parent / setting
(folder / file).unlink()
empty = self.run_tool("reviewer-header", "prose")
folder.rmdir()
missing = self.run_tool("reviewer-header", "prose")
folder.mkdir()
(folder / file).write_text("# Restored\n")
for ran in (empty, missing):
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn(f"{folder} is not a folder with a file in it; {self.config} sets it as `{setting}`", ran.stderr)
def test_reviewer_header_names_the_coding_conventions_only_where_the_projects_config_sets_them(self):
self.assertIsNone(self.header_line("Coding conventions:", "prose"))
(self.checkout / "CONVENTIONS.md").write_text("# Conventions\n")
(self.config.parent / "style.md").write_text("# Style\n")
self.config.write_text(PROJECT_CONFIG + 'coding-conventions = ["checkout:CONVENTIONS.md", "folder:style.md"]\n')
self.assertEqual(self.header_line("Coding conventions:", "prose"), f"Coding conventions: {self.checkout}/CONVENTIONS.md, {self.config.parent}/style.md")
def test_reviewer_header_fails_where_a_coding_conventions_file_is_missing(self):
self.config.write_text(PROJECT_CONFIG + 'coding-conventions = ["checkout:CONVENTIONS.md"]\n')
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
self.assertIn(f"{self.checkout}/CONVENTIONS.md is not a file; {self.config} sets it in `coding-conventions`", ran.stderr)
def test_reviewer_header_gives_the_architect_the_places(self):
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
self.assertEqual(self.header_line("Places:", "architecture"), f"Places: {folder}/places.md")
def test_reviewer_header_names_the_file_that_holds_the_principles_last_where_the_project_keeps_one(self):
self.assertIsNone(self.header_line("Principles:", "prose"))
(self.checkout / "AGENTS.md").write_text("")
self.assertIsNone(self.header_line("Principles:", "prose"))
self.bare("prose-reviewer")
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual(ran.stdout.splitlines()[-1], f"Principles: read {self.checkout}/AGENTS.md first, for the project principles and the decision titles.")
def test_reviewer_header_names_the_decision_log_where_the_project_keeps_no_agents_md(self):
(self.checkout / "docs").mkdir(exist_ok=True)
(self.checkout / "docs" / "decisions.md").write_text("1. A principle.\n\n# Decisions\n")
(self.checkout / "CHANGELOG.md").write_text("# Changelog\n")
self.bare("prose-reviewer")
ran = self.run_tool("reviewer-header", "prose")
self.assertEqual(ran.stdout.splitlines()[-1], f"Principles: read {self.checkout}/docs/decisions.md first, up to `# Decisions`, for the project principles and the decision titles.")
def bare(self, agent):
(self.checkout.parent / ".claude" / "agents").mkdir(parents=True, exist_ok=True)
(self.checkout.parent / ".claude" / "agents" / f"{agent}.md").write_text("---\nomitClaudeMd: true\n---\n")
def test_reviewer_context_hands_a_reviewer_the_sections_or_what_kept_it_from_them(self):
def hook(agent):
return subprocess.run([sys.executable, str(TOOL), "reviewer-context"], capture_output=True, env=self.env, input=json.dumps({"agent_type": agent}), text=True)
self.bare("prose-reviewer")
missing = hook("prose-reviewer")
self.assertEqual((missing.returncode, missing.stderr), (0, ""))
self.assertIn("failed: could not read", json.loads(missing.stdout)["hookSpecificOutput"]["additionalContext"])
(self.checkout.parent / ".claude").mkdir(exist_ok=True)
(self.checkout.parent / ".claude" / "CLAUDE.md").write_text("## Shared goal\n\nHealth.\n\n## Prose\n\nShort.\n\n## Vocabulary\n\nWords.\n")
ran = hook("prose-reviewer")
self.assertEqual(ran.returncode, 0, ran.stderr)
self.assertIn("## Prose\n\nShort.\n\n## Vocabulary\n\nWords.", json.loads(ran.stdout)["hookSpecificOutput"]["additionalContext"])
self.assertEqual((hook("Explore").returncode, hook("Explore").stdout), (0, ""))
if __name__ == "__main__":
unittest.main()