Files

363 lines
18 KiB
Python

import dataclasses
import re
import typing
from failure import Failure
from text_files.markdown_text import FENCE, sections
from plan.release import parsed, Release, release_of, version, 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 goals file.
CODE_HEALTH = "code health"
# The scope that opens a goal's name in the Moves of an epic's item, since the epic and the item's repo both number their goals from 1: `epic 1.1 by 8, code health by 5, repo 2 by 4`. Three readers, seated as the human who writes these cells, picked a scope word on both goals, 3-0, over one on either alone and over the repo's name. A todo.md's item may name neither.
EPIC_GOAL = "epic "
REPO_GOAL = "repo "
# 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 what a failure calls the item, 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(label: 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 the goals file."""
matches = [re.fullmatch(rf"((?:{EPIC_GOAL}|{REPO_GOAL})?[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"{label}'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"{label} 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"{label} 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(label: 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.
# Live: rank_todo.py ranks a table in this shape, so a project that has not reshaped yet can still commit. `todo.md` item 156 drops that ranking once no project holds such a table; score_outcomes goes on reading old tables out of git history.
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, ...]
# Empty where the item has none, and where a reader took only the table.
detail: str = ""
# The pull request, as `#<number> <URL>`, whose merge by a person the item awaits; empty where it awaits none, and where the reader asked no forge. release_plan.awaiting_merge sets it.
awaits_merge: str = ""
@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, each that awaits a person's merge of its pull request, and each 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 item.awaits_merge 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 the goals file 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))
id_, tagline = named["ID"], 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"\*\*[^*].*[^*]\*\*", tagline):
return Failure(f"item {id_}'s Item cell is not one bold tagline: {tagline}")
shape = shape_of(table.columns)
fields = item_fields({name: cell for name, cell in named.items() if cell or name not in shape.derived}, f"item {id_}", shape, int(id_))
if isinstance(fields, Failure):
return fields
assert fields.release is not None, "table_rows refuses a table without a Release column"
return Item(int(id_), fields.release, fields.exempt, tagline, fields.scores, fields.moves, fields.blocked_by)
@dataclasses.dataclass(frozen=True)
class ItemFields:
"""The cells of an item that a caller named, each held to the items table's format. A cell it didn't name reads as empty, and the release as None."""
release: Release | None = None
exempt: Exempt = ""
scores: dict[str, int] = dataclasses.field(default_factory=dict)
moves: Moves = ()
blocked_by: tuple[int, ...] = ()
def item_fields(named: dict[str, str], label: str, shape: Shape = SHAPE, id_: int | None = None) -> ItemFields | Failure:
"""Each of the Release, Exempt, score, goals and Blocked-by cells that named holds by column name, held to shape's format; the one check every plan backend makes of an item's cells. label opens each message, such as "item 12" or "the item to file". id_ is the item's own ID, which its Blocked by may not name."""
release = named.get("Release")
if release is not None and parsed(release) is None:
return Failure(f"{label}'s Release {release!r} is not a semver version, such as 1.2.0")
exempt = named.get("Exempt", "")
if not is_exempt(exempt):
return Failure(f"{label}'s Exempt {exempt!r} is not empty or one of {', '.join(EXEMPTIONS[1:])}")
scores = parse_scores(label, named, shape.score_columns)
if isinstance(scores, Failure):
return scores
moves = shape.read_goals(label, named.get(shape.goals_column, ""))
if isinstance(moves, Failure):
return moves
blocked_by = parse_ids(named.get(BLOCKED_BY, ""))
if blocked_by is None:
return Failure(f"{label}'s {BLOCKED_BY} {named[BLOCKED_BY]!r} is not empty or IDs separated by \", \"")
if id_ in blocked_by:
return Failure(f"{label} is blocked by itself; drop {id_} from its {BLOCKED_BY}")
return ItemFields(None if release is None else release_of(release), exempt, scores, moves, blocked_by)
def is_exempt(cell: str) -> typing.TypeGuard[Exempt]:
return cell in EXEMPTIONS
def parse_scores(label: str, named: dict[str, str], names: tuple[str, ...]) -> dict[str, int] | Failure:
"""Each score in names that named 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"{label}'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 row_cells(item: Item, shape: Shape) -> dict[str, str]:
"""item's cells by column name, as a row of a table in shape holds them; the Score, which only ranking works out, aside."""
return {"ID": str(item.id), "Release": version(item.release), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves)}
def tagline_text(cell: str) -> str:
"""The tagline an Item cell holds, as plain text: without the bold, each | unescaped."""
return cell.strip().removeprefix("**").removesuffix("**").replace("\\|", "|")
def detail_heading(id_: int, tagline: str) -> str:
"""The heading under ## Details that opens item id_'s detail; tagline is plain text."""
return f"### {id_}. {tagline}"
def items_shape(found: list[Item]) -> Shape:
"""The shape a table of found needs: OLD_SHAPE where an item holds a score only that shape has, as a plan not yet reshaped does."""
return OLD_SHAPE if any(set(item.scores) - set(SHAPE.score_columns) for item in found) else SHAPE