148 lines
8.0 KiB
Python
Executable File
148 lines
8.0 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Score todo.md's items by the formula it states, weighing code health first and then the goals file's achieve goals by their position, and hold them to its bar.
|
|
|
|
usage: rank_todo.py [--check] [todo.md]
|
|
|
|
Run inside a checkout. Reads four files at the paths the project's config names, which
|
|
`project-config` prints: todo.md, its plan; the goals file; and docs/decisions.md and
|
|
docs/comprehension-history.md where they exist. A file given must be that plan.
|
|
Rewrites each item's Score from the formula and sorts the items by release; within a release,
|
|
question rows come first, then security rows, then the rest, each group by score from highest,
|
|
then by ID. Then it moves each blocker, an item another's Blocked by cell names, that ranks below
|
|
an item it blocks to just above the first such item. Orders the details to match. Writes each
|
|
item's R, and adds the Blocked by and R columns to a table without them. --check doesn't write
|
|
anything and fails when the file is not ranked as it would be, or when an item's detail holds a
|
|
`Touches:` list not spelt as `touch-predictions --help` shows.
|
|
|
|
A valid todo.md; ## Details and each item's detail are optional:
|
|
|
|
# todo
|
|
|
|
## Scoring
|
|
|
|
`Score = 100 * V / (2**S + 8)`
|
|
|
|
`Bar = 1`
|
|
|
|
`Next ID = 2`
|
|
|
|
## Items
|
|
|
|
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
|
|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
| 1 | 0.1.0 | | | **Make the first thing work.** | 2 | 2 | 1 | 3 | 3 | 1 by 9 | 0 |
|
|
|
|
## Details
|
|
|
|
### 1. Make the first thing work.
|
|
|
|
What the tagline cannot say.
|
|
|
|
- The formula holds numbers, + - * / ** and parentheses over L, E, I, R, S and V.
|
|
- V sums, over the goals in an item's Moves cell, each goal's weight times how far the item moves it.
|
|
The goals file marks each goal **Maintain:** or **Achieve:**. Code health, the achieve goal
|
|
every project shares, ranks first; a Moves cell names it as in `code health by 6`. The goals
|
|
file's achieve goals follow in reading order, a sub-goal such as 1.1 included. Each weighs 0.97 times the one
|
|
before, and the weights sum to 1. With 5 achieve goals the first weighs 0.212 and the last 0.188.
|
|
With 15 they weigh 0.082 and 0.053. The overall is the mean of the overall means of every scoring
|
|
run on docs/comprehension-history.md's newest scored commit. While it is under the project's
|
|
readability floor, or the history holds no scoring run, code health weighs 4 times its weight by
|
|
position, and the other goals keep theirs. The config sets the floor as `readability-floor`, 7.0
|
|
where left out. A line `**Void:** code health, since <reason>.` in the goals file's ## Goals drops code
|
|
health, and an item may not name it. A project must void it where its docs/decisions.md has a
|
|
`## review opt-out:` title naming the comprehension check. An item that adds a test,
|
|
a gate leg or a probe that fails where a maintain goal breaks may name that goal, by how much
|
|
more confident the project becomes that the goal holds, 1 to 10. Each point is worth 0.5. An
|
|
item marked defect names a maintain goal for how much of it is broken, and each point is worth
|
|
the heaviest achieve goal's weight, or 0.5 where that is lighter. The tool does not check that
|
|
an item adds a test, a gate leg or a probe; reviewers do.
|
|
- The bar is judged on the Score as shown, to one decimal.
|
|
- A new item takes Next ID, and Next ID then goes up by one; every ID stays below it.
|
|
- An item's L, E and I are levels that ~/.claude/rules/todo-items.md defines: L from 1 to 4, E from 1
|
|
to 3 and I from 1 to 5.
|
|
rank_todo.py writes its R, L + E + I - 2, at least 7 when I is 5 and at least 5 when I is 4. Its S
|
|
is a whole number from 1 to 10.
|
|
- An item's Moves cell is empty, or names each goal it moves and how far, a whole number from 1 to
|
|
10, such as `1.1 by 8, 1.2 by 5`: the most specific goal, and a parent only for a move none of its
|
|
sub-goals covers, so never a goal beside its own sub-goal. An empty cell scores V 0.
|
|
- An item's Exempt cell is empty, or names why the bar does not apply: decision, defect, owner,
|
|
principle, question or security. An item docs/decisions.md cites as "`todo.md` item N" must be
|
|
exempt, and a row marked decision must be cited there.
|
|
- An item's Item cell is one bold tagline; its detail, if any, sits under its ID in ## Details.
|
|
- An item's Blocked by cell is empty, or lists IDs such as `12, 14`: each must be done before the
|
|
item starts, so no blocker may sit in a later release, and no item may block itself or form a
|
|
loop. An ID at or above Next ID fails; one below it that the table no longer holds was finished
|
|
or deleted, and is dropped.
|
|
- ## Items holds only the table: an order goes in the scores or the Blocked by column.
|
|
- The table holds the columns above. One missing L, E or I fails, and so does one with a column this
|
|
version does not know, since writing it would drop that column.
|
|
- A table in the old shape, with C, A, G and Goals columns in place of L, E, I and Moves, still
|
|
ranks, by a formula over R, S, A, G and W and a | Goal | W | table that weighs every goal, W
|
|
being the heaviest cited goal's weight; ranking it says to reshape it.
|
|
- ## Renamed is optional: one line `- 0.2.1 renamed to 0.3.0` per renamed release. chunk-preflight,
|
|
loop-claude and larv-review skip the line's first release, and ignore the second, which is for the
|
|
reader. No item may sit under a marked release, and a line goes once a tag at or past its first
|
|
release is cut. A release whose items all moved elsewhere without a line reads as finished.
|
|
|
|
Exit 1, saying why, on bad arguments, a checkout no config names or a config that cannot be read, a
|
|
file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file or docs/decisions.md that breaks the
|
|
rules above, a scoring run on docs/comprehension-history.md's newest scored commit with no Mean row
|
|
ending in its overall, an item that is not exempt scoring under the bar, or --check finding the file
|
|
unranked, or an item's `Touches:` list unreadable.
|
|
"""
|
|
import pathlib
|
|
import sys
|
|
|
|
from failure import Failure
|
|
from plan_store.stores import file_plan
|
|
from project_config.main import located
|
|
|
|
|
|
def main(argv: list[str], home: pathlib.Path) -> int:
|
|
if argv[:1] in (["-h"], ["--help"]):
|
|
print(__doc__.strip())
|
|
return 0
|
|
args = parse_args(argv)
|
|
if isinstance(args, Failure):
|
|
return fail(args)
|
|
config = located(None, home)
|
|
if isinstance(config, Failure):
|
|
return fail(config)
|
|
if config.plan_file is None and args == (True, None):
|
|
# Jira's backlog ranks a plan kept there, so the check passes, as silently as on a ranked todo.md: chunk-preflight runs it on every project.
|
|
return 0
|
|
if config.plan_file is None:
|
|
return fail(Failure(f"rank_todo.py ranks a todo.md, and this checkout's config keeps the plan in Jira, whose backlog ranks it: {config.plan_label}"))
|
|
check, todo = args[0], args[1] or config.plan_file
|
|
# The goals, decisions and history are this checkout's project's, so another project's plan would be ranked by them.
|
|
if todo.resolve() != config.plan_file.resolve():
|
|
return fail(Failure(f"rank_todo.py: {todo} is not the plan this checkout's config names, {config.plan_file.resolve()}; run rank_todo.py in the checkout of the project whose plan it is"))
|
|
plan = file_plan(config, todo)
|
|
if check:
|
|
failures = plan.check()
|
|
for line in failures:
|
|
print(line, file=sys.stderr)
|
|
return 1 if failures else 0
|
|
ranked = plan.rank()
|
|
if isinstance(ranked, Failure):
|
|
return fail(ranked)
|
|
for line in plan.reported(ranked):
|
|
print(line, file=sys.stderr)
|
|
return 1 if ranked.under_bar else 0
|
|
|
|
|
|
def fail(failure: Failure) -> int:
|
|
print(failure.reason, file=sys.stderr)
|
|
return 1
|
|
|
|
|
|
def parse_args(argv: list[str]) -> tuple[bool, pathlib.Path | None] | Failure:
|
|
paths = [arg for arg in argv if arg != "--check"]
|
|
if len(paths) > 1 or any(path.startswith("-") for path in paths):
|
|
return Failure(f"rank_todo.py: cannot read the arguments {' '.join(argv)}; usage: rank_todo.py [--check] [todo.md]")
|
|
return "--check" in argv, pathlib.Path(paths[0]) if paths else None
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main(sys.argv[1:], pathlib.Path.home()))
|