Files
claude-config/bin/release_plan/ranking.py
T

545 lines
29 KiB
Python

"""Rank todo.md's items by the formula it states, weighing code health first and then README.md's achieve goals by their position, and hold them to its bar; rank_todo.py --help states the rules."""
import ast
import dataclasses
import decimal
import graphlib
import math
import pathlib
import re
import sys
import typing
from release_plan.todo_table import BLOCKED_BY, cells, CODE_HEALTH, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
from failure import Failure
from review_rules.comprehension_history import FLOOR, HISTORY, latest_overall
from records.markdown_text import listed, sections
from records.file_writes import replace_file
from release_plan.release import version
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
GOAL_STEP = 0.97
# Code health weighs this many times its weight by position while the comprehension panel's overall is under FLOOR, or unmeasured; lilleman's choice, which docs/decisions.md records.
UNDER_FLOOR = 4
# Any **Void:** line of README.md's ## Goals; ranked_goals accepts only `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
VOID = re.compile(r"^\*\*Void:\*\* (.*)$", re.M)
# A docs/decisions.md title opting the project out of the comprehension check, as larv-review's SKILL.md → "Opt-out" spells it.
OPTED_OUT = re.compile(r"^## review opt-out:.*\bcomprehension check\b", re.M)
LARGEST_FORMULA = 200
LONGEST_FORMULA = 4 * LARGEST_FORMULA
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
WEIGHTS_HEADER = "| Goal | W |"
# The Exempt reasons that rank ahead of the rest of their release, in this order: a question first, since its answer may change other items, then a security finding.
FIRST = {"question": 0, "security": 1}
# How README.md marks a goal; None where it marks it neither way.
Mark = typing.Literal["Maintain", "Achieve"] | None
RESHAPE = f"todo.md's items table is in the old shape, scoring A and G against goal weights todo.md states. Until todo.md has the shape rank_todo.py --help shows, reshaping it is the project's only work, as ~/.claude/CLAUDE.md → 'Working loop' says: mark README.md's goals **Maintain:** or **Achieve:**, name each item's {MOVES}, score its L, E and I in place of C, and set the bar below the score of every item to keep"
@dataclasses.dataclass(frozen=True)
class Scoring:
shape: Shape
formula: ast.Expression
bar: float
next_id: int
# Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. In OLD_SHAPE an item may name only the goals weights holds.
goals: dict[str, Mark]
# The weight of each goal an item may name: in OLD_SHAPE each of README.md's goals, at the weight todo.md states; else each goal goal_weights weighs.
weights: dict[str, float]
@dataclasses.dataclass(frozen=True)
class Ranked:
text: str
under_bar: list[str]
# What ranking prints and --check does not: an old-shape table's call to reshape, a README that voids code health and marks no goal **Achieve:**, and each dropped blocker ID, since a mistyped ID drops the same way.
notes: list[str]
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
texts = read_all(todo)
if isinstance(texts, Failure):
return texts
ranked = rank(*texts)
if isinstance(ranked, Failure):
return ranked
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
return unwritten
for line in ranked.notes + ranked.under_bar:
print(f"{todo}: {line}", file=sys.stderr)
return ranked
def check_failures(todo: pathlib.Path) -> list[str]:
"""Why --check fails on todo, empty when it passes."""
texts = read_all(todo)
if isinstance(texts, Failure):
return [texts.reason]
ranked = rank(*texts)
if isinstance(ranked, Failure):
return [ranked.reason]
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md, each empty when there is none."""
texts = []
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
try:
texts.append(path.read_text(encoding="utf-8"))
except FileNotFoundError:
if missing:
return Failure(f"{path}: not found; {missing}")
texts.append("")
except OSError as failure:
return Failure(f"{path}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{path}: not UTF-8")
return texts[0], texts[1], texts[2], texts[3]
def write(path: pathlib.Path, text: str) -> Failure | None:
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
def rank(text: str, readme: str, decisions: str, history: str) -> Ranked | Failure:
lines = text.split("\n")
table = read_table(lines)
if isinstance(table, Failure):
return table
shape = shape_of(table.columns)
scoring = read_scoring(text, lines, readme, decisions, history, shape)
if isinstance(scoring, Failure):
return scoring
items = read_items(table, scoring)
if isinstance(items, Failure):
return items
if uncited := check_citations(items, decisions):
return uncited
if isinstance(marked := renames(text), Failure):
return marked
if live := next((item for item in items if item.release in marked), None):
return Failure(f"todo.md marks release {version(live.release)} renamed but files item {live.id} under it; drop the mark or move the item")
scored = ordered(items, scoring)
if isinstance(scored, Failure):
return scored
ranked = rank_details(rewrite_table(lines, table, shape, scored), [item for item, _ in scored])
if isinstance(ranked, Failure):
return ranked
under_bar = [under_the_bar(item, value, scoring.bar, items) for item, value in scored if not item.exempt and round(value, 1) < scoring.bar]
return Ranked(ranked, under_bar, notes(items, scoring))
# The columns ranking fills itself, so a table without one gains it.
WRITTEN = (BLOCKED_BY, "R", "Score")
def rewrite_table(lines: list[str], table: Table, shape: Shape, scored: list[tuple[Item, float]]) -> str:
"""lines with the table's rows in scored's order, under a header naming, in shape's order, each column the table holds and each of WRITTEN."""
columns = tuple(column for column in shape.columns if column in table.columns or column in WRITTEN)
header = ["| " + " | ".join(columns) + " |", "|" + "---|" * len(columns)]
rows = [render_item(item, value, shape, columns) for item, value in scored]
return "\n".join(lines[:table.header] + header + rows + lines[table.start + len(table.rows):])
def notes(items: list[Item], scoring: Scoring) -> list[str]:
held = {item.id for item in items}
dropped = [f"item {item.id}: dropped {', '.join(map(str, gone))} from its {BLOCKED_BY}; the table no longer holds {'it' if len(gone) == 1 else 'them'}" for item in items if (gone := sorted(set(item.blocked_by) - held))]
if scoring.shape is OLD_SHAPE:
return [RESHAPE] + dropped
# Printed so the under-bar lines it causes do not read as items of low value.
unweighed = [] if any(scoring.weights.values()) else ["README.md voids code health and marks no goal **Achieve:**, so every item scores V 0"]
return unweighed + dropped
def blocked_through(id_: int, items: list[Item]) -> set[int]:
"""The IDs of the items id_ blocks, and of those they block in turn."""
found: set[int] = set()
reached = {id_}
while reached:
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
found |= reached
return found
def ordered(items: list[Item], scoring: Scoring) -> list[tuple[Item, float]] | Failure:
"""Each item with its score, by release, then questions and security findings first, then by score from highest, then by ID; then each blocker above every item it blocks."""
by_score = []
for item in items:
value = score(scoring.formula, item, scoring)
if isinstance(value, Failure):
return value
by_score.append((item, value))
by_score.sort(key=lambda pair: (pair[0].release, FIRST.get(pair[0].exempt, len(FIRST)), -pair[1], pair[0].id))
return blockers_first(by_score)
def under_the_bar(item: Item, value: float, bar: float, items: list[Item]) -> str:
blocks = [str(id_) for id_ in sorted(blocked_through(item.id, items))]
blocked = f" and the items it blocks, directly or through another ({', '.join(blocks)})" if blocks else ""
return f"item {item.id} scores {value:.1f}, under the bar {bar:g}; delete it{blocked}, or mark it with a reason the bar does not apply"
def read_scoring(text: str, lines: list[str], readme: str, decisions: str, history: str, shape: Shape) -> Scoring | Failure:
goals = ranked_goals(readme, decisions)
if isinstance(goals, Failure):
return goals
formula = parse_formula(stated(text, "Score"), variables(shape))
if isinstance(formula, Failure):
return formula
bar = number(stated(text, "Bar"), "the bar")
if isinstance(bar, Failure):
return bar
next_id = stated(text, "Next ID")
if isinstance(next_id, Failure) or not re.fullmatch(r"[0-9]+", next_id):
return next_id if isinstance(next_id, Failure) else Failure(f"Next ID {next_id!r} is not a whole number")
weights = weigh(lines, history, goals, shape)
if isinstance(weights, Failure):
return weights
return Scoring(shape, formula, bar, int(next_id), dict(goals), weights)
def ranked_goals(readme: str, decisions: str) -> list[tuple[str, Mark]] | Failure:
"""Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. A **Void:** line other than `**Void:** code health, since <reason>.` fails, and so does a docs/decisions.md that opts out of the comprehension check where README.md keeps code health, since the goal then has no signal."""
goals = readme_goals(readme)
if isinstance(goals, Failure):
return goals
voids = VOID.findall("".join(sections(readme).get("Goals", [])))
if other := [void for void in voids if not void.startswith(f"{CODE_HEALTH}, since ")]:
if other[0].lower().startswith(CODE_HEALTH):
return Failure(f"README.md's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
return Failure(f"README.md's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
if voids:
return goals
if OPTED_OUT.search(decisions):
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
return [(CODE_HEALTH, "Achieve"), *goals]
def weigh(lines: list[str], history: str, goals: list[tuple[str, Mark]], shape: Shape) -> dict[str, float] | Failure:
"""Each goal's weight. In OLD_SHAPE, README.md's goals weigh what todo.md states, and code health has no weight, so no item may name it. Otherwise goal_weights gives each its weight, at the overall latest_overall reads where the goals hold code health."""
if shape is OLD_SHAPE:
return parse_weights(lines, [number for number, _ in goals if number != CODE_HEALTH])
if WEIGHTS_HEADER in lines:
return Failure(f"todo.md holds a goal weights table beside a {MOVES} column; drop the table, since rank_todo.py weighs the goals itself, as its --help says")
overall = latest_overall(history) if CODE_HEALTH in dict(goals) else None
if isinstance(overall, Failure):
return overall
return goal_weights(goals, overall)
def read_table(lines: list[str]) -> Table | Failure:
"""The items table, held to its shape's columns and alone under ## Items."""
if "## Items" not in lines:
return Failure("todo.md is not in the scored-table format; rank_todo.py --help shows a valid one")
table = items_table(lines)
if table is None:
return Failure(f"## Items holds no table whose header opens {HEADER_START}; rank_todo.py --help shows a valid one")
if isinstance(table, Failure):
return table
shape = shape_of(table.columns)
if missing := [column for column in shape.risk_columns if column not in table.columns]:
old = older_columns(table, shape)
dropped = f", and drop {listed(old, 'and')}" if old else ""
columns = f"{listed(missing, 'and')} column; add it" if len(missing) == 1 else f"{listed(missing, 'and')} columns; add them"
return Failure(f"todo.md's items table has no {columns}, scoring each item's {listed(shape.risk_columns, 'and')} as rank_todo.py --help shows{dropped}")
return unknown_columns(table, shape) or outside_items(lines, table) or table
def unknown_columns(table: Table, shape: Shape) -> Failure | None:
"""Why ranking, which writes only the columns of the table's shape, would drop one of the table's columns; None when it would drop none."""
unknown = [column for column in table.columns if column not in shape.columns]
if old := older_columns(table, shape):
kind = "a column of an older shape; drop it" if len(old) == 1 else "columns of an older shape; drop them"
return Failure(f"todo.md's items table has {listed(old, 'and')}, {kind}, as rank_todo.py --help shows")
if unknown:
return Failure(f"todo.md's items table has the column {', '.join(unknown)}, which this rank_todo.py does not know; the columns it knows are {', '.join(shape.columns)}. Rename it, or move this machine to the release that added it")
return None
def older_columns(table: Table, shape: Shape) -> list[str]:
"""The table's columns that only OLD_SHAPE knows, where the table is in SHAPE."""
return [column for column in table.columns if column not in SHAPE.columns and column in OLD_SHAPE.columns] if shape is SHAPE else []
def read_items(table: Table, scoring: Scoring) -> list[Item] | Failure:
items = []
for row in table.rows:
item = parse_item(row, scoring, table)
if isinstance(item, Failure):
return item
items.append(item)
ids = {item.id for item in items}
if len(ids) < len(items):
return Failure("two items share an ID")
if ids and max(ids) >= scoring.next_id:
return Failure(f"item {max(ids)} is not under Next ID {scoring.next_id}; raise Next ID past every ID")
for item in items:
if unheld := [blocker for blocker in item.blocked_by if blocker >= scoring.next_id]:
return Failure(f"item {item.id} is blocked by item {unheld[0]}, which is not under Next ID {scoring.next_id}; name an item the table holds or held")
return items
def outside_items(lines: list[str], table: Table) -> Failure | None:
"""Why the table does not stand alone under ## Items: the table's order is todo.md's only order."""
heading = max((index for index in range(table.header) if lines[index].startswith("## ")), default=None)
if heading is None:
return Failure("the items table sits under no ## heading; move it under ## Items")
if lines[heading] != "## Items":
return Failure(f"the items table sits under {lines[heading]}, not ## Items; move it under ## Items")
after = lines[table.start + len(table.rows):]
section = after[:next((index for index, line in enumerate(after) if line.startswith("## ")), len(after))]
if any(line.strip() for line in lines[heading + 1:table.header] + section):
return Failure(f"## Items holds text beside its table; an order goes in the scores or the {BLOCKED_BY} column, and a note in the item's detail")
return None
def blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
held = {item.id: (item, value) for item, value in scored}
position = {item.id: index for index, (item, _) in enumerate(scored)}
for item, _ in scored:
for blocker in item.blocked_by:
if blocker in held and held[blocker][0].release > item.release:
later, earlier = version(held[blocker][0].release), version(item.release)
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
if loop := blocking_loop(held):
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
placed: set[int] = set()
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
try:
graphlib.TopologicalSorter(graph).prepare()
except graphlib.CycleError as cycle:
return sorted(set(cycle.args[1]))
return None
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int]) -> list[tuple[Item, float]]:
"""The item id_, unless placed holds it, preceded by those of its blockers placed doesn't hold yet, each in score order, and theirs before them. Each item it returns joins placed. blocking_loop has ruled out a loop."""
if id_ in placed:
return []
placed.add(id_)
item, value = held[id_]
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
def check_citations(items: list[Item], decisions: str) -> Failure | None:
"""Holds todo.md and docs/decisions.md to each other: a cited item is exempt, a decision row is cited."""
cited = set(cited_items(decisions))
if gone := sorted(cited - {item.id for item in items}):
return Failure(f"docs/decisions.md cites \"`todo.md` item {gone[0]}\", which todo.md no longer holds; revise that decision to say what holds now")
for item in sorted(items, key=lambda item: item.id):
if item.id in cited and not item.exempt:
return Failure(f"docs/decisions.md cites \"`todo.md` item {item.id}\"; mark it decision, or another reason the bar does not apply")
if item.exempt == "decision" and item.id not in cited:
return Failure(f"item {item.id} is marked decision, but docs/decisions.md does not cite \"`todo.md` item {item.id}\"; cite it there, or mark it with another reason the bar does not apply")
return None
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
found = sections(readme).get("Goals", [])
if len(found) != 1:
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
goals: list[tuple[str, Mark]] = []
path: list[tuple[int, str]] = []
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
while path and path[-1][0] >= len(indent):
path.pop()
path.append((len(indent), position))
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
numbers = [number for number, _ in goals]
if not goals:
return Failure("README.md's ## Goals has no numbered goal")
if len(set(numbers)) < len(numbers):
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
return goals
def goal_weights(goals: list[tuple[str, Mark]], overall: decimal.Decimal | None) -> dict[str, float] | Failure:
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Each maintain goal weighs as the heaviest achieve goal, since a broken one outranks any achieve goal; only a defect that restores it may name it. Every weight is 0 where goals holds no achieve goal, as where README.md voids code health and marks no goal **Achieve:**, so every item scores V 0 and only an exempt one passes the bar."""
if unmarked := [number for number, mark in goals if mark is None]:
return Failure(f"README.md's goal {unmarked[0]} is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score")
achieve = [number for number, mark in goals if mark == "Achieve"]
total = sum(GOAL_STEP**rank for rank in range(len(achieve)))
weights = {number: GOAL_STEP**rank / total for rank, number in enumerate(achieve)}
if CODE_HEALTH in weights and (overall is None or overall < FLOOR):
weights[CODE_HEALTH] *= UNDER_FLOOR
heaviest = max(weights.values(), default=0.0)
return weights | {number: heaviest for number, mark in goals if mark == "Maintain"}
def cited_items(decisions: str) -> list[int]:
return [int(id_) for cited in re.findall(r"`todo\.md` items? (\d+(?:(?:, | and )\d+)*)", decisions) for id_ in re.findall(r"\d+", cited)]
def stated(text: str, name: str) -> str | Failure:
found = re.findall(rf"^`{name} = ([^`]+)`$", text, re.M)
if len(found) != 1:
return Failure(f"todo.md states `{name} = ...` {len(found)} times; state it once, on a line of its own under ## Scoring")
return found[0]
def parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
if isinstance(source, Failure):
return source
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
if len(source) > LONGEST_FORMULA:
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
try:
tree = ast.parse(source, mode="eval")
except (SyntaxError, ValueError):
return Failure(f"the formula {source!r} does not parse")
nodes = list(ast.walk(tree))
if len(nodes) > LARGEST_FORMULA:
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
for node in nodes:
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
return tree
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
match node:
case ast.Expression(body):
return evaluate(body, values)
case ast.Constant(value) if isinstance(value, (int, float)):
return float(value)
case ast.Name(name):
return values[name]
case ast.UnaryOp(ast.USub(), operand):
return -evaluate(operand, values)
case ast.UnaryOp(ast.UAdd(), operand):
return evaluate(operand, values)
case ast.BinOp(left, ast.Add(), right):
return evaluate(left, values) + evaluate(right, values)
case ast.BinOp(left, ast.Sub(), right):
return evaluate(left, values) - evaluate(right, values)
case ast.BinOp(left, ast.Mult(), right):
return evaluate(left, values) * evaluate(right, values)
case ast.BinOp(left, ast.Div(), right):
divisor = evaluate(right, values)
return evaluate(left, values) / divisor if divisor else math.nan
case ast.BinOp(left, ast.Pow(), right):
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
base, exponent = evaluate(left, values), evaluate(right, values)
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
if math.isnan(base) or math.isnan(exponent):
return math.nan
try:
return math.pow(base, exponent)
except (OverflowError, ValueError):
return math.nan
return math.nan
def goal_term(shape: Shape) -> str:
"""The name of the formula's goal term, which score builds: W in OLD_SHAPE, V in the current shape."""
return "W" if shape is OLD_SHAPE else "V"
def variables(shape: Shape) -> tuple[str, ...]:
"""The names the formula may use: the shape's scores but C, which stays out of the formula, and its goal term."""
return tuple(sorted({*shape.score_columns} - {"C"} | {goal_term(shape)}))
def score(formula: ast.Expression, item: Item, scoring: Scoring) -> float | Failure:
if goal_term(scoring.shape) == "W":
# The old shape weighs an item by its heaviest cited goal.
term = max(scoring.weights[goal] for goal, _ in item.moves)
else:
# Only an OLD_SHAPE item names a goal without a move.
term = sum(scoring.weights[goal] * (by or 0) for goal, by in item.moves)
value = evaluate(formula, {**item.scores, goal_term(scoring.shape): term})
return value if math.isfinite(value) else Failure(f"the formula gives item {item.id} no finite score")
def number(text: str | Failure, what: str) -> float | Failure:
if isinstance(text, Failure):
return text
try:
value = float(text)
except ValueError:
value = math.nan
return value if math.isfinite(value) else Failure(f"{what} {text!r} is not a finite number")
def parse_weights(lines: list[str], goals: list[str]) -> dict[str, float] | Failure:
table = table_rows(lines, WEIGHTS_HEADER)
if isinstance(table, Failure):
return table
weights: dict[str, float] = {}
for row in table.rows:
found = cells(row, 2)
if isinstance(found, Failure):
return found
weight = number(found[1], f"goal {found[0]}'s weight")
if isinstance(weight, Failure):
return weight
if found[0] in weights:
return Failure(f"the goal weights list goal {found[0]} twice")
weights[found[0]] = weight
if list(weights) != goals:
default = "\n".join(f"| {goal} | {(len(goals) - index) / len(goals):.2f} |" for index, goal in enumerate(goals))
return Failure(f"the goal weights list {', '.join(weights) or 'no goal'}, but README.md's goals are {', '.join(goals)}; by position they weigh:\n{WEIGHTS_HEADER}\n|---|---|\n{default}")
return weights
def parse_item(row: str, scoring: Scoring, table: Table) -> Item | Failure:
"""The row as an item, refused where it names a goal it may not; in SHAPE, with the R its L, E and I give."""
item = parse_row(row, table)
if isinstance(item, Failure):
return item
if broken := cited_goals_failure(item, scoring):
return broken
if scoring.shape is OLD_SHAPE:
return item
# R is written here, as the Score is, so --check finds a stale one, and a reader keeps the R the table stored.
return dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
"""Why the item may not name one of the goals it names, such as one README.md voids or does not number; None when it may name each. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
if scoring.shape is OLD_SHAPE:
unknown = [goal for goal, _ in item.moves if goal not in scoring.weights]
return Failure(f"item {item.id} cites goal {', '.join(unknown)}, which the goal weights do not list") if unknown else None
for goal, _ in item.moves:
if goal == CODE_HEALTH and goal not in scoring.goals:
return Failure(f"item {item.id} names {CODE_HEALTH}, which README.md voids; drop it from the item's {MOVES}, or the void from README.md")
if goal not in scoring.goals:
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
if scoring.goals[goal] == "Maintain" and item.exempt != "defect":
return Failure(f"item {item.id} cites goal {goal}, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves")
return None
def render_item(item: Item, value: float, shape: Shape, columns: tuple[str, ...]) -> str:
"""The item's row, each cell under its column."""
written = {"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), "Score": f"{value:.1f}"}
return "| " + " | ".join(written[column] for column in columns) + " |"
def rank_details(text: str, items: list[Item]) -> str | Failure:
section = DETAILS.search(text)
details = item_details(text)
if section is None or isinstance(details, Failure):
return details if isinstance(details, Failure) else text
if unknown := sorted(set(details) - {item.id for item in items}):
return Failure(f"## Details holds item {', '.join(map(str, unknown))}, which the items table does not")
headed = [f"### {item.id}. {item.tagline.strip('*').replace(chr(92) + '|', '|')}\n\n{details[item.id]}\n" for item in items if item.id in details]
ranked = "\n" + "\n".join(headed) if headed else "\n"
tail = "\n" if section.end() < len(text) else ""
return text[:section.start(1)] + ranked + tail + text[section.end():]