Files
claude-config/bin/todo_table.py
T

247 lines
11 KiB
Python

import dataclasses
import re
import typing
from failure import Failure
# 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}
EXEMPTIONS = ("", "decision", "defect", "owner", "principle", "question", "security")
# 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"
# How the items table's header opens, which tells it from any other table in todo.md.
HEADER_START = "| ID | Release |"
# 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 blocked by nothing, 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."""
matches = [re.fullmatch(r"([0-9]+(?:\.[0-9]+)*) 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, 1.2 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: tuple[int, int, int]
exempt: str
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
def items(todo: str) -> list[Item] | None | Failure:
"""Each row of a todo.md's items table; None where todo.md holds no items table."""
table = items_table(todo.splitlines())
if table is None or 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]) -> set[int]:
"""The IDs of the items that wait: each marked question, or blocked by an item the table still holds. Row order does not change the result."""
held = {item.id for item in found}
return {item.id for item in found if item.exempt == "question" or held.intersection(item.blocked_by)}
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))
if misformed := check_cells(row, named):
return misformed
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
major, minor, patch = (int(part) for part in named["Release"].split("."))
return Item(int(named["ID"]), (major, minor, patch), named["Exempt"], named["Item"], scores, moves, blocked_by)
def check_cells(row: str, named: dict[str, str]) -> Failure | None:
"""Holds the row's ID, Release, Exempt and Item cells to the format: why one breaks it, None when none does."""
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 not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", release):
return Failure(f"item {id_}'s release {release!r} is not a semver version")
if exempt not in EXEMPTIONS:
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 None
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