Files
claude-config/bin/score_outcomes/main.py
T

150 lines
7.2 KiB
Python

"""Show what finished chunks measured beside the scores their items were guessed at, to score a new item by.
usage: score-outcomes [L E I S]
Run it inside a project checkout or one of its worktrees. It fetches origin, when the checkout has
that remote, and reads origin's default branch, or else the local main or master; a failed fetch
reads origin as last fetched and says so on stderr.
Git history is the record. A chunk is a merge commit on the default branch's first-parent line
whose change removed items from todo.md, and changed more than todo.md and the records below; it
shipped those items. Each item's guess is the scores it held in the todo.md of the merge's first
parent: L, E, I, R and S. An item scored before L, E and I replaced C holds R and S, and C too where
its table also had A, G and Goals. The chunk measures:
- lines changed: lines added plus lines deleted against the first parent, leaving out todo.md and
the records tools append to, docs/comprehension-history.md and docs/reading-cost.md;
- files: the files those lines are in;
- review rounds past each pass's first: among the branch's `Answer <pass> round <n>:` commit
titles, each pass's rounds as `larv-review round-count` counts them, less one, summed;
- 🔴 and 🟡 findings: summed over those titles, each opening `<k> 🔴, <m> 🟡` after the colon,
such as `Answer stability round 1: 1 🔴, 2 🟡; flag a deleted test`. Unknown where a round title
lacks the counts, or the branch has no round.
A project that merges without merge commits, by fast-forward or squash, has no chunk to measure.
Given L, E and I, on the levels ~/.claude/rules/todo-items.md defines, and S, it works out R from
L, E and I, as rank_todo.py does, and lists the 5 finished items whose guesses sit closest, closest
first: the least mean squared difference over the scores both hold, so R and S alone for an item
scored before L, E and I, the newest first among equals. Each line gives what the item's chunk
measured, which items shipped with it, and its tagline.
Then the project's anchors, the shipped items its docs/score-anchors.md names for each level of L,
E and I, read from the checkout's working tree, each line as above, or that no merge shipped it. A
file that cannot be read, a row that does not hold a level on its scale and a list of IDs, or a
level named twice leaves the anchors out, saying why.
Then the median of the outcome R and S each predict at each value they were guessed at: R against
🔴 findings, S against lines changed. And how well L, E and I each order chunks by review rounds
past each pass's first and by 🔴 findings: Spearman's rank correlation, from -1 to +1, where +1
orders them exactly; none where every chunk held the same level, or the same outcome. It counts only chunks that shipped one
item, since a chunk measures all its items at once, and reports a score only once 10 such chunks
hold it and its outcomes.
Exit 1, saying why, on bad arguments, when git cannot start, finds no checkout or reads a shallow
clone, or the default branch cannot be read; or, after the rest of the report, when the anchors are
left out.
"""
import pathlib
import re
import sys
from score_outcomes.anchors import anchor_lines, Anchors, ANCHORS_PATH, parse_anchors
from git_repo import default_branch, file_at, full_history, git, top
from failure import Failure
from todo_table import LEVELS, risk, TOP_SCORE
from markdown_text import listed
from score_outcomes.outcomes import nearest, Outcome, outcomes_of, render, report, shipped
from utc_stamp import utc
# The scores score-outcomes takes, in order.
GIVEN = ("L", "E", "I", "S")
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if argv and (len(argv) != len(GIVEN) or not all(re.fullmatch(r"[1-9][0-9]?", arg) and int(arg) <= LEVELS.get(name, TOP_SCORE) for name, arg in zip(GIVEN, argv))):
scales = listed([f"{name} from 1 to {LEVELS.get(name, TOP_SCORE)}" for name in GIVEN], "and")
print(f"score-outcomes: cannot read the arguments {' '.join(argv)}; usage: score-outcomes [L E I S], {scales}", file=sys.stderr)
return 1
found = default_branch(stale_ok=True)
if isinstance(found, Failure):
return failed(found)
default, note = found
if note:
print(f"score-outcomes: {note}", file=sys.stderr)
outcomes = read_outcomes(default)
if isinstance(outcomes, Failure):
return failed(outcomes)
anchored = read_anchors()
print(report_text(outcomes, anchored, dict(zip(GIVEN, map(int, argv))) if argv else None))
return failed(anchored) if isinstance(anchored, Failure) else 0
def report_text(outcomes: list[Outcome], anchored: Anchors | Failure, given: dict[str, int] | None) -> str:
"""The report: the finished items nearest the given scores, where any are given, then the anchors, then the medians."""
sections = []
if given is not None:
r = risk(given["L"], given["E"], given["I"])
near = [render(outcome) for outcome in nearest(outcomes, given | {"R": r})] or ["- None: no merge commit on the default branch shipped an item from todo.md. A project that merges by squash or fast-forward has none."]
sections.append([f"Finished items nearest L {given['L']}, E {given['E']}, I {given['I']}, so R {r}, and S {given['S']}, closest first:", "", *near])
sections.append([f"Anchors in {ANCHORS_PATH}, each level's shipped items:", "", *anchor_lines(anchored, outcomes)])
sections.append(["Median outcome at each guessed score, among chunks that shipped one item:", "", *report(outcomes)])
return "\n\n".join("\n".join(section) for section in sections)
def failed(failure: Failure) -> int:
print(f"score-outcomes: {failure.reason}", file=sys.stderr)
return 1
def read_anchors() -> Anchors | Failure:
"""The checkout's anchors as its working tree holds them, so a branch that edits them shows its edit; none where it has no such file."""
root = top()
if isinstance(root, Failure):
return root
try:
return parse_anchors((pathlib.Path(root) / ANCHORS_PATH).read_text())
except FileNotFoundError:
return []
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"cannot read {ANCHORS_PATH}: {failure}")
def read_outcomes(default: str) -> list[Outcome] | Failure:
if partial := full_history():
return partial
merges = git("log", "--first-parent", "--merges", "--format=%H %h %ct", default, "--", "todo.md")
if isinstance(merges, Failure):
return merges
outcomes: list[Outcome] = []
for line in merges.splitlines():
merge, short, time = line.split()
measured = measure(merge, short, utc(int(time)))
if isinstance(measured, Failure):
return measured
outcomes += measured
return outcomes
def measure(merge: str, short: str, merged: str) -> list[Outcome] | Failure:
"""What one merge measured for each item it shipped."""
before = file_at(f"{merge}^1", "todo.md")
if isinstance(before, Failure):
return before
after = file_at(merge, "todo.md")
if isinstance(after, Failure):
return after
items = shipped(before, after)
if not items:
return []
numstat = git("diff", "--numstat", f"{merge}^1", merge)
if isinstance(numstat, Failure):
return numstat
titles = git("log", "--format=%s", f"{merge}^1..{merge}^2")
if isinstance(titles, Failure):
return titles
return outcomes_of(items, short, merged, numstat, titles.splitlines())