124 lines
6.2 KiB
Python
Executable File
124 lines
6.2 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Score 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.
|
|
|
|
usage: rank_todo.py [--check] [todo.md]
|
|
|
|
Reads todo.md (default: ./todo.md), the README.md beside it, and docs/decisions.md and
|
|
docs/comprehension-history.md where they exist. 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 writes nothing and fails when the file is not ranked as it would be.
|
|
|
|
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.
|
|
README.md 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`. README.md'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 7.0, or the history
|
|
holds no scoring run, code health weighs 4 times its weight by position, and the other goals keep
|
|
theirs. A line `**Void:** code health, since <reason>.` in README.md'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. Only an item marked defect may name a
|
|
maintain goal, the one it restores, which weighs as the heaviest achieve goal.
|
|
- 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 the table and nothing else: 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 README 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 file that cannot be read or written, a todo.md, README.md 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.
|
|
"""
|
|
import pathlib
|
|
import sys
|
|
|
|
from failure import Failure
|
|
from release_plan import ranking
|
|
|
|
|
|
def main(argv: list[str]) -> int:
|
|
if argv[:1] in (["-h"], ["--help"]):
|
|
print(__doc__.strip())
|
|
return 0
|
|
args = parse_args(argv)
|
|
if isinstance(args, Failure):
|
|
return fail(args)
|
|
check, todo = args
|
|
if check:
|
|
failures = ranking.check_failures(todo)
|
|
for line in failures:
|
|
print(line, file=sys.stderr)
|
|
return 1 if failures else 0
|
|
ranked = ranking.rank_file(todo)
|
|
if isinstance(ranked, Failure):
|
|
return fail(ranked)
|
|
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] | 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 "todo.md")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main(sys.argv[1:]))
|