358 lines
18 KiB
Python
358 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"
|
|
# 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"([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 = ""
|
|
|
|
@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 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
|