247 lines
11 KiB
Python
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
|