545 lines
29 KiB
Python
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():]
|
|
|