329 lines
15 KiB
Python
329 lines
15 KiB
Python
import dataclasses
|
|
import re
|
|
import typing
|
|
|
|
from failure import Failure
|
|
from records.markdown_text import FENCE, sections
|
|
from release_plan.release import parsed, Release, release_of, VERSION
|
|
|
|
# Each score a Shape names, and each goal's move, runs from 1 to TOP_SCORE, but for the levels L, E and I, which run from 1 to their LEVELS: ~/.claude/rules/todo-items.md defines each level.
|
|
TOP_SCORE = 10
|
|
LEVELS = {"L": 4, "E": 3, "I": 5}
|
|
# The least R each impact level I allows, since a severe enough consequence outranks how unlikely it is.
|
|
RISK_FLOOR = {4: 5, 5: 7}
|
|
# The highest R an item may have and still share a chunk; `docs/decisions.md` → `chunks:` says why 5.
|
|
BUNDLE_MAX_R = 5
|
|
# What an Exempt cell may hold: empty, or a reason ~/.claude/rules/todo-items.md defines.
|
|
Exempt = typing.Literal["", "decision", "defect", "owner", "principle", "question", "security"]
|
|
EXEMPTIONS: tuple[Exempt, ...] = typing.get_args(Exempt)
|
|
# The column naming the items that block an item: each must be done before the item starts.
|
|
BLOCKED_BY = "Blocked by"
|
|
# The column naming each achieve goal an item moves and how far, such as `1.1 by 8, 1.2 by 5`.
|
|
MOVES = "Moves"
|
|
# The achieve goal every project shares, which ~/.claude/CLAUDE.md → "Shared goal" states, and a Moves cell names by these words, since it has no number in any README.
|
|
CODE_HEALTH = "code health"
|
|
# How the items table's header opens, which tells it from any other table in todo.md.
|
|
HEADER_START = "| ID | Release |"
|
|
# todo.md's ## Details section, its body the first group.
|
|
DETAILS = re.compile(r"^## Details\n(.*?)(?=^## |\Z)", re.M | re.S)
|
|
# One line of todo.md's ## Renamed section: the release it renamed and the one it became.
|
|
RENAME = re.compile(rf"- ({VERSION}) renamed to ({VERSION})")
|
|
# Each goal an item names, in its order, with how far the item moves it; None in OLD_SHAPE, whose Goals cell names no move.
|
|
Moves = tuple[tuple[str, int | None], ...]
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Shape:
|
|
"""A shape of the items table: its columns, and how its goals cell reads and writes."""
|
|
# The score columns, in the order the table holds them.
|
|
score_columns: tuple[str, ...]
|
|
# The columns a reader does without: a missing BLOCKED_BY reads as not blocked, a missing score column as that score unset, and a missing Score column as not yet ranked.
|
|
optional: tuple[str, ...]
|
|
# The columns rank_todo.py needs to rank a row, so no chunk starts on an item whose risk is unscored.
|
|
risk_columns: tuple[str, ...]
|
|
# The scores rank_todo.py works out and writes, so a blank cell reads as no score yet.
|
|
derived: tuple[str, ...]
|
|
# The column naming the goals an item serves; read_goals reads it, given the item's ID to name in a failure, and write_goals writes it back.
|
|
goals_column: str
|
|
read_goals: typing.Callable[[str, str], Moves | Failure]
|
|
write_goals: typing.Callable[[Moves], str]
|
|
|
|
@property
|
|
def columns(self) -> tuple[str, ...]:
|
|
"""Every column of the shape, in order. A reader takes cells by column name, so it reads a table from before an optional column joined, or with a column a later release adds."""
|
|
return ("ID", "Release", BLOCKED_BY, "Exempt", "Item", *self.score_columns, self.goals_column, "Score")
|
|
|
|
@property
|
|
def needed(self) -> tuple[str, ...]:
|
|
"""The columns without which no row can be read."""
|
|
return tuple(column for column in self.columns if column not in self.optional)
|
|
|
|
|
|
def parse_moves(id_: str, cell: str) -> Moves | Failure:
|
|
"""A Moves cell: empty, or each goal the item moves, named once, and how far. ranking.py's cited_goals_failure holds the rules that need README.md."""
|
|
matches = [re.fullmatch(rf"([0-9]+(?:\.[0-9]+)*|{CODE_HEALTH}) by ([0-9]+)", move) for move in cell.split(", ")] if cell else []
|
|
moves = tuple((match.group(1), int(match.group(2))) for match in matches if match)
|
|
if len(moves) < len(matches) or any(not 1 <= by <= TOP_SCORE for _, by in moves):
|
|
return Failure(f"item {id_}'s {MOVES} {cell!r} is not empty or goals such as `1.1 by 8, {CODE_HEALTH} by 5`, each moved by a whole number from 1 to {TOP_SCORE}")
|
|
goals = [goal for goal, _ in moves]
|
|
if repeated := [goal for goal in goals if goals.count(goal) > 1]:
|
|
return Failure(f"item {id_} cites goal {repeated[0]} twice; name each goal once")
|
|
if nested := [(parent, goal) for parent in goals for goal in goals if goal.startswith(parent + ".")]:
|
|
return Failure(f"item {id_} names goal {nested[0][0]} and its sub-goal {nested[0][1]}; name one, never both: the sub-goal where the move serves it, else the parent")
|
|
return moves
|
|
|
|
|
|
def write_moves(moves: Moves) -> str:
|
|
return ", ".join(f"{goal} by {by}" for goal, by in moves)
|
|
|
|
|
|
def parse_cited(id_: str, cell: str) -> Moves:
|
|
"""An old-shape Goals cell, such as `2.1, 1`: each goal it cites, with no move."""
|
|
return tuple((goal.strip(), None) for goal in cell.split(","))
|
|
|
|
|
|
def write_cited(moves: Moves) -> str:
|
|
return ", ".join(goal for goal, _ in moves)
|
|
|
|
|
|
# L, E and I are optional, since score_outcomes reads, out of git history, tables from before they replaced C; R too, since rank_todo.py writes it from them.
|
|
SHAPE = Shape(("L", "E", "I", "R", "S"), (BLOCKED_BY, "L", "E", "I", "R", "Score"), ("L", "E", "I"), ("R",), MOVES, parse_moves, write_moves)
|
|
# The shape from before MOVES replaced A, G and Goals, and L, E and I replaced C, which older todo.md files hold; one from before C joined lacks it.
|
|
OLD_SHAPE = Shape(("R", "S", "C", "A", "G"), (BLOCKED_BY, "C", "Score"), (), (), "Goals", parse_cited, write_cited)
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Item:
|
|
id: int
|
|
release: Release
|
|
exempt: Exempt
|
|
tagline: str
|
|
scores: dict[str, int]
|
|
moves: Moves
|
|
blocked_by: tuple[int, ...]
|
|
|
|
@property
|
|
def likelihood(self) -> int:
|
|
"""L, which routes the item's worker to a rung; 0 without one."""
|
|
return self.scores.get("L", 0)
|
|
|
|
@property
|
|
def escape_and_impact(self) -> int:
|
|
"""E + I, which routes the item's reviewers to a rung; 0 without them."""
|
|
return self.scores["E"] + self.scores["I"] if "E" in self.scores and "I" in self.scores else 0
|
|
|
|
|
|
def risk(likelihood: int, escape: int, impact: int) -> int:
|
|
"""R from its levels: L + E + I - 2, never under RISK_FLOOR's value for I."""
|
|
return max(likelihood + escape + impact - 2, RISK_FLOOR.get(impact, 0))
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Table:
|
|
"""A markdown table: the index of its header in the file's lines, its column names, and its body rows."""
|
|
header: int
|
|
columns: tuple[str, ...]
|
|
rows: list[str]
|
|
|
|
@property
|
|
def start(self) -> int:
|
|
"""The index of the first body row, below the header and the divider."""
|
|
return self.header + 2
|
|
|
|
|
|
def shape_of(columns: tuple[str, ...]) -> Shape:
|
|
"""OLD_SHAPE where the columns include A, G or Goals and not MOVES; else SHAPE, so a misspelt MOVES is reported missing."""
|
|
return OLD_SHAPE if MOVES not in columns and {"A", "G", OLD_SHAPE.goals_column}.intersection(columns) else SHAPE
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class NoItemsTable(Failure):
|
|
"""todo.md holds no items table. A table with no rows is not a NoItemsTable: items returns an empty list for it."""
|
|
|
|
|
|
def items(todo: str) -> list[Item] | Failure:
|
|
"""Each row of a todo.md's items table; a NoItemsTable where todo.md holds none."""
|
|
table = items_table(todo.splitlines())
|
|
if table is None:
|
|
return NoItemsTable("todo.md holds no items table")
|
|
if isinstance(table, Failure):
|
|
return table
|
|
found = []
|
|
for row in table.rows:
|
|
item = parse_row(row, table)
|
|
if isinstance(item, Failure):
|
|
return item
|
|
found.append(item)
|
|
return found
|
|
|
|
|
|
def items_table(lines: list[str]) -> Table | None | Failure:
|
|
"""The table whose header opens with HEADER_START; None where there is none."""
|
|
headers = [line for line in lines if line.startswith(HEADER_START)]
|
|
if not headers:
|
|
return None
|
|
if len(headers) > 1:
|
|
return Failure(f"todo.md holds {len(headers)} tables whose header opens {HEADER_START}; keep one items table")
|
|
table = table_rows(lines, headers[0])
|
|
if isinstance(table, Failure):
|
|
return table
|
|
if repeated := sorted({column for column in table.columns if table.columns.count(column) > 1}):
|
|
return Failure(f"todo.md's items table names the column {', '.join(repeated)} twice; keep one")
|
|
if missing := [column for column in shape_of(table.columns).needed if column not in table.columns]:
|
|
return Failure(f"todo.md's items table has no {', '.join(missing)} column; rank_todo.py --help shows a valid one")
|
|
return table
|
|
|
|
|
|
def waiting(found: list[Item], done: set[int]) -> set[int]:
|
|
"""The IDs of the items that wait: each marked question, or blocked by an item the table still holds and done does not name. Row order does not change the result."""
|
|
held = {item.id for item in found} - done
|
|
return {item.id for item in found if item.exempt == "question" or held.intersection(item.blocked_by)}
|
|
|
|
|
|
def next_item(found: list[Item]) -> Item | None:
|
|
"""The earliest release's first row that does not wait, as waiting says, in the table's order; release_standing.chunk_item takes it as the next chunk's first item where its release is the next."""
|
|
if not found:
|
|
return None
|
|
release = min(item.release for item in found)
|
|
waits = waiting(found, set())
|
|
return next((item for item in found if item.release == release and item.id not in waits), None)
|
|
|
|
|
|
def renames(todo: str) -> set[Release] | Failure:
|
|
"""Each release todo.md's ## Renamed section says was renamed, as `- 0.2.1 renamed to 0.3.0`, so never finished; the tools read only the old release. `docs/decisions.md` → `todo.md: one table …` gives the rule and the spelling's pick."""
|
|
marked: set[Release] = set()
|
|
for body in sections(todo).get("Renamed", []):
|
|
for line in body.splitlines():
|
|
rename = RENAME.fullmatch(line.strip())
|
|
if rename is None:
|
|
return Failure(f"todo.md's ## Renamed section holds {line.strip()!r}, not a line such as `- 0.2.1 renamed to 0.3.0`")
|
|
if rename.group(1) == rename.group(2):
|
|
return Failure(f"todo.md's ## Renamed section renames {rename.group(1)} to itself; name the release it became")
|
|
marked.add(release_of(rename.group(1)))
|
|
return marked
|
|
|
|
|
|
def ships_alone(item: Item) -> bool:
|
|
"""An item above BUNDLE_MAX_R joins no chunk, and none joins it. R is worked out from L, E and I, so a row whose R cell rank_todo.py has not filled yet still counts. An old-shape table has no L, E or I, so none of its items ships alone."""
|
|
scores = item.scores
|
|
return all(level in scores for level in ("L", "E", "I")) and risk(scores["L"], scores["E"], scores["I"]) > BUNDLE_MAX_R
|
|
|
|
|
|
def bundle_candidates(found: list[Item], first: Item) -> list[Item]:
|
|
"""The items of first's release, in the table's order, that a chunk taking first may take too: those that do not ship alone, and do not wait once the chunk's own items count as done."""
|
|
if ships_alone(first):
|
|
return []
|
|
chunk = {item.id for item in found if item.release == first.release and not ships_alone(item)}
|
|
# Dropping an item that waits may make another wait on it, so drop until none waits.
|
|
while waits := waiting(found, chunk) & chunk:
|
|
chunk -= waits
|
|
return [item for item in found if item.id in chunk and item.id != first.id]
|
|
|
|
|
|
def item_details(todo: str) -> dict[int, str] | Failure:
|
|
"""Each item's detail under ## Details, by ID; empty where todo.md has no such section."""
|
|
section = DETAILS.search(todo)
|
|
if section is None:
|
|
return {}
|
|
# A fenced line such as "## Goals" or "### 2. x" would read as a heading and split a detail.
|
|
if FENCE.search(section.group(1)):
|
|
return Failure("## Details holds a fenced code block; indent quoted markdown by four spaces instead")
|
|
parts = re.split(r"^### (\d+)\. [^\n]*\n", section.group(1), flags=re.M)
|
|
if parts[0].strip():
|
|
return Failure("## Details holds text before its first ### <ID>. heading")
|
|
details: dict[int, str] = {}
|
|
for id_, detail in zip(parts[1::2], parts[2::2]):
|
|
if int(id_) in details:
|
|
return Failure(f"## Details holds item {id_} twice")
|
|
details[int(id_)] = detail.strip("\n")
|
|
return details
|
|
|
|
|
|
def table_rows(lines: list[str], header: str) -> Table | Failure:
|
|
if lines.count(header) != 1:
|
|
return Failure(f"todo.md needs the table header {header} once")
|
|
at = lines.index(header)
|
|
if at + 2 > len(lines) or not re.fullmatch(r"\|(-+\|)+", lines[at + 1].replace(" ", "")):
|
|
return Failure(f"the table under {header} has no |---| divider line")
|
|
end = at + 2
|
|
while end < len(lines) and lines[end].startswith("|"):
|
|
end += 1
|
|
columns = cells(header, header.count("|") - 1)
|
|
if isinstance(columns, Failure):
|
|
return columns
|
|
return Table(at, tuple(columns), lines[at + 2:end])
|
|
|
|
|
|
def cells(row: str, count: int) -> list[str] | Failure:
|
|
found = [cell.strip() for cell in re.split(r"(?<!\\)\|", row.strip())[1:-1]]
|
|
return found if len(found) == count else Failure(f"this row needs {count} cells: {row}")
|
|
|
|
|
|
def parse_row(row: str, table: Table) -> Item | Failure:
|
|
"""An item row of table, every cell checked but whether README.md numbers and weighs the goals it names."""
|
|
found = cells(row, len(table.columns))
|
|
if isinstance(found, Failure):
|
|
return found
|
|
named = dict(zip(table.columns, found))
|
|
exempt = check_cells(row, named)
|
|
if isinstance(exempt, Failure):
|
|
return exempt
|
|
shape = shape_of(table.columns)
|
|
scores = parse_scores(named["ID"], {name: cell for name, cell in named.items() if cell or name not in shape.derived}, shape.score_columns)
|
|
if isinstance(scores, Failure):
|
|
return scores
|
|
blocked_by = parse_blockers(named["ID"], named.get(BLOCKED_BY, ""))
|
|
if isinstance(blocked_by, Failure):
|
|
return blocked_by
|
|
moves = shape.read_goals(named["ID"], named[shape.goals_column])
|
|
if isinstance(moves, Failure):
|
|
return moves
|
|
return Item(int(named["ID"]), release_of(named["Release"]), exempt, named["Item"], scores, moves, blocked_by)
|
|
|
|
|
|
def is_exempt(cell: str) -> typing.TypeGuard[Exempt]:
|
|
return cell in EXEMPTIONS
|
|
|
|
|
|
def check_cells(row: str, named: dict[str, str]) -> Exempt | Failure:
|
|
"""Holds the row's ID, Release, Exempt and Item cells to the format: the row's Exempt cell, or why a cell breaks it."""
|
|
id_, release, exempt, tagline = named["ID"], named["Release"], named["Exempt"], named["Item"]
|
|
if not re.fullmatch(r"[0-9]+", id_) or int(id_) < 1:
|
|
return Failure(f"the ID {id_!r} is not a positive whole number: {row}")
|
|
if parsed(release) is None:
|
|
return Failure(f"item {id_}'s release {release!r} is not a semver version")
|
|
if not is_exempt(exempt):
|
|
return Failure(f"item {id_}'s Exempt {exempt!r} is not empty or one of {', '.join(EXEMPTIONS[1:])}")
|
|
if not re.fullmatch(r"\*\*[^*].*[^*]\*\*", tagline):
|
|
return Failure(f"item {id_}'s Item cell is not one bold tagline: {tagline}")
|
|
return exempt
|
|
|
|
|
|
def parse_scores(id_: str, named: dict[str, str], names: tuple[str, ...]) -> dict[str, int] | Failure:
|
|
"""Each score in names that the row holds; only an optional one may be missing, since the table holds every needed column."""
|
|
scores: dict[str, int] = {}
|
|
for name in names:
|
|
if name not in named:
|
|
continue
|
|
top = LEVELS.get(name, TOP_SCORE)
|
|
if not re.fullmatch(r"[0-9]+", named[name]) or not 1 <= int(named[name]) <= top:
|
|
return Failure(f"item {id_}'s {name} {named[name]!r} is not a whole number from 1 to {top}")
|
|
scores[name] = int(named[name])
|
|
return scores
|
|
|
|
|
|
def parse_ids(cell: str) -> tuple[int, ...] | None:
|
|
"""The item IDs a cell lists, such as `12, 14`: an empty tuple where the cell is empty, None where it holds anything else."""
|
|
if not re.fullmatch(r"([0-9]+(, [0-9]+)*)?", cell):
|
|
return None
|
|
return tuple(int(id_) for id_ in cell.split(", ") if id_)
|
|
|
|
|
|
def parse_blockers(id_: str, cell: str) -> tuple[int, ...] | Failure:
|
|
blocked_by = parse_ids(cell)
|
|
if blocked_by is None:
|
|
return Failure(f"item {id_}'s {BLOCKED_BY} {cell!r} is not empty or IDs separated by \", \"")
|
|
if int(id_) in blocked_by:
|
|
return Failure(f"item {id_} is blocked by itself; drop {id_} from its {BLOCKED_BY}")
|
|
return blocked_by
|