479 lines
30 KiB
Python
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, [], []))
|