150 lines
7.2 KiB
Python
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())
|