Files
claude-config/bin/release_plan/test_ranking.py
T

479 lines
30 KiB
Python

import contextlib
import io
import pathlib
import re
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from project_config.test_project_config import configured
from failure import Failure
from release_plan import plan_file, ranking
from repo_checks import ROOT
from release_plan import todo_table
# Voids code health, so these tests weigh only the project's own goals; class CodeHealth weighs it.
VOID = "**Void:** code health, since a test project has no code to read.\n\n"
README = "# P\n\n## Goals\n\n" + VOID + "1. **Achieve:** Fast.\n2. **Maintain:** Correct.\n 1. **Achieve:** Tested.\n\n## Audience\n\nMe.\n"
DECISIONS = "## A choice\n\nStands until `todo.md` item 5 ends it.\n"
TODO = """# todo
## Scoring
`Score = 100 * V / 2**S`
`Bar = 2`
`Next ID = 6`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 0 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 0 |
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 | 0 |
| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 3 | 3 | 5 | 9 | 2 | 2.1 by 1 | 0 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 0 |
## Details
### 1. stale heading
Later detail.
### 3. Make it fast.
Fast detail.
## Notes
Kept as written.
"""
OLD_SHAPE = """# todo
## Scoring
`Score = -R - S/4 + 2*A + 2*G*W`
`Bar = 9`
`Next ID = 6`
| Goal | W |
|---|---|
| 1 | 1.00 |
| 2 | 0.67 |
| 2.1 | 0.33 |
## Items
| ID | Release | Blocked by | Exempt | Item | R | S | C | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 0 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 0 |
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 0 |
| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | 0 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 0 |
## Details
### 1. stale heading
Later detail.
### 3. Make it fast.
Fast detail.
## Notes
Kept as written.
"""
class Rank(unittest.TestCase):
def ranked(self, todo=TODO, readme=README, decisions=DECISIONS):
return ranking.rank(todo, readme, decisions, "")
def test_scores_and_sorts_by_release_then_security_then_score_and_orders_the_details_to_match(self):
ranked = self.ranked()
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 3 | 3 | 5 | 9 | 2 | 2.1 by 1 | 12.3 |
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 | 5.5 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 3.1 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 1.5 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 9 | 228.4 |
""", ranked.text)
self.assertTrue(ranked.text.endswith("## Details\n\n### 3. Make it fast, `a | b`.\n\nFast detail.\n\n### 1. Ship the later thing.\n\nLater detail.\n\n## Notes\n\nKept as written.\n"))
self.assertEqual(ranked.under_bar, [])
self.assertEqual(ranked.notes, [])
self.assertEqual(self.ranked(ranked.text), ranked)
def test_keeps_a_detail_that_opens_with_markdown_quoted_by_four_spaces(self):
quoting = TODO.replace("Fast detail.", " ## Goals\n\nFast detail.")
self.assertIn("### 3. Make it fast, `a | b`.\n\n ## Goals\n\nFast detail.\n", self.ranked(quoting).text)
def test_weighs_each_achieve_goal_97_percent_of_the_one_above_and_no_maintain_goal(self):
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
self.assertEqual({goal: round(weight, 4) for goal, weight in ranking.goal_weights(ranking.numbered_goals(readme), None).items()}, {"1": 0.3435, "1.2": 0.3332, "2": 0.3232})
def test_weighs_5_achieve_goals_from_0212_to_0188_and_15_from_0082_to_0053(self):
for count, first, last in ((5, 0.212, 0.188), (15, 0.082, 0.053)):
with self.subTest(count=count):
goals = ranking.numbered_goals("## Goals\n\n" + "".join(f"{number}. **Achieve:** G.\n" for number in range(1, count + 1)))
weights = list(ranking.goal_weights(goals, None).values())
self.assertEqual((round(weights[0], 3), round(weights[-1], 3), round(sum(weights), 6)), (first, last, 1))
def test_scores_an_item_by_the_weights_of_the_goals_it_moves(self):
readme = "## Goals\n\n" + VOID + "1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
todo = TODO.replace("2.1 by 8, 1 by 6", "1.2 by 2, 2 by 3").replace("| 2.1 by 1 |", "| 1 by 1 |")
self.assertIn("| **Make it fast, `a \\| b`.** | 2 | 1 | 2 | 3 | 7 | 1.2 by 2, 2 by 3 | 1.3 |", self.ranked(todo, readme).text)
def test_scores_an_item_that_moves_no_goal_zero(self):
ranked = self.ranked(TODO.replace("| 1 | 2 | 1 | 2 | 4 | 2.1 by 1 |", "| 1 | 2 | 1 | 2 | 4 | |"))
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | | 0.0 |", ranked.text)
self.assertEqual(ranked.under_bar, ["item 2 scores 0.0, under the bar 2; delete it, or mark it with a reason the bar does not apply"])
def test_holds_each_item_a_decision_cites_and_says_how_to_settle_a_finished_one(self):
self.assertIsInstance(self.ranked(decisions=DECISIONS + "Until `todo.md` item 4 lands.\n"), ranking.Ranked)
gone = self.ranked(TODO.replace("| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 0 |\n", ""))
self.assertEqual(gone.reason, "docs/decisions.md cites \"`todo.md` item 5\", which todo.md no longer holds; revise that decision to say what holds now")
def test_names_each_item_under_the_bar_that_is_not_exempt(self):
ranked = self.ranked(TODO.replace("`Bar = 2`", "`Bar = 3.5`"))
self.assertEqual(ranked.under_bar, ["item 2 scores 3.1, under the bar 3.5; delete it, or mark it with a reason the bar does not apply"])
self.assertEqual(self.ranked(TODO.replace("`Bar = 2`", "`Bar = 3.1`")).under_bar, [])
blocking = self.ranked(TODO.replace("`Bar = 2`", "`Bar = 3.5`").replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 2 |").replace("| 5 | 0.1.0 | |", "| 5 | 0.1.0 | 3 |"))
self.assertEqual(blocking.under_bar, ["item 2 scores 3.1, under the bar 3.5; delete it and the items it blocks, directly or through another (3, 5), or mark it with a reason the bar does not apply"])
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | principle |")).under_bar, [])
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | owner |")).under_bar, [])
def test_reads_goals_and_sub_goals_in_reading_order(self):
self.assertEqual(ranking.numbered_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(ranking.numbered_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
self.assertEqual(ranking.numbered_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
self.assertEqual(ranking.numbered_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("the goals file's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
self.assertEqual(ranking.parse_weights(["| Goal | W |", "|---|---|"], ["1"]), Failure("the goal weights list no goal, but the goals file's goals are 1; by position they weigh:\n| Goal | W |\n|---|---|\n| 1 | 1.00 |"))
self.assertEqual(ranking.numbered_goals("# P\n"), Failure("the goals file has ## Goals 0 times; it needs it once"))
self.assertEqual(ranking.numbered_goals("## Goals\n\nFast.\n"), Failure("the goals file's ## Goals has no numbered goal"))
self.assertEqual(ranking.parse_weights(["| Goal | W |", "|---|---|", "| 1 | 0.5 |", "| 3 | 0.5 |"], ["1", "2"]), Failure("the goal weights list 1, 3, but the goals file's goals are 1, 2; by position they weigh:\n| Goal | W |\n|---|---|\n| 1 | 1.00 |\n| 2 | 0.50 |"))
self.assertEqual(ranking.numbered_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
def test_refuses_a_goal_it_cannot_weigh(self):
cases = {
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 3 by 6"), README): "item 3 cites goal 3, which the goals file's ## Goals does not number",
(TODO.replace("2.1 by 8, 1 by 6", "2.1 by 8, 2.1 by 6"), README): "item 3 cites goal 2.1 twice; name each goal once",
(TODO, README.replace("**Maintain:** Correct", "Correct")): "the goals file's goal 2 is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score",
}
for (todo, readme), reason in cases.items():
with self.subTest(reason=reason):
self.assertEqual(self.ranked(todo, readme), Failure(reason))
def test_ranks_questions_first_then_security_whatever_they_score_and_a_defect_by_its_score(self):
todo = TODO.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | defect |").replace("| 3 | 3 | 5 | 9 | 2 | 2.1 by 1 |", "| 3 | 3 | 5 | 9 | 8 | 2.1 by 1 |").replace("| 5 | 0.1.0 | | decision |", "| 5 | 0.1.0 | | question |")
rows = [line.split(" | ")[0] for line in self.ranked(todo, decisions="").text.splitlines() if line.startswith("| ") and " | 0." in line]
self.assertEqual(rows, ["| 5", "| 4", "| 3", "| 2", "| 1"])
def test_weighs_the_maintain_goal_a_defect_restores_as_the_heaviest_achieve_goal(self):
ranked = self.ranked(TODO.replace("| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 |", "| 2 | 0.1.0 | | defect | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 |"))
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 | 9.5 |", ranked.text)
def test_weighs_a_maintain_goal_an_item_raises_confidence_in_as_half_a_goal_per_point(self):
ranked = self.ranked(TODO.replace("| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 |", "| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 |"))
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 | 9.4 |", ranked.text)
def test_weighs_a_defects_maintain_goal_at_least_as_much_as_a_confidence_gain(self):
readme = README.replace("**Achieve:**", "**Maintain:**")
todo = TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| 2 by 3 |").replace("| 1 by 9 |", "| |").replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | defect |")
self.assertIn("| **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2 by 3 | 9.4 |", self.ranked(todo, readme).text)
def test_refuses_a_goal_named_beside_its_own_sub_goal(self):
readme = "## Goals\n\n" + VOID + "1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
todo = TODO.replace("2.1 by 8, 1 by 6", "1.2 by 2, 1 by 3").replace("| 2.1 by 1 |", "| 2 by 1 |")
self.assertEqual(self.ranked(todo, readme), Failure("item 3 names goal 1 and its sub-goal 1.2; name one, never both: the sub-goal where the move serves it, else the parent"))
self.assertIsInstance(self.ranked(todo.replace("1.2 by 2, 1 by 3", "1.2 by 2, 2 by 3"), readme), ranking.Ranked)
def test_scores_every_item_zero_where_readme_marks_no_goal_achieve(self):
ranked = self.ranked(TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| |").replace("| 1 by 9 |", "| |"), README.replace("**Achieve:**", "**Maintain:**"))
self.assertEqual([line.split(" scores ")[0] for line in ranked.under_bar], ["item 2", "item 3", "item 1"])
self.assertEqual(ranked.notes, ["the goals file voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"])
def test_accepts_a_move_of_ten_and_a_variable_base(self):
ranked = self.ranked(TODO.replace("| 1 by 9 |", "| 1 by 10 |").replace("100 * V / 2**S", "V * S ** 2"))
self.assertIn("| **Ship the later thing.** | 1 | 1 | 1 | 1 | 1 | 1 by 10 | 5.1 |", ranked.text)
def test_asks_to_drop_a_goal_weights_table_from_a_table_with_moves(self):
weighted = TODO.replace("## Items\n", "| Goal | W |\n|---|---|\n| 1 | 1.00 |\n\n## Items\n")
self.assertEqual(self.ranked(weighted), Failure("todo.md holds a goal weights table beside a Moves column; drop the table, since rank_todo.py weighs the goals itself, as its --help says"))
def test_refuses_a_file_off_the_format(self):
row = "| 2 | 0.1.0 | | | **Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1 | 0 |"
broken = {
row: row.replace("0.1.0", "0.1"),
"| 1 | 2 | 1 | 2 | 4 | 2.1 by 1 |": "| 5 | 2 | 1 | 2 | 4 | 2.1 by 1 |",
"Tighten the tests.** | 1 | 2 | 1 | 2 | 4 |": "Tighten the tests.** | 1 | 4 | 1 | 2 | 4 |",
"Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1": "Tighten the tests.** | 1 | 2 | 6 | 2 | 4 | 2.1",
"Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by": "Tighten the tests.** | 0 | 2 | 1 | 2 | 4 | 2.1 by",
"| 2 | 4 | 2.1 by 1 | 0 |\n| 3": "| 2 | 11 | 2.1 by 1 | 0 |\n| 3",
"Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 1": "Tighten the tests.** | 1 | 2 | 1 | 2 | 4 | 2.1 by 11",
"Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1": "Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 0",
"2.1 by 8, 1 by 6": "2.1: 8, 1: 6",
"2.1 by 8, 1 by 6 ": "2.1 by 8,1 by 6 ",
"| 2 | 1 | 2 | 3 | 7 | 2.1 by 8, 1 by 6 |": "| 2 | 1 | 2 | 3 | 7 | 2.1, 1 |",
row + "\n": row.replace("2 | 4 |", "2 | ² |") + "\n",
"| 2.1 by 1 | 0 |\n\n## Details": "| 2.1 by 1 | 0 |\n\n| 9 | 0.1.0 | | | **Stray.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 0 |\n\n## Details",
"| 4 | 0.1.0 | | security |": "| 4 | 0.1.0 | | later |",
"| 5 | 0.1.0 | | decision |": "| 5 | 0.1.0 | | |",
"`Next ID = 6`": "`Next ID = 5`",
"`Next ID = 6`\n": "`Next ID = 6.5`\n",
"| 4 | 0.1.0 | | security | **Rotate": "| 4 | 0.1.0 | | decision | **Rotate",
"Fast detail.": "```\n## Goals\n```",
"### 3. Make it fast.": "### 7. Make it fast.",
"`Bar = 2`": "`Bar = nan`",
"## Items\n\n| ID | Release | Blocked by |": "## Plan\n\n| ID | Release |",
}
for old, new in broken.items():
with self.subTest(new=new):
self.assertIn(old, TODO)
self.assertIsInstance(self.ranked(TODO.replace(old, new)), Failure)
# A scoring run of the project whose overall mean is {overall}.
SCORED = "# Comprehension history\n\n## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mid A | 6 |\n| Mean | {overall} |\n"
class CodeHealth(unittest.TestCase):
readme = "## Goals\n\n1. **Achieve:** A.\n"
todo = TODO.split("| 1 | 0.2.0", 1)[0].replace("`Bar = 2`", "`Bar = 0.1`") + "| 1 | 0.1.0 | | | **Read easier.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 0 |\n| 2 | 0.1.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 0 |\n"
def scores(self, history, readme=readme):
ranked = ranking.rank(self.todo, readme, "", history)
return ranked if isinstance(ranked, Failure) else {line.split(" | ")[0]: line.rsplit(" | ", 1)[1].rstrip(" |") for line in ranked.text.splitlines() if line.startswith("| ") and " 0.1.0 " in line}
def entry(self, overall, at="2026-10-08T12", read="PR #1 at aaaaaaa"):
"""A scoring run's entry, without the history's title."""
return SCORED.format(overall=overall).removeprefix("# Comprehension history\n\n").replace("2026-10-08T12", at).replace("PR #1 at aaaaaaa", read)
def test_ranks_code_health_first_among_the_achieve_goals_at_an_overall_of_7_or_above(self):
# Code health, then goal 1: weights 1 / 1.97 and 0.97 / 1.97, an item moving one by 1 at S 1 scoring 50 times its weight.
self.assertEqual(self.scores(SCORED.format(overall="7.00")), {"| 1": "25.4", "| 2": "24.6"})
def test_weighs_code_health_four_times_as_much_under_an_overall_of_7_and_before_any_scoring_run(self):
for history in (SCORED.format(overall="6.99"), "", "# Comprehension history\n\n## 2026-10-09T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nRuling: better\n"):
with self.subTest(history=history):
self.assertEqual(self.scores(history), {"| 1": "101.5", "| 2": "24.6"})
def test_weighs_by_the_newest_scored_commit_wherever_the_file_holds_it(self):
older = self.entry("6.50")
newer = self.entry("7.25", "2026-10-10T12", "PR #1 at bbbbbbb")
for history in (f"{older}\n{newer}", f"{newer}\n{older}"):
with self.subTest(history=history):
self.assertEqual(self.scores(history)["| 1"], "25.4")
def test_weighs_by_the_mean_overall_of_every_run_on_the_newest_scored_commit(self):
# 7.13 and 6.88 average 7.005, at the floor or above; 7.10 and 6.80 average 6.95, under it.
for first, rerun, value in (("7.13", "6.88", "25.4"), ("7.10", "6.80", "101.5")):
with self.subTest(first=first, rerun=rerun):
self.assertEqual(self.scores(f"{self.entry(first)}\n{self.entry(rerun, '2026-10-08T13', 'PR #1 rerun at aaaaaaa')}")["| 1"], value)
later = self.entry("6.50", "2026-10-09T12", "PR #2 at bbbbbbb")
self.assertEqual(self.scores(f"{self.entry('7.13')}\n{self.entry('6.88', '2026-10-08T13', 'PR #1 rerun at aaaaaaa')}\n{later}")["| 1"], "101.5")
def test_matches_a_commit_whichever_length_a_heading_writes_it_at(self):
full = "aaaaaaa" + "0" * 33
# As runs of one commit, 7.13 and 6.88 average 7.005; the newer alone is under the floor.
for first, rerun in (("aaaaaaa", full), (full, "aaaaaaa")):
with self.subTest(first=first, rerun=rerun):
self.assertEqual(self.scores(f"{self.entry('7.13', read=f'PR #1 at {first}')}\n{self.entry('6.88', '2026-10-08T13', f'PR #1 rerun at {rerun}')}")["| 1"], "25.4")
def test_weighs_by_a_ruling_that_holds_scoring_seats_places(self):
# A ruling recorded before PR #255 scored the project too: below its votes, a scores table with a Mean row, and each scoring seat's places.
ruling = "## 2026-10-10T12:00:00Z, PR #2 at bbbbbbb, against aaaaaaa\n\nRuling: better\n\n| Seat | Overall |\n|---|---|\n| Mid A | better |\n\n| Seat | Overall |\n|---|---|\n| Mid A | 7.5 |\n| Mean | 7.25 |\n\nJunior A, hardest first:\n\n- `bin/a.py:1` `f`: long\n"
self.assertEqual(self.scores(f"{self.entry('6.50')}\n{ruling}")["| 1"], "25.4")
def test_refuses_a_newest_scoring_run_with_no_overall_mean(self):
for history in (SCORED.format(overall="high"), SCORED.split("| Mean")[0]):
with self.subTest(history=history):
self.assertEqual(self.scores(history), Failure("docs/comprehension-history.md's scoring run 2026-10-08T12:00:00Z, PR #1 at aaaaaaa has no Mean row ending in its overall, which sets code health's weight"))
def test_drops_code_health_where_readme_voids_it(self):
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
self.assertEqual(self.scores("", voided), Failure("item 1 names code health, which the goals file voids; drop it from the item's Moves, or the void from the goals file"))
ranked = ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", "")
self.assertIn("| **Read easier.** | 1 | 1 | 1 | 1 | 1 | 1 by 2 | 100.0 |", ranked.text)
def test_weighs_a_defects_maintain_goal_as_code_health_four_times_over_under_an_overall_of_7(self):
readme = "## Goals\n\n1. **Achieve:** A.\n2. **Maintain:** B.\n"
todo = self.todo.replace("| 2 | 0.1.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 |", "| 2 | 0.1.0 | | defect | **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 |")
for history, value in (("", "101.5"), (SCORED.format(overall="7.00"), "25.4")):
with self.subTest(history=history):
self.assertIn(f"| **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 | {value} |", ranking.rank(todo, readme, "", history).text)
def test_refuses_a_plan_whose_project_opts_out_of_the_comprehension_check_yet_keeps_code_health(self):
opted_out = "## review opt-out: the architect and the comprehension check\n\nCosts rounds.\n"
self.assertEqual(ranking.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in the goals file's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
self.assertIsInstance(ranking.rank(self.todo, self.readme, opted_out.replace(" and the comprehension check", ""), ""), ranking.Ranked)
voided = "## Goals\n\n**Void:** code health, since nobody reads the probes.\n\n1. **Achieve:** A.\n"
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, opted_out, ""), ranking.Ranked)
def test_ranks_a_project_that_voids_code_health_whatever_its_history_holds(self):
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", SCORED.format(overall="high")), ranking.Ranked)
def test_refuses_a_void_of_anything_but_code_health(self):
self.assertEqual(self.scores("", "## Goals\n\n**Void:** speed, since nobody waits.\n\n1. **Achieve:** A.\n"), Failure("the goals file's ## Goals voids `speed, since nobody waits.`; only code health may be voided, as `**Void:** code health, since <reason>.`"))
def test_shows_the_spelling_of_a_void_of_code_health_that_misses_it(self):
for void in ("code health.", "Code health, since it is a one-off script.", "code health since it is a one-off script."):
with self.subTest(void=void):
self.assertEqual(self.scores("", f"## Goals\n\n**Void:** {void}\n\n1. **Achieve:** A.\n"), Failure(f"the goals file's ## Goals voids code health as `{void}`; spell the void exactly `**Void:** code health, since <reason>.`"))
def test_parses_code_health_in_a_moves_cell(self):
self.assertEqual(todo_table.parse_moves("1", "code health by 4, 1.1 by 2"), (("code health", 4), ("1.1", 2)))
self.assertIsInstance(todo_table.parse_moves("1", "code health by 11"), Failure)
self.assertIsInstance(todo_table.parse_moves("1", "health by 4"), Failure)
def test_reads_the_history_beside_todo_md_and_the_goals_the_config_names(self):
with tempfile.TemporaryDirectory() as temp:
todo = pathlib.Path(temp, "todo.md")
todo.write_text(self.todo)
folder = configured(self, pathlib.Path(temp), goals="folder:goals.md")
(folder / "goals.md").write_text(self.readme)
pathlib.Path(temp, "docs").mkdir()
pathlib.Path(temp, "docs", "comprehension-history.md").write_text(SCORED.format(overall="7.00"))
with contextlib.redirect_stderr(io.StringIO()):
ranked = plan_file.rank_file(todo)
self.assertIsInstance(ranked, ranking.Ranked)
self.assertEqual(ranked.under_bar, [])
self.assertIn("| code health by 1 | 25.4 |", todo.read_text())
class Risk(unittest.TestCase):
"""R is L + E + I - 2, which rank_todo.py writes, at least 7 when I is 5 and at least 5 when I is 4."""
def ranked(self, todo):
return ranking.rank(todo, README, DECISIONS, "")
def test_writes_r_from_l_e_and_i_over_a_stale_or_missing_r(self):
ranked = self.ranked(TODO).text
for levels, risk in (("| 1 | 1 | 1 |", 1), ("| 2 | 1 | 2 |", 3), ("| 1 | 2 | 1 |", 2)):
with self.subTest(levels=levels):
self.assertIn(f"{levels} {risk} |", ranked)
stale = TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 2 | 1 | 2 | 10 | 7 |")
self.assertEqual(self.ranked(stale).text, ranked)
without_r = TODO.replace("| I | R | S |", "| I | S |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|")
without_r = re.sub(r"(\*\* \| \d+ \| \d+ \| \d+) \| \d+ \|", r"\1 |", without_r)
self.assertEqual(self.ranked(without_r).text, ranked)
def test_writes_r_into_a_blank_r_cell(self):
blank = TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 2 | 1 | 2 | | 7 |")
self.assertEqual(self.ranked(blank).text, self.ranked(TODO).text)
def test_leaves_a_stale_r_to_ranking_so_a_reader_keeps_the_r_the_table_stored(self):
stale = TODO.replace("| 2 | 1 | 2 | 3 | 7 |", "| 2 | 1 | 2 | 10 | 7 |")
self.assertEqual(next(item for item in todo_table.items(stale) if item.id == 3).scores["R"], 10)
self.assertNotEqual(self.ranked(stale).text, stale)
def test_holds_r_at_7_when_i_is_5_and_at_5_when_i_is_4(self):
cases = {"| 1 | 1 | 5 |": 7, "| 1 | 1 | 4 |": 5, "| 2 | 2 | 4 |": 6, "| 4 | 3 | 5 |": 10, "| 3 | 3 | 3 |": 7}
for levels, risk in cases.items():
with self.subTest(levels=levels):
ranked = self.ranked(TODO.replace("| 1 | 2 | 1 | 2 | 4 |", f"{levels} 1 | 4 |"))
self.assertIn(f"**Tighten the tests.** {levels} {risk} | 4 |", ranked.text)
def test_routes_a_worker_on_l_and_its_reviewers_on_e_plus_i(self):
item = next(item for item in todo_table.items(TODO) if item.id == 4)
self.assertEqual((item.likelihood, item.escape_and_impact), (3, 8))
def test_names_the_one_level_column_a_table_lacks(self):
without_i = TODO.replace("| E | I | R |", "| E | R |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|---|")
without_i = re.sub(r"(\*\* \| \d+ \| \d+) \| \d+ \|", r"\1 |", without_i)
self.assertEqual(self.ranked(without_i), Failure("todo.md's items table has no I column; add it, scoring each item's L, E and I as rank_todo.py --help shows"))
def test_asks_a_table_from_before_l_e_and_i_for_them_yet_reads_its_rows(self):
before = TODO.replace("| L | E | I | R | S | Moves |", "| R | S | C | Moves |").replace("|---|---|---|---|---|---|---|---|---|---|---|---|", "|---|---|---|---|---|---|---|---|---|---|")
before = re.sub(r"(\*\* \|) \d+ \| \d+ \| \d+ \| (\d+) \| (\d+) \|", r"\1 \2 | \3 | 3 |", before)
self.assertEqual(self.ranked(before), Failure("todo.md's items table has no L, E and I columns; add them, scoring each item's L, E and I as rank_todo.py --help shows, and drop C"))
items = todo_table.items(before)
self.assertEqual([(item.scores, item.likelihood, item.escape_and_impact) for item in items][1], ({"R": 2, "S": 4}, 0, 0))
class OldShape(unittest.TestCase):
"""A table with A, G and Goals, from before the Moves column, ranks by the formula and goal weights it states until its project reshapes it."""
def ranked(self, todo=OLD_SHAPE, readme=README):
return ranking.rank(todo, readme, DECISIONS, "")
def test_scores_by_the_stated_weights_and_says_to_reshape(self):
ranked = self.ranked()
self.assertIn("""| 4 | 0.1.0 | | security | **Rotate the leaked key.** | 9 | 2 | 3 | 1 | 1 | 2.1 | -6.8 |
| 3 | 0.1.0 | | | **Make it fast, `a \\| b`.** | 3 | 8 | 3 | 6 | 8 | 2.1, 1 | 23.0 |
| 2 | 0.1.0 | | | **Tighten the tests.** | 2 | 4 | 3 | 5 | 5 | 2.1 | 10.3 |
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 5.1 |
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 34.8 |
""", ranked.text)
self.assertEqual(ranked.notes, [ranking.RESHAPE])
self.assertEqual(self.ranked(ranked.text), ranked)
unmarked = "# P\n\n## Goals\n\n1. Fast.\n2. Correct.\n 1. Tested.\n"
self.assertEqual(self.ranked(readme=unmarked), ranked)
def test_prints_the_positional_weights_when_they_stop_listing_the_readmes_goals(self):
failure = self.ranked(readme=README.replace(" 1. **Achieve:** Tested.", " 1. **Achieve:** Tested.\n3. Small."))
self.assertIn("| 1 | 1.00 |\n| 2 | 0.75 |\n| 2.1 | 0.50 |\n| 3 | 0.25 |", failure.reason)
def test_refuses_an_item_citing_a_goal_the_weights_do_not_list(self):
self.assertEqual(self.ranked(OLD_SHAPE.replace("| 2.1, 1 | 0 |", "| 2.1, 9 | 0 |")), Failure("item 3 cites goal 9, which the goal weights do not list"))
def test_refuses_a_formula_over_v(self):
self.assertEqual(self.ranked(OLD_SHAPE.replace("-R - S/4 + 2*A + 2*G*W", "V")), Failure("the formula 'V' may hold only numbers, A, G, R, S, W, + - * / ** and parentheses"))
def test_ranks_a_table_from_before_c_joined_and_says_to_reshape_it(self):
legacy = OLD_SHAPE.split("## Items")[0] + "## Items\n\n| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 5 | 5 | 2.1 | 0 |\n"
self.assertEqual(ranking.rank(legacy, README, "", "").notes, [ranking.RESHAPE])
def test_refuses_a_table_with_both_moves_and_goals(self):
both = OLD_SHAPE.replace("| Goals | Score |\n|---|", "| Goals | Moves | Score |\n|---|---|").replace(" | 0 |\n", " | 1 by 1 | 0 |\n")
self.assertEqual(self.ranked(both), Failure("todo.md's items table has no L, E and I columns; add them, scoring each item's L, E and I as rank_todo.py --help shows, and drop C, A, G and Goals"))
one = TODO.replace("| Moves | Score |\n|---|", "| Moves | G | Score |\n|---|---|").replace(" | 0 |\n", " | 1 | 0 |\n")
self.assertEqual(self.ranked(one), Failure("todo.md's items table has G, a column of an older shape; drop it, as rank_todo.py --help shows"))
def test_names_the_goals_column_a_table_misspells_by_its_shape(self):
misspelt = TODO.replace("| S | Moves |", "| S | Move |")
self.assertEqual(ranking.rank(misspelt, README, DECISIONS, ""), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(todo_table.items(misspelt), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
self.assertEqual(self.ranked(OLD_SHAPE.replace("| G | Goals |", "| G | Goal |")), Failure("todo.md's items table has no Goals column; rank_todo.py --help shows a valid one"))
class Renamed(unittest.TestCase):
def test_reads_the_releases_the_renamed_section_names(self):
self.assertEqual(todo_table.renames("## Items\n\n## Details\n"), set())
self.assertEqual(todo_table.renames("## Renamed\n\n- 0.2.1 renamed to 0.3.0\n- 0.3.0 renamed to 0.4.0\n\n## Details\n"), {(0, 2, 1), (0, 3, 0)})
self.assertEqual(todo_table.renames("## Renamed\n\n- 0.2.1 renamed to 0.3.0 \n"), {(0, 2, 1)})
for bad in ("soon", "- 0.2.1 is now 0.3.0", "- 0.2 renamed to 0.3.0", "- 0.2.1 renamed to 0.3.0 later", "- 0.2.1 renamed to 0.2.1"):
with self.subTest(bad):
self.assertIsInstance(todo_table.renames(f"## Renamed\n\n{bad}\n"), Failure)
def test_fails_on_a_renamed_section_that_does_not_parse(self):
failed = ranking.rank(TODO + "\n## Renamed\n\nsoon\n", README, DECISIONS, "")
self.assertIsInstance(failed, Failure)
self.assertIn("## Renamed", failed.reason)
def test_ranks_a_plan_with_a_valid_renamed_section(self):
self.assertIsInstance(ranking.rank(TODO + "\n## Renamed\n\n- 0.3.0 renamed to 0.4.0\n", README, DECISIONS, ""), ranking.Ranked)
def test_fails_on_an_item_filed_under_a_release_the_plan_marks_renamed(self):
live = ranking.rank(TODO + "\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", README, DECISIONS, "")
self.assertIsInstance(live, Failure)
self.assertIn("marks release 0.2.0 renamed but files item 1 under it", live.reason)
class ThisRepo(unittest.TestCase):
def test_todo_md_is_ranked_with_nothing_under_the_bar(self):
text = (ROOT / "todo.md").read_text(encoding="utf-8")
ranked = ranking.rank(text, *((ROOT / name).read_text(encoding="utf-8") for name in ("README.md", "docs/decisions.md", "docs/comprehension-history.md")))
self.assertEqual(ranked, ranking.Ranked(text, [], []))