350 lines
19 KiB
Python
350 lines
19 KiB
Python
"""Rank todo.md's items by the formula it states, with the goal weights goals_file.py gives, and hold them to its bar; rank_todo.py --help states the rules.
|
|
"""
|
|
import ast
|
|
import dataclasses
|
|
import decimal
|
|
import math
|
|
import re
|
|
import typing
|
|
|
|
from plan.todo_table import BLOCKED_BY, cells, CODE_HEALTH, detail_heading, DETAILS, Exempt, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, row_cells, Shape, SHAPE, shape_of, Table, table_rows, tagline_text
|
|
from plan.blockers import blocked_through, blockers_first
|
|
from plan.citations import check_citations
|
|
from plan.formula import evaluate, parse_formula
|
|
from failure import Failure
|
|
from plan.goals_file import goal_weights, Mark, ranked_goals
|
|
from review_rules.comprehension_history import latest_overall
|
|
from text_files.markdown_text import listed
|
|
from plan.release import version
|
|
|
|
# What a point of an item's move on a maintain goal is worth. A defect that restores the goal weighs it at least this much per point. docs/decisions.md records the choice and its data.
|
|
MAINTAIN_WEIGHT = 0.5
|
|
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: dict[Exempt, int] = {"question": 0, "security": 1}
|
|
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 the goals file'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 the goals file voids it, then the goals file'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 the goals file's goals, at the weight todo.md states; else each achieve goal, as goal_weights weighs it. A maintain goal is weighed per item, by weight_of.
|
|
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 goals file 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(text: str, goals_text: str, decisions: str, history: str, floor: decimal.Decimal) -> Ranked | Failure:
|
|
"""floor is the project's readability floor, which its config sets."""
|
|
lines = text.split("\n")
|
|
table = read_table(lines)
|
|
if isinstance(table, Failure):
|
|
return table
|
|
shape = shape_of(table.columns)
|
|
scoring = read_scoring(text, lines, goals_text, decisions, history, shape, floor)
|
|
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 falls_under(item, value, 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 ["the goals file voids code health and marks no goal **Achieve:**, so an item scores V 0 unless it names a maintain goal"]
|
|
return unweighed + dropped
|
|
|
|
|
|
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], goals_text: str, decisions: str, history: str, shape: Shape, floor: decimal.Decimal) -> Scoring | Failure:
|
|
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")
|
|
return scoring_of(stated(text, "Score"), number(stated(text, "Bar"), "the bar"), goals_text, decisions, history, floor, shape=shape, lines=lines, next_id=int(next_id))
|
|
|
|
|
|
def config_scoring(formula: str, bar: float, goals_text: str, decisions: str, history: str, floor: decimal.Decimal) -> Scoring | Failure:
|
|
"""The scoring of a plan in Jira, whose formula and bar the project's config states. Jira numbers the issues, so no Next ID applies."""
|
|
return scoring_of(formula, bar, goals_text, decisions, history, floor, shape=SHAPE, lines=[], next_id=0)
|
|
|
|
|
|
def scoring_of(formula_text: str | Failure, bar: float | Failure, goals_text: str, decisions: str, history: str, floor: decimal.Decimal, *, shape: Shape, lines: list[str], next_id: int) -> Scoring | Failure:
|
|
goals = ranked_goals(goals_text, decisions)
|
|
if isinstance(goals, Failure):
|
|
return goals
|
|
formula = parse_formula(formula_text, variables(shape))
|
|
if isinstance(formula, Failure):
|
|
return formula
|
|
if isinstance(bar, Failure):
|
|
return bar
|
|
weights = weigh(lines, history, goals, shape, floor)
|
|
if isinstance(weights, Failure):
|
|
return weights
|
|
return Scoring(shape, formula, bar, next_id, dict(goals), weights)
|
|
|
|
|
|
def weigh(lines: list[str], history: str, goals: list[tuple[str, Mark]], shape: Shape, floor: decimal.Decimal) -> dict[str, float] | Failure:
|
|
"""Each goal's weight. In OLD_SHAPE, the goals file'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, floor)
|
|
|
|
|
|
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 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 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(weight_of(goal, item, scoring) * (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 weight_of(goal: str, item: Item, scoring: Scoring) -> float:
|
|
"""What a point of the item's move on the goal is worth. An achieve goal weighs what goal_weights says. A maintain goal weighs MAINTAIN_WEIGHT, except under an item marked defect, which names it for how much of it is broken: that weighs as the heaviest achieve goal, or MAINTAIN_WEIGHT where that is lighter, since a broken goal outranks every achieve goal and every confidence gain. The code checks only the mark; reviewers check that a non-defect item adds a test, gate leg or probe."""
|
|
if scoring.goals[goal] != "Maintain":
|
|
return scoring.weights[goal]
|
|
return max([MAINTAIN_WEIGHT, *scoring.weights.values()]) if item.exempt == "defect" else MAINTAIN_WEIGHT
|
|
|
|
|
|
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 the goals file'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 with_risk(item)
|
|
|
|
|
|
def with_risk(item: Item) -> Item:
|
|
return dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
|
|
|
|
|
|
def falls_under(item: Item, value: float, bar: float) -> bool:
|
|
"""Whether the item, which scores value, may not be planned: it scores under the bar, rounded as todo.md shows a Score, and isn't exempt."""
|
|
return not item.exempt and round(value, 1) < bar
|
|
|
|
|
|
def item_score(item: Item, scoring: Scoring, name: str) -> float | Failure:
|
|
"""The score of an item that holds no R, such as an issue in Jira; refused where it names a goal it may not. name is what a message calls the item."""
|
|
if broken := cited_goals_failure(item, scoring, name):
|
|
return broken
|
|
value = score(scoring.formula, with_risk(item), scoring)
|
|
return Failure(f"the formula gives {name} no finite score") if isinstance(value, Failure) else value
|
|
|
|
|
|
def cited_goals_failure(item: Item, scoring: Scoring, name: str = "") -> Failure | None:
|
|
"""Why the item may not name one of the goals it names, such as one the goals file voids or does not number; None when it may name each. name is what a message calls the item, `item <ID>` where empty. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
|
|
name = name or f"item {item.id}"
|
|
if scoring.shape is OLD_SHAPE:
|
|
unknown = [goal for goal, _ in item.moves if goal not in scoring.weights]
|
|
return Failure(f"{name} 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"{name} names {CODE_HEALTH}, which the goals file voids; drop it from the item's {MOVES}, or the void from the goals file")
|
|
if goal not in scoring.goals:
|
|
return Failure(f"{name} cites goal {goal}, which the goals file's ## Goals does not number")
|
|
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 = row_cells(item, shape) | {"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"{detail_heading(item.id, tagline_text(item.tagline))}\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():]
|
|
|