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

1327 lines
89 KiB
Python

import contextlib
import decimal
import itertools
import json
import os
import pathlib
import subprocess
import sys
import tempfile
import textwrap
import unittest
import unittest.mock
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.plan import checkout_plan, EMPTIED_WORDS, landed_towards, plan_reasons, scoring_run_due
from review_rules import comprehension_history
from project_config.test_project_config 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 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 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 = ["leaves release 0.1.0 with no plan item"]
floor = ["ships item 2, a floor item"]
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)
with unittest.mock.patch.dict(os.environ, {"HOME": str(self.config.parents[2])}):
self.assertEqual(plan_reasons("origin/main", [2], pathlib.Path.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], pathlib.Path.home()), [])
(self.config.parent / "decisions.md").unlink()
gone = plan_reasons("origin/main", [1, 7], pathlib.Path.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], pathlib.Path.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_puts_the_preloaded_text_it_is_given_in_the_seats_prompts(self):
self.commit("Values", self.VALUES)
prepared = self.run_tool("prepare-scoring", "--preloaded", "the files the harness loaded")
self.assertEqual(prepared.returncode, 0, prepared.stderr)
prompts = [path.read_text() for path in (self.checkout.parent / ".local" / "state" / "larv-review").rglob("*.md") if "scoring" in path.parts]
self.assertTrue(any("the files the harness loaded" in prompt for prompt in prompts), prepared.stdout)
def test_prepare_scoring_refuses_a_preloaded_flag_without_its_text_and_any_other_arguments(self):
self.commit("Values", self.VALUES)
for given in (["--preloaded"], ["text"], ["text", "--preloaded"], ["--preloaded", "text", "more"], ["--other", "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(pathlib.Path.home(), 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", "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_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_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()