Group bin's root modules into packages named by purpose, and make rank_todo.py a launcher of release_plan/ranking.py
This commit is contained in:
+10
-15
@@ -25,15 +25,14 @@
|
||||
!bin/chunk_preflight/*.py
|
||||
!bin/claude_code/
|
||||
!bin/claude_code/*.py
|
||||
!bin/comprehension_history.py
|
||||
!bin/command_lines/
|
||||
!bin/command_lines/*.py
|
||||
!bin/deploy-release
|
||||
!bin/deploy_release/
|
||||
!bin/deploy_release/*.py
|
||||
!bin/docker_command.py
|
||||
!bin/failure.py
|
||||
!bin/file_writes.py
|
||||
!bin/git_command.py
|
||||
!bin/git_repo.py
|
||||
!bin/git_cli/
|
||||
!bin/git_cli/*.py
|
||||
!bin/judge-replay
|
||||
!bin/judge_replay/
|
||||
!bin/judge_replay/*.py
|
||||
@@ -49,27 +48,26 @@
|
||||
!bin/loop_inbox/*.py
|
||||
!bin/machine_load/
|
||||
!bin/machine_load/*.py
|
||||
!bin/markdown_text.py
|
||||
!bin/metric-bench
|
||||
!bin/metric_bench/
|
||||
!bin/metric_bench/*.py
|
||||
!bin/model_routing/
|
||||
!bin/model_routing/*.py
|
||||
!bin/project_key.py
|
||||
!bin/rank_todo.py
|
||||
!bin/reading-cost
|
||||
!bin/reading_cost/
|
||||
!bin/reading_cost/*.py
|
||||
!bin/release.py
|
||||
!bin/release_standing.py
|
||||
!bin/records/
|
||||
!bin/records/*.py
|
||||
!bin/release_plan/
|
||||
!bin/release_plan/*.py
|
||||
!bin/repo_checks/
|
||||
!bin/repo_checks/*.py
|
||||
!bin/review-replay
|
||||
!bin/review_folder.py
|
||||
!bin/review_passes.py
|
||||
!bin/review_replay/
|
||||
!bin/review_replay/*.py
|
||||
!bin/round_titles.py
|
||||
!bin/review_rules/
|
||||
!bin/review_rules/*.py
|
||||
!bin/routing_figures/
|
||||
!bin/routing_figures/*.py
|
||||
!bin/rule-hook
|
||||
@@ -86,16 +84,13 @@
|
||||
!bin/score_outcomes/
|
||||
!bin/score_outcomes/*.py
|
||||
!bin/settings_filter.py
|
||||
!bin/shell_command.py
|
||||
!bin/statusline.py
|
||||
!bin/subagent-rung
|
||||
!bin/subagent_rung/
|
||||
!bin/subagent_rung/*.py
|
||||
!bin/test_*.py
|
||||
!bin/todo_table.py
|
||||
!bin/transcript_archive/
|
||||
!bin/transcript_archive/*.py
|
||||
!bin/utc_stamp.py
|
||||
!docs/
|
||||
!docs/*.md
|
||||
!principles/
|
||||
|
||||
@@ -125,22 +125,28 @@ pytest_add_cli_args=-k
|
||||
|
||||
Then, in the copy: `uvx --with pytest==9.2.0 'mutmut>=3,<4' run && uvx --with pytest==9.2.0 'mutmut>=3,<4' results`, and `uvx --with pytest==9.2.0 'mutmut>=3,<4' show <mutant>` to see a mutant's change. The config keys are mutmut 3's.
|
||||
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. The non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool.
|
||||
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. `bin/`'s root holds only the launchers, the stand-alone tools with their tests, `test_env.py` and `failure.py`. `failure.py` stays there because its `Failure`, the value every module returns for a failed step, fits no one package's purpose. `claude_code/`, `command_lines/`, `git_cli/`, `records/`, `release_plan/`, `review_rules/` and `transcript_archive/` serve more than one tool.
|
||||
|
||||
- `branch_chunks/` cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, for `score_outcomes` and `routing_figures`. It imports `reading_cost`'s record path.
|
||||
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_standing.py`, which says whether the next release is ready to cut.
|
||||
- `command_lines/` reads a shell command: its simple commands, and what a docker call in it asks, for `rule_hook`, `run_heavy`, `reading_cost` and `routing_figures`.
|
||||
- `deploy_release` imports `chunk_preflight`'s `forge_of`, which tells a GitHub origin from a Gitea one, and `release_plan`'s `release_standing`, which says whether the next release is ready to cut.
|
||||
- `git_cli/` runs git, through `git_repo.py`'s `git`, which every tool starts git with, and reads a git call in a shell command (`git_command.py`).
|
||||
- `judge_replay` imports `loop_claude`'s judge.
|
||||
- `larv_review` imports `rank_todo.py`'s ranking.
|
||||
- `larv_review` imports `release_plan`'s ranking.
|
||||
- `loop_claude` runs `chunk-preflight` as a process of its own.
|
||||
- `loop_inbox` imports `loop_claude`'s question files (`waiting/`), the files a running loop lists itself in (`running_loops.py`, `session_lock.py`), its effects and paths, and `hand_over.py`, which opens claude for `/talk`. A change to any of them changes loop-inbox too.
|
||||
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for.
|
||||
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read.
|
||||
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
|
||||
- `rank_todo.py` launches `release_plan/ranking.py`; `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
|
||||
- `records/` reads the sections of the Markdown records the tools keep, stamps their entries in UTC, and writes the tools' files privately and whole.
|
||||
- `release_plan/` reads `todo.md`'s items table, parses releases, says how the plan stands to the last release cut, and ranks the plan (`ranking.py`).
|
||||
- `repo_checks/` tests the repo itself.
|
||||
- `review_rules/` holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.
|
||||
- `routing_figures/` measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.
|
||||
- `rule_hook` imports `rank_todo.py`'s check.
|
||||
- `rule_hook` imports `release_plan`'s ranking check.
|
||||
- `rung_replay/` holds what `judge_replay` and `review_replay` share: the rung search, the argument reader, the candidate rungs and the exits. It reads `loop_claude`'s retry count and models file.
|
||||
- `test_env.py` serves the tests.
|
||||
- `transcript_archive/` stores loop-claude's transcripts; its `project_key.py` names a project's archive folder, its loop-claude session and its entry in the models file.
|
||||
|
||||
## Tracking a new file
|
||||
|
||||
|
||||
@@ -3,10 +3,10 @@ import re
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from comprehension_history import HISTORY
|
||||
from todo_table import Item, items
|
||||
from review_rules.comprehension_history import HISTORY
|
||||
from release_plan.todo_table import Item, items
|
||||
from reading_cost.figures import RECORD
|
||||
from utc_stamp import utc
|
||||
from records.utc_stamp import utc
|
||||
|
||||
# The plan, and the records tools append to: none of their lines are the chunk's work.
|
||||
NOT_WORK = ("todo.md", HISTORY, RECORD)
|
||||
|
||||
@@ -5,8 +5,8 @@ import re
|
||||
import typing
|
||||
|
||||
from branch_chunks.cut import Branch, BranchChunk, NOT_WORK
|
||||
from todo_table import Item
|
||||
from round_titles import title_counts
|
||||
from release_plan.todo_table import Item
|
||||
from review_rules.round_titles import title_counts
|
||||
|
||||
# The Exempt cells, per ~/.claude/rules/todo-items.md, that mark an item fixing a defect.
|
||||
FIXES = ("defect", "security")
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
from branch_chunks.fixes import blamed, fixing_changes, FixingChange, removed_work, Traced, with_fixes
|
||||
from branch_chunks.cut import BranchChunk, cut_branch, LOG, plan_revisions, shipped_by
|
||||
from failure import Failure
|
||||
from git_repo import Run, text_at
|
||||
from git_cli.git_repo import Run, text_at
|
||||
|
||||
|
||||
def branch_chunks(default: str, run: Run) -> list[BranchChunk] | Failure:
|
||||
|
||||
@@ -13,9 +13,9 @@ from branch_chunks.fixes import blamed, fixing_changes, removed, removed_work, T
|
||||
from branch_chunks.cut import Branch, chunk_log, Commit, cut_branch, landing, NOT_WORK, shipped, Span
|
||||
from branch_chunks.read import branch_chunks, traced_to
|
||||
from failure import Failure
|
||||
from git_repo import git
|
||||
from git_cli.git_repo import git
|
||||
from test_env import isolated_env
|
||||
from todo_table import Item
|
||||
from release_plan.todo_table import Item
|
||||
|
||||
HEADER = "| ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
WITHOUT_C = "| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
import pathlib
|
||||
import re
|
||||
|
||||
from release_standing import chunk_item, Cut, dated_cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
|
||||
from release_plan.release_standing import chunk_item, Cut, dated_cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, NoItem, Plan
|
||||
from todo_table import item_details, items, NoItemsTable
|
||||
from release import version
|
||||
from release_plan.todo_table import item_details, items, NoItemsTable
|
||||
from release_plan.release import version
|
||||
|
||||
# The command each forge's CLI lists pull requests with; pulls_command adds the flags that pick their rows and fields.
|
||||
PULLS_LIST: dict[Forge, tuple[str, ...]] = {"gh": ("gh", "pr", "list"), "tea": ("tea", "pulls", "list")}
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
"""The lines the preflight prints, stated from what it gathered."""
|
||||
from todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
|
||||
from release_plan.todo_table import bundle_candidates, BUNDLE_MAX_R, Item, ships_alone
|
||||
from chunk_preflight.choices import cut_name, PULLS_LIST
|
||||
from release_standing import dated_cut, LastCut, unreleased_entries
|
||||
from release_plan.release_standing import dated_cut, LastCut, unreleased_entries
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran
|
||||
from markdown_text import quoted
|
||||
from release import version
|
||||
from records.markdown_text import quoted
|
||||
from release_plan.release import version
|
||||
|
||||
|
||||
def render(found: Gathered) -> list[str]:
|
||||
|
||||
@@ -4,8 +4,8 @@ import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from todo_table import Item
|
||||
from release_standing import LastCut
|
||||
from release_plan.todo_table import Item
|
||||
from release_plan.release_standing import LastCut
|
||||
|
||||
# The CLI that lists a forge's pull requests: gh for a github.com origin, tea for any other.
|
||||
Forge = typing.Literal["gh", "tea"]
|
||||
|
||||
@@ -57,8 +57,8 @@ import subprocess
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from git_repo import commit_exists, default_branch, file_at, git, top
|
||||
from release_standing import default_plan
|
||||
from git_cli.git_repo import commit_exists, default_branch, file_at, git, top
|
||||
from release_plan.release_standing import default_plan
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran, Worktree
|
||||
from chunk_preflight.choices import forge_of, named_paths, planned, pulls_command, worktree_add, worktree_on
|
||||
|
||||
@@ -12,7 +12,7 @@ from failure import Failure
|
||||
from chunk_preflight.choices import forge_of, named_paths, planned, worktree_add
|
||||
from chunk_preflight.gathered import Gathered, ItemFacts, NamedPath, NoItem, Ran, Worktree
|
||||
from test_env import isolated_env
|
||||
from release_standing import LastCut
|
||||
from release_plan.release_standing import LastCut
|
||||
from chunk_preflight.main import line_count, ran, seconds, TIMEOUT
|
||||
from chunk_preflight.facts import open_pulls, render
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import unittest
|
||||
|
||||
from docker_command import capped
|
||||
from command_lines.docker_command import capped
|
||||
|
||||
|
||||
class Capped(unittest.TestCase):
|
||||
@@ -8,14 +8,14 @@ import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
|
||||
from release_standing import chunk_item, Cut, default_plan, Next, ReadyToCut, ReviewDue, Unplanned
|
||||
from git_repo import default_ref, git
|
||||
from release_plan.release_standing import chunk_item, Cut, default_plan, Next, ReadyToCut, ReviewDue, Unplanned
|
||||
from git_cli.git_repo import default_ref, git
|
||||
from deploy_release.deploy import deploy
|
||||
from failure import Failure
|
||||
from deploy_release import forge
|
||||
from chunk_preflight.choices import forge_of
|
||||
from todo_table import items
|
||||
from release import newest_tag, Release, version
|
||||
from release_plan.todo_table import items
|
||||
from release_plan.release import newest_tag, Release, version
|
||||
|
||||
|
||||
def cut(clone: str, checkout: str) -> str | Failure:
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
"""Move a checkout to this repo's newest release, as a bare `deploy-release` does."""
|
||||
from failure import Failure
|
||||
from git_repo import git
|
||||
from release import newest_tag, parsed, tagged
|
||||
from markdown_text import sections
|
||||
from git_cli.git_repo import git
|
||||
from release_plan.release import newest_tag, parsed, tagged
|
||||
from records.markdown_text import sections
|
||||
|
||||
|
||||
def deploy(checkout: str) -> str | Failure:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import dataclasses
|
||||
|
||||
from shell_command import resolved, Simple
|
||||
from command_lines.shell_command import resolved, Simple
|
||||
|
||||
# git's global options that take a value as the next word.
|
||||
GIT_VALUED = {"-C", "-c", "--exec-path", "--git-dir", "--namespace", "--work-tree"}
|
||||
@@ -5,12 +5,10 @@ import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
|
||||
|
||||
from git_cli import git_repo
|
||||
class Git(unittest.TestCase):
|
||||
# Each command is a shell alias, so it touches no repository, whatever GIT_DIR the test runs under.
|
||||
|
||||
@@ -30,7 +30,7 @@ from transcript_archive.location import archive_root, transcript_of
|
||||
from transcript_archive.read import archived_outcomes
|
||||
from rung_replay.command import arguments_or_exit, down_from, failed, limited_exit, projects_on
|
||||
from judge_replay.replay import Case, case_from, Kind, report, reproduced, sample, verdict_kind
|
||||
from project_key import checkout_of
|
||||
from transcript_archive.project_key import checkout_of
|
||||
from loop_claude.effects import Effects
|
||||
from failure import Failure
|
||||
from rung_replay.search import first_reply, replayed
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import decimal
|
||||
|
||||
from comprehension_history import by_time, counted_vote, entries, Entry, last_cells
|
||||
from review_rules.comprehension_history import by_time, counted_vote, entries, Entry, last_cells
|
||||
from larv_review.seats import FIRST_SEATS
|
||||
|
||||
# Matches score-outcomes, which waits for 10 finished chunks before it shows a median.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
from failure import Failure
|
||||
from git_repo import file_at, full_history, git, top
|
||||
from comprehension_history import HISTORY, HistoryChange
|
||||
from git_cli.git_repo import file_at, full_history, git, top
|
||||
from review_rules.comprehension_history import HISTORY, HistoryChange
|
||||
|
||||
|
||||
def history_changes(default: str) -> list[HistoryChange] | Failure:
|
||||
|
||||
@@ -2,15 +2,15 @@ import pathlib
|
||||
import time
|
||||
|
||||
from larv_review.agreement import agreement_report
|
||||
from comprehension_history import appended, DIMENSIONS, FLOOR, heading, Heading, HISTORY, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
|
||||
from git_repo import commit_exists, top
|
||||
from review_rules.comprehension_history import appended, DIMENSIONS, FLOOR, heading, Heading, HISTORY, latest_places, recorded, ruling_entry, scoring_entry, ScoringRun, vote_text
|
||||
from git_cli.git_repo import commit_exists, top
|
||||
from larv_review.ruling import counted, overall, ruling, split, surplus, votes
|
||||
from failure import Failure
|
||||
from larv_review.seats import FIRST_SEATS, scores, seats_file, SeatsFile
|
||||
from larv_review.scoring import means, under_floor
|
||||
from larv_review.plan import plan_reasons
|
||||
import rank_todo
|
||||
from file_writes import replace_file
|
||||
from release_plan import ranking
|
||||
from records.file_writes import replace_file
|
||||
|
||||
|
||||
def record_ruling(votes_file: pathlib.Path) -> Failure | None:
|
||||
@@ -61,7 +61,7 @@ def rerank() -> Failure | None:
|
||||
if isinstance(checkout, Failure):
|
||||
return checkout
|
||||
todo = pathlib.Path(checkout, "todo.md")
|
||||
ranked = rank_todo.rank_file(todo)
|
||||
ranked = ranking.rank_file(todo)
|
||||
if isinstance(ranked, Failure):
|
||||
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Fix what that names, then run rank_todo.py on {todo}, not record-scoring again")
|
||||
if ranked.under_bar:
|
||||
|
||||
@@ -103,17 +103,17 @@ import re
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from git_repo import branch_titles, default_branch, git, top
|
||||
from round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
|
||||
from git_cli.git_repo import branch_titles, default_branch, git, top
|
||||
from review_rules.round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
|
||||
from failure import Failure
|
||||
from comprehension_history import FLOOR
|
||||
from review_rules.comprehension_history import FLOOR
|
||||
from larv_review.history_changes import history_changes
|
||||
from larv_review.ruling_base import measured_commit
|
||||
from larv_review.agreement import MIN_PAIRS
|
||||
from review_passes import PASSES
|
||||
from review_rules.review_passes import PASSES
|
||||
from larv_review.plan import plan_reasons
|
||||
from larv_review.history_commands import record_ruling, record_scoring, show_agreement, show_places
|
||||
from review_folder import REPORTS, review_folder
|
||||
from review_rules.review_folder import REPORTS, review_folder
|
||||
|
||||
USAGE = "usage: larv-review review-folder | ruling-base | round-count | needs-scoring-run [<item ID>...] | record-ruling <votes file> | record-scoring <scores file> [<item ID>...] | places | agreement"
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
import pathlib
|
||||
|
||||
from release_standing import Cut, default_plan, LastCut, next_release, Unknown
|
||||
from release_plan.release_standing import Cut, default_plan, LastCut, next_release, Unknown
|
||||
from failure import Failure
|
||||
from todo_table import Item, items, NoItemsTable, renames
|
||||
from release import Release, version
|
||||
from git_repo import top
|
||||
from release_plan.todo_table import Item, items, NoItemsTable, renames
|
||||
from release_plan.release import Release, version
|
||||
from git_cli.git_repo import top
|
||||
|
||||
|
||||
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed_release: Release | None, renamed: set[Release]) -> list[str] | Failure:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
from comprehension_history import DIMENSIONS, PLACE, place_dimensions, Seat
|
||||
from review_rules.comprehension_history import DIMENSIONS, PLACE, place_dimensions, Seat
|
||||
from failure import Failure
|
||||
from larv_review.seats import FIRST_SEATS, SPLIT_SEATS, vote_line
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
from comprehension_history import entries, HistoryChange
|
||||
from review_rules.comprehension_history import entries, HistoryChange
|
||||
|
||||
|
||||
def measured_commit(changes: list[HistoryChange]) -> str | None:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import decimal
|
||||
|
||||
from comprehension_history import DIMENSIONS, FLOOR
|
||||
from review_rules.comprehension_history import DIMENSIONS, FLOOR
|
||||
|
||||
|
||||
def means(lines: list[list[str]]) -> list[decimal.Decimal]:
|
||||
|
||||
@@ -2,7 +2,7 @@ import dataclasses
|
||||
import decimal
|
||||
import re
|
||||
|
||||
from comprehension_history import ARCHITECT, DIMENSIONS, JUNIOR, MID, Seat, SENIOR
|
||||
from review_rules.comprehension_history import ARCHITECT, DIMENSIONS, JUNIOR, MID, Seat, SENIOR
|
||||
from failure import Failure
|
||||
|
||||
SCORES = re.compile(", ".join(rf"{name} ([0-9]+(?:\.[0-9]+)?)" for name in DIMENSIONS))
|
||||
|
||||
@@ -11,14 +11,14 @@ import unittest
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from larv_review.agreement import agreement_report, ruling_agreement, run_agreement
|
||||
from comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
|
||||
import comprehension_history
|
||||
from review_rules.comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
|
||||
from review_rules import comprehension_history
|
||||
from larv_review.ruling import counted, ruling, split, surplus, votes
|
||||
from failure import Failure
|
||||
from test_env import isolated_env
|
||||
from todo_table import Item, items, NoItemsTable
|
||||
from release_plan.todo_table import Item, items, NoItemsTable
|
||||
from larv_review.plan import landed_towards, plan_reasons, scoring_run_due
|
||||
from release_standing import LastCut
|
||||
from release_plan.release_standing import LastCut
|
||||
from larv_review.scoring import means, under_floor
|
||||
from larv_review.ruling_base import measured_commit
|
||||
from larv_review.seats import score_line, scores, seats_file
|
||||
|
||||
@@ -9,7 +9,7 @@ from loop_claude.effects import Effects
|
||||
from loop_claude import escalation_mark
|
||||
from failure import Failure
|
||||
from loop_claude.verdicts import Finished, Interrupt, QuotedAnswer, TakenIn, Unfinished, Verdict
|
||||
from todo_table import LEVELS
|
||||
from release_plan.todo_table import LEVELS
|
||||
from model_routing.route import on_its_scale
|
||||
from claude_code.transcript import plain, verbatim
|
||||
from loop_claude.cycle.retry import retried
|
||||
|
||||
@@ -4,8 +4,8 @@ from model_routing.ladder import climbed, LADDER, position, Rung
|
||||
from model_routing.route import ESCALATION_MARKER, Route
|
||||
from loop_claude.routing import escalation_rungs
|
||||
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
|
||||
from review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
|
||||
from markdown_text import listed, quoted
|
||||
from review_rules.review_passes import INSTRUCTION_FILES, INSTRUCTION_FOLDERS
|
||||
from records.markdown_text import listed, quoted
|
||||
from claude_code.transcript import Typed
|
||||
|
||||
# Where the judge may quote an answer from, named as the human and the worker see them; of README.md the judge sees only the premises.
|
||||
|
||||
@@ -10,7 +10,7 @@ import time
|
||||
import typing
|
||||
import uuid
|
||||
|
||||
import git_repo
|
||||
from git_cli import git_repo
|
||||
from machine_load.memory import Memory, read_memory
|
||||
|
||||
# Seconds between a loop's looks for an answer from loop-inbox while it reads its terminal, and for the end of the claude loop-inbox opened.
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
import pathlib
|
||||
import typing
|
||||
|
||||
from release_standing import default_plan, DefaultPlan
|
||||
from git_repo import default_ref, file_at
|
||||
from release_plan.release_standing import default_plan, DefaultPlan
|
||||
from git_cli.git_repo import default_ref, file_at
|
||||
from loop_claude.effects import Effects, say
|
||||
from failure import Failure
|
||||
from loop_claude.routing import first_route, kept, routed_item
|
||||
from todo_table import Item
|
||||
from release_plan.todo_table import Item
|
||||
from transcript_archive.read import latest_worker
|
||||
from loop_claude.cycle import prompts
|
||||
from model_routing.route import Route, route_from
|
||||
|
||||
@@ -15,7 +15,7 @@ from loop_claude.project.model_choice import get_or_ask_models
|
||||
from loop_claude.loop.usage import HELP
|
||||
from loop_claude.running_loops import Listed, shown_running
|
||||
from loop_claude.paths import Paths
|
||||
from project_key import project_key
|
||||
from transcript_archive.project_key import project_key
|
||||
from model_routing.ladder import project_rung
|
||||
from loop_claude.project.premises import read_premises
|
||||
from loop_claude.project.records import read_records
|
||||
|
||||
@@ -13,7 +13,7 @@ from routing_figures.render import render
|
||||
from model_routing.ladder import Rung
|
||||
from routing_figures import state
|
||||
from loop_claude.stop import Stop
|
||||
from utc_stamp import utc
|
||||
from records.utc_stamp import utc
|
||||
|
||||
|
||||
def check_routing(root: pathlib.Path, checkout: str, session: str, rung: Rung, paths: Paths, questions: pathlib.Path, effects: Effects) -> Stop | None:
|
||||
|
||||
@@ -9,7 +9,7 @@ from loop_claude.effects import Effects, say
|
||||
from failure import Failure
|
||||
from loop_claude.stop import needs_human, needs_terminal, Stop
|
||||
from loop_claude.paths import Paths
|
||||
from file_writes import replace_json
|
||||
from records.file_writes import replace_json
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
from failure import Failure
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
from markdown_text import sections
|
||||
from records.markdown_text import sections
|
||||
|
||||
|
||||
def read_premises(root: str) -> str | Failure:
|
||||
|
||||
@@ -9,12 +9,12 @@ The worker, and the session /talk opens, run on a Route (model_routing/route.py)
|
||||
"""
|
||||
import dataclasses
|
||||
|
||||
from release_standing import chunk_item, LastCut, Next
|
||||
from release_plan.release_standing import chunk_item, LastCut, Next
|
||||
from model_routing.ladder import climbed, highest, LADDER, position, project_rung, review_floor, Rung, stepped_up, worker_rung
|
||||
from loop_claude import escalation_mark
|
||||
from failure import Failure
|
||||
from loop_claude.verdicts import Interrupt, QuotedAnswer, Unfinished
|
||||
from todo_table import Item, items, NoItemsTable
|
||||
from release_plan.todo_table import Item, items, NoItemsTable
|
||||
from model_routing.route import Route
|
||||
|
||||
UNFINISHED_PER_STEP = 2
|
||||
|
||||
@@ -19,8 +19,8 @@ import typing
|
||||
from loop_claude.effects import Effects, say
|
||||
from loop_claude.session_lock import ended, held, running
|
||||
from failure import Failure
|
||||
from todo_table import items
|
||||
from file_writes import replace_json
|
||||
from release_plan.todo_table import items
|
||||
from records.file_writes import replace_json
|
||||
|
||||
# How many times, 0.1 s apart, a loop tries to take its lock: loop-inbox takes it for a moment each time it checks whether the loop has ended.
|
||||
LOCK_TRIES = 10
|
||||
|
||||
@@ -9,7 +9,7 @@ import pathlib
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from file_writes import make_private
|
||||
from records.file_writes import make_private
|
||||
|
||||
|
||||
def lock_file(folder: pathlib.Path, session: str) -> pathlib.Path:
|
||||
|
||||
@@ -914,7 +914,7 @@ class Reload(unittest.TestCase):
|
||||
worker(append=["loop-claude", "\ndef\n"]), judge(),
|
||||
worker(replace=["loop-claude", "\ndef\n", "\n# edited\n"]), judge(),
|
||||
worker(append=["loop_claude/nested/edited.py", "# edited\n"]), judge(),
|
||||
worker(append=["file_writes.py", "# edited\n"]), judge(),
|
||||
worker(append=["records/file_writes.py", "# edited\n"]), judge(),
|
||||
worker(),
|
||||
])
|
||||
self.assertEqual(run.code, 130)
|
||||
|
||||
@@ -25,7 +25,7 @@ from routing_figures.calls import Call
|
||||
from loop_claude.project import checkout, model_choice, records
|
||||
from loop_claude.loop import chunk_start, close
|
||||
from loop_claude.waiting.answers import ClaudeEnded, ClaudeOpening, send, Typed
|
||||
from release_standing import DefaultPlan, LastCut
|
||||
from release_plan.release_standing import DefaultPlan, LastCut
|
||||
from loop_claude.effects import Effects, POLL_SECONDS, PYTHON_TIMEOUT, run_python, say, system_effects
|
||||
from claude_code import entries, reply, session
|
||||
from failure import Failure
|
||||
@@ -42,7 +42,7 @@ from transcript_archive.location import project_archive
|
||||
from model_routing.route import Route, route_from, WorkerLine
|
||||
from loop_claude.stop import Stop
|
||||
from loop_claude.running_loops import Taken
|
||||
from utc_stamp import utc
|
||||
from records.utc_stamp import utc
|
||||
from loop_claude.cycle.judge import verdict_from
|
||||
from loop_claude.waiting.listing import waiting
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ import pathlib
|
||||
|
||||
from loop_claude.waiting.ask import Ask, tagged
|
||||
from failure import Failure
|
||||
from file_writes import replace_json
|
||||
from records.file_writes import replace_json
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
|
||||
@@ -7,7 +7,7 @@ import pathlib
|
||||
import typing
|
||||
|
||||
from loop_claude.hand_over import ClaudeCommand
|
||||
from utc_stamp import seconds, utc
|
||||
from records.utc_stamp import seconds, utc
|
||||
|
||||
if typing.TYPE_CHECKING:
|
||||
from _typeshed import DataclassInstance
|
||||
|
||||
@@ -8,7 +8,7 @@ from loop_claude.waiting.ask import Ask, ask_fields, read_ask
|
||||
from loop_claude.effects import Effects, say
|
||||
from loop_claude.session_lock import ended, running
|
||||
from failure import Failure
|
||||
from file_writes import make_private, replace_json
|
||||
from records.file_writes import make_private, replace_json
|
||||
|
||||
|
||||
def ask_file(folder: pathlib.Path, session: str) -> pathlib.Path:
|
||||
|
||||
@@ -4,7 +4,7 @@ import dataclasses
|
||||
import os
|
||||
import statistics
|
||||
|
||||
from comprehension_history import Place
|
||||
from review_rules.comprehension_history import Place
|
||||
from metric_bench.python_units import Unit
|
||||
|
||||
METRICS: dict[str, Callable[[Unit, dict[str, int]], int]] = {
|
||||
|
||||
@@ -36,9 +36,9 @@ import statistics
|
||||
import sys
|
||||
|
||||
from metric_bench.bench import bench, co_changed, medians, METRICS, RunScores, Score, tracked_places
|
||||
from comprehension_history import entries, Entry
|
||||
from review_rules.comprehension_history import entries, Entry
|
||||
from failure import Failure
|
||||
from git_repo import git
|
||||
from git_cli.git_repo import git
|
||||
from metric_bench.python_units import measured, python_units, Unit
|
||||
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from metric_bench.bench import auc, bench, co_changed, top_k, tracked_places
|
||||
from metric_bench.python_units import cognitive, measured, python_units, Unit
|
||||
from comprehension_history import entries, Place
|
||||
from review_rules.comprehension_history import entries, Place
|
||||
from failure import Failure
|
||||
from test_env import isolated_env
|
||||
from metric_bench.main import scored_runs
|
||||
|
||||
@@ -3,7 +3,7 @@ import dataclasses
|
||||
import re
|
||||
import typing
|
||||
|
||||
from review_passes import ReviewedPass
|
||||
from review_rules.review_passes import ReviewedPass
|
||||
|
||||
# How Rung.__str__ spells a rung that names an effort, and Rung.parse reads it back.
|
||||
WORDING = re.compile(r"(?P<model>\S+) at (?P<effort>\S+) effort")
|
||||
|
||||
@@ -3,7 +3,7 @@ import dataclasses
|
||||
import json
|
||||
import typing
|
||||
|
||||
from todo_table import LEVELS
|
||||
from release_plan.todo_table import LEVELS
|
||||
from model_routing.ladder import REVIEW_STEPS, Rung
|
||||
|
||||
# How a worker opens the prompt of a subagent it escalates a task to, `Escalation trigger 2: …`: docs/decisions.md → `routing: a worker hands a task one rung up`.
|
||||
|
||||
@@ -5,8 +5,8 @@ import unittest
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from model_routing.ladder import highest, LADDER, lowest_worker_rung, planning_rung, project_rung, review_floor, review_rung, Rung, stepped_up, worker_rung, WORKER_STEPS
|
||||
from todo_table import LEVELS
|
||||
from review_passes import REVIEWERS
|
||||
from release_plan.todo_table import LEVELS
|
||||
from review_rules.review_passes import REVIEWERS
|
||||
|
||||
OPUS = Rung("claude-opus-5-5", "medium")
|
||||
|
||||
|
||||
+3
-654
@@ -1,660 +1,9 @@
|
||||
#!/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 ast
|
||||
import dataclasses
|
||||
import decimal
|
||||
import graphlib
|
||||
import math
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from todo_table import BLOCKED_BY, cells, CODE_HEALTH, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
|
||||
from failure import Failure
|
||||
from comprehension_history import FLOOR, HISTORY, latest_overall
|
||||
from markdown_text import listed, sections
|
||||
from file_writes import replace_file
|
||||
from release import version
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
|
||||
GOAL_STEP = 0.97
|
||||
# Code health weighs this many times its weight by position while the comprehension panel's overall is under FLOOR, or unmeasured; lilleman's choice, which docs/decisions.md records.
|
||||
UNDER_FLOOR = 4
|
||||
# Any **Void:** line of README.md's ## Goals; ranked_goals accepts only `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
|
||||
VOID = re.compile(r"^\*\*Void:\*\* (.*)$", re.M)
|
||||
# A docs/decisions.md title opting the project out of the comprehension check, as larv-review's SKILL.md → "Opt-out" spells it.
|
||||
OPTED_OUT = re.compile(r"^## review opt-out:.*\bcomprehension check\b", re.M)
|
||||
LARGEST_FORMULA = 200
|
||||
LONGEST_FORMULA = 4 * LARGEST_FORMULA
|
||||
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
|
||||
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 = {"question": 0, "security": 1}
|
||||
# How README.md marks a goal; None where it marks it neither way.
|
||||
Mark = typing.Literal["Maintain", "Achieve"] | None
|
||||
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 README.md'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"
|
||||
from release_plan import ranking
|
||||
|
||||
|
||||
@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 README.md voids it, then README.md'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 README.md's goals, at the weight todo.md states; else each goal goal_weights weighs.
|
||||
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 README 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 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 = check_failures(todo)
|
||||
for line in failures:
|
||||
print(line, file=sys.stderr)
|
||||
return 1 if failures else 0
|
||||
ranked = rank_file(todo)
|
||||
if isinstance(ranked, Failure):
|
||||
return fail(ranked)
|
||||
return 1 if ranked.under_bar else 0
|
||||
|
||||
|
||||
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
|
||||
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
|
||||
texts = read_all(todo)
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
ranked = rank(*texts)
|
||||
if isinstance(ranked, Failure):
|
||||
return ranked
|
||||
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
|
||||
return unwritten
|
||||
for line in ranked.notes + ranked.under_bar:
|
||||
print(f"{todo}: {line}", file=sys.stderr)
|
||||
return ranked
|
||||
|
||||
|
||||
def check_failures(todo: pathlib.Path) -> list[str]:
|
||||
"""Why --check fails on todo, empty when it passes."""
|
||||
texts = read_all(todo)
|
||||
if isinstance(texts, Failure):
|
||||
return [texts.reason]
|
||||
ranked = rank(*texts)
|
||||
if isinstance(ranked, Failure):
|
||||
return [ranked.reason]
|
||||
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
|
||||
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
|
||||
|
||||
|
||||
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")
|
||||
|
||||
|
||||
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
|
||||
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md, each empty when there is none."""
|
||||
texts = []
|
||||
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
|
||||
try:
|
||||
texts.append(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
if missing:
|
||||
return Failure(f"{path}: not found; {missing}")
|
||||
texts.append("")
|
||||
except OSError as failure:
|
||||
return Failure(f"{path}: {failure.strerror}")
|
||||
except UnicodeDecodeError:
|
||||
return Failure(f"{path}: not UTF-8")
|
||||
return texts[0], texts[1], texts[2], texts[3]
|
||||
|
||||
|
||||
def write(path: pathlib.Path, text: str) -> Failure | None:
|
||||
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
|
||||
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
|
||||
|
||||
|
||||
def rank(text: str, readme: str, decisions: str, history: str) -> Ranked | Failure:
|
||||
lines = text.split("\n")
|
||||
table = read_table(lines)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
shape = shape_of(table.columns)
|
||||
scoring = read_scoring(text, lines, readme, decisions, history, shape)
|
||||
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 not item.exempt and round(value, 1) < 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 ["README.md voids code health and marks no goal **Achieve:**, so every item scores V 0"]
|
||||
return unweighed + dropped
|
||||
|
||||
|
||||
def blocked_through(id_: int, items: list[Item]) -> set[int]:
|
||||
"""The IDs of the items id_ blocks, and of those they block in turn."""
|
||||
found: set[int] = set()
|
||||
reached = {id_}
|
||||
while reached:
|
||||
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
|
||||
found |= reached
|
||||
return found
|
||||
|
||||
|
||||
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], readme: str, decisions: str, history: str, shape: Shape) -> Scoring | Failure:
|
||||
goals = ranked_goals(readme, decisions)
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
formula = parse_formula(stated(text, "Score"), variables(shape))
|
||||
if isinstance(formula, Failure):
|
||||
return formula
|
||||
bar = number(stated(text, "Bar"), "the bar")
|
||||
if isinstance(bar, Failure):
|
||||
return bar
|
||||
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")
|
||||
weights = weigh(lines, history, goals, shape)
|
||||
if isinstance(weights, Failure):
|
||||
return weights
|
||||
return Scoring(shape, formula, bar, int(next_id), dict(goals), weights)
|
||||
|
||||
|
||||
def ranked_goals(readme: str, decisions: str) -> list[tuple[str, Mark]] | Failure:
|
||||
"""Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. A **Void:** line other than `**Void:** code health, since <reason>.` fails, and so does a docs/decisions.md that opts out of the comprehension check where README.md keeps code health, since the goal then has no signal."""
|
||||
goals = readme_goals(readme)
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
voids = VOID.findall("".join(sections(readme).get("Goals", [])))
|
||||
if other := [void for void in voids if not void.startswith(f"{CODE_HEALTH}, since ")]:
|
||||
if other[0].lower().startswith(CODE_HEALTH):
|
||||
return Failure(f"README.md's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
return Failure(f"README.md's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
if voids:
|
||||
return goals
|
||||
if OPTED_OUT.search(decisions):
|
||||
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
|
||||
return [(CODE_HEALTH, "Achieve"), *goals]
|
||||
|
||||
|
||||
def weigh(lines: list[str], history: str, goals: list[tuple[str, Mark]], shape: Shape) -> dict[str, float] | Failure:
|
||||
"""Each goal's weight. In OLD_SHAPE, README.md'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)
|
||||
|
||||
|
||||
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 blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
|
||||
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
|
||||
held = {item.id: (item, value) for item, value in scored}
|
||||
position = {item.id: index for index, (item, _) in enumerate(scored)}
|
||||
for item, _ in scored:
|
||||
for blocker in item.blocked_by:
|
||||
if blocker in held and held[blocker][0].release > item.release:
|
||||
later, earlier = version(held[blocker][0].release), version(item.release)
|
||||
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
|
||||
if loop := blocking_loop(held):
|
||||
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
|
||||
placed: set[int] = set()
|
||||
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
|
||||
|
||||
|
||||
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
|
||||
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
|
||||
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
|
||||
try:
|
||||
graphlib.TopologicalSorter(graph).prepare()
|
||||
except graphlib.CycleError as cycle:
|
||||
return sorted(set(cycle.args[1]))
|
||||
return None
|
||||
|
||||
|
||||
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int]) -> list[tuple[Item, float]]:
|
||||
"""The item id_, unless placed holds it, preceded by those of its blockers placed doesn't hold yet, each in score order, and theirs before them. Each item it returns joins placed. blocking_loop has ruled out a loop."""
|
||||
if id_ in placed:
|
||||
return []
|
||||
placed.add(id_)
|
||||
item, value = held[id_]
|
||||
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
|
||||
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
|
||||
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
|
||||
|
||||
|
||||
def check_citations(items: list[Item], decisions: str) -> Failure | None:
|
||||
"""Holds todo.md and docs/decisions.md to each other: a cited item is exempt, a decision row is cited."""
|
||||
cited = set(cited_items(decisions))
|
||||
if gone := sorted(cited - {item.id for item in items}):
|
||||
return Failure(f"docs/decisions.md cites \"`todo.md` item {gone[0]}\", which todo.md no longer holds; revise that decision to say what holds now")
|
||||
for item in sorted(items, key=lambda item: item.id):
|
||||
if item.id in cited and not item.exempt:
|
||||
return Failure(f"docs/decisions.md cites \"`todo.md` item {item.id}\"; mark it decision, or another reason the bar does not apply")
|
||||
if item.exempt == "decision" and item.id not in cited:
|
||||
return Failure(f"item {item.id} is marked decision, but docs/decisions.md does not cite \"`todo.md` item {item.id}\"; cite it there, or mark it with another reason the bar does not apply")
|
||||
return None
|
||||
|
||||
|
||||
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
|
||||
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
|
||||
found = sections(readme).get("Goals", [])
|
||||
if len(found) != 1:
|
||||
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
|
||||
goals: list[tuple[str, Mark]] = []
|
||||
path: list[tuple[int, str]] = []
|
||||
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
|
||||
while path and path[-1][0] >= len(indent):
|
||||
path.pop()
|
||||
path.append((len(indent), position))
|
||||
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
|
||||
numbers = [number for number, _ in goals]
|
||||
if not goals:
|
||||
return Failure("README.md's ## Goals has no numbered goal")
|
||||
if len(set(numbers)) < len(numbers):
|
||||
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
|
||||
return goals
|
||||
|
||||
|
||||
def goal_weights(goals: list[tuple[str, Mark]], overall: decimal.Decimal | None) -> dict[str, float] | Failure:
|
||||
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Each maintain goal weighs as the heaviest achieve goal, since a broken one outranks any achieve goal; only a defect that restores it may name it. Every weight is 0 where goals holds no achieve goal, as where README.md voids code health and marks no goal **Achieve:**, so every item scores V 0 and only an exempt one passes the bar."""
|
||||
if unmarked := [number for number, mark in goals if mark is None]:
|
||||
return Failure(f"README.md's goal {unmarked[0]} is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score")
|
||||
achieve = [number for number, mark in goals if mark == "Achieve"]
|
||||
total = sum(GOAL_STEP**rank for rank in range(len(achieve)))
|
||||
weights = {number: GOAL_STEP**rank / total for rank, number in enumerate(achieve)}
|
||||
if CODE_HEALTH in weights and (overall is None or overall < FLOOR):
|
||||
weights[CODE_HEALTH] *= UNDER_FLOOR
|
||||
heaviest = max(weights.values(), default=0.0)
|
||||
return weights | {number: heaviest for number, mark in goals if mark == "Maintain"}
|
||||
|
||||
|
||||
def cited_items(decisions: str) -> list[int]:
|
||||
return [int(id_) for cited in re.findall(r"`todo\.md` items? (\d+(?:(?:, | and )\d+)*)", decisions) for id_ in re.findall(r"\d+", cited)]
|
||||
|
||||
|
||||
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 parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
|
||||
if isinstance(source, Failure):
|
||||
return source
|
||||
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
|
||||
if len(source) > LONGEST_FORMULA:
|
||||
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
|
||||
try:
|
||||
tree = ast.parse(source, mode="eval")
|
||||
except (SyntaxError, ValueError):
|
||||
return Failure(f"the formula {source!r} does not parse")
|
||||
nodes = list(ast.walk(tree))
|
||||
if len(nodes) > LARGEST_FORMULA:
|
||||
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
|
||||
for node in nodes:
|
||||
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
|
||||
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
|
||||
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
|
||||
return tree
|
||||
|
||||
|
||||
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
|
||||
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
|
||||
match node:
|
||||
case ast.Expression(body):
|
||||
return evaluate(body, values)
|
||||
case ast.Constant(value) if isinstance(value, (int, float)):
|
||||
return float(value)
|
||||
case ast.Name(name):
|
||||
return values[name]
|
||||
case ast.UnaryOp(ast.USub(), operand):
|
||||
return -evaluate(operand, values)
|
||||
case ast.UnaryOp(ast.UAdd(), operand):
|
||||
return evaluate(operand, values)
|
||||
case ast.BinOp(left, ast.Add(), right):
|
||||
return evaluate(left, values) + evaluate(right, values)
|
||||
case ast.BinOp(left, ast.Sub(), right):
|
||||
return evaluate(left, values) - evaluate(right, values)
|
||||
case ast.BinOp(left, ast.Mult(), right):
|
||||
return evaluate(left, values) * evaluate(right, values)
|
||||
case ast.BinOp(left, ast.Div(), right):
|
||||
divisor = evaluate(right, values)
|
||||
return evaluate(left, values) / divisor if divisor else math.nan
|
||||
case ast.BinOp(left, ast.Pow(), right):
|
||||
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
|
||||
base, exponent = evaluate(left, values), evaluate(right, values)
|
||||
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
|
||||
if math.isnan(base) or math.isnan(exponent):
|
||||
return math.nan
|
||||
try:
|
||||
return math.pow(base, exponent)
|
||||
except (OverflowError, ValueError):
|
||||
return math.nan
|
||||
return math.nan
|
||||
|
||||
|
||||
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(scoring.weights[goal] * (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 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 README.md'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 dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
|
||||
|
||||
|
||||
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
|
||||
"""Why the item may not name one of the goals it names, such as one README.md voids or does not number; None when it may name each. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
|
||||
if scoring.shape is OLD_SHAPE:
|
||||
unknown = [goal for goal, _ in item.moves if goal not in scoring.weights]
|
||||
return Failure(f"item {item.id} 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"item {item.id} names {CODE_HEALTH}, which README.md voids; drop it from the item's {MOVES}, or the void from README.md")
|
||||
if goal not in scoring.goals:
|
||||
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
|
||||
if scoring.goals[goal] == "Maintain" and item.exempt != "defect":
|
||||
return Failure(f"item {item.id} cites goal {goal}, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves")
|
||||
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 = {"ID": str(item.id), "Release": version(item.release), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves), "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"### {item.id}. {item.tagline.strip('*').replace(chr(92) + '|', '|')}\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():]
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
sys.exit(ranking.main(sys.argv[1:]))
|
||||
|
||||
@@ -5,8 +5,8 @@ import statistics
|
||||
from failure import Failure
|
||||
from transcript_archive.read import FinishedChunk
|
||||
from reading_cost.measure import Reading
|
||||
from markdown_text import sections
|
||||
from utc_stamp import STAMPED
|
||||
from records.markdown_text import sections
|
||||
from records.utc_stamp import STAMPED
|
||||
|
||||
FIGURE = re.compile(rf"^Reading cost, chunk (\w+), finished ({STAMPED})$")
|
||||
FIGURE_FILE = re.compile(r"^- `(.+)` (\d+)$")
|
||||
|
||||
@@ -32,10 +32,10 @@ from reading_cost.measure import Checkout, measure, Reading
|
||||
from failure import Failure
|
||||
from reading_cost.figures import figure, merged, readings_of, RECORD, RESET, trend, unheld
|
||||
from transcript_archive.read import finished_chunks, read_threads
|
||||
from git_repo import git
|
||||
from git_cli.git_repo import git
|
||||
from transcript_archive.location import project_archive
|
||||
from file_writes import replace_file
|
||||
from utc_stamp import utc
|
||||
from records.file_writes import replace_file
|
||||
from records.utc_stamp import utc
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Updated:
|
||||
|
||||
@@ -3,9 +3,9 @@ import dataclasses
|
||||
import re
|
||||
|
||||
from claude_code.entries import assistant_parts, parse_entry, tool_call, usage_count
|
||||
from git_command import commits
|
||||
from git_cli.git_command import commits
|
||||
from reading_cost.shell_reads import Reads, shell_reads
|
||||
from shell_command import resolved, simple_commands
|
||||
from command_lines.shell_command import resolved, simple_commands
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ import dataclasses
|
||||
import posixpath
|
||||
import re
|
||||
|
||||
from shell_command import resolved, simple_commands
|
||||
from command_lines.shell_command import resolved, simple_commands
|
||||
|
||||
NOT_A_PATH = re.compile(r"[*?\[\]{}$\\'\",=()<>|;&]|://|^\d+$")
|
||||
# Their first operand is a pattern or a program, unless -e or -f gives it.
|
||||
|
||||
@@ -4,12 +4,10 @@ import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
import file_writes
|
||||
|
||||
|
||||
from records import file_writes
|
||||
class ReplaceFile(unittest.TestCase):
|
||||
def test_removes_what_it_staged_when_the_replace_fails(self):
|
||||
with tempfile.TemporaryDirectory() as root:
|
||||
@@ -2,11 +2,9 @@ import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
import markdown_text
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from records import markdown_text
|
||||
class Sections(unittest.TestCase):
|
||||
def test_keeps_every_headed_section_with_its_bodies(self):
|
||||
text = "# Title\n\nintro\n\n## Goals\n\n1. one\n```sh\n# not a heading\n```\n### Later\n2. two\n#1 priority\n\n## Empty\n\n## Audience\nme\n## Audience\nagain\n# Appendix\nnot audience\n"
|
||||
@@ -0,0 +1,656 @@
|
||||
"""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 ast
|
||||
import dataclasses
|
||||
import decimal
|
||||
import graphlib
|
||||
import math
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
import typing
|
||||
|
||||
from release_plan.todo_table import BLOCKED_BY, cells, CODE_HEALTH, DETAILS, HEADER_START, Item, item_details, items_table, MOVES, OLD_SHAPE, parse_row, renames, risk, Shape, SHAPE, shape_of, Table, table_rows
|
||||
from failure import Failure
|
||||
from review_rules.comprehension_history import FLOOR, HISTORY, latest_overall
|
||||
from records.markdown_text import listed, sections
|
||||
from records.file_writes import replace_file
|
||||
from release_plan.release import version
|
||||
|
||||
# What each achieve goal weighs of the one above it; docs/decisions.md records the choice.
|
||||
GOAL_STEP = 0.97
|
||||
# Code health weighs this many times its weight by position while the comprehension panel's overall is under FLOOR, or unmeasured; lilleman's choice, which docs/decisions.md records.
|
||||
UNDER_FLOOR = 4
|
||||
# Any **Void:** line of README.md's ## Goals; ranked_goals accepts only `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → "Shared goal" spells it.
|
||||
VOID = re.compile(r"^\*\*Void:\*\* (.*)$", re.M)
|
||||
# A docs/decisions.md title opting the project out of the comprehension check, as larv-review's SKILL.md → "Opt-out" spells it.
|
||||
OPTED_OUT = re.compile(r"^## review opt-out:.*\bcomprehension check\b", re.M)
|
||||
LARGEST_FORMULA = 200
|
||||
LONGEST_FORMULA = 4 * LARGEST_FORMULA
|
||||
OPERATORS = (ast.Add, ast.BinOp, ast.Div, ast.Expression, ast.Load, ast.Mult, ast.Pow, ast.Sub, ast.UAdd, ast.UnaryOp, ast.USub)
|
||||
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 = {"question": 0, "security": 1}
|
||||
# How README.md marks a goal; None where it marks it neither way.
|
||||
Mark = typing.Literal["Maintain", "Achieve"] | None
|
||||
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 README.md'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 README.md voids it, then README.md'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 README.md's goals, at the weight todo.md states; else each goal goal_weights weighs.
|
||||
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 README 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 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 = check_failures(todo)
|
||||
for line in failures:
|
||||
print(line, file=sys.stderr)
|
||||
return 1 if failures else 0
|
||||
ranked = rank_file(todo)
|
||||
if isinstance(ranked, Failure):
|
||||
return fail(ranked)
|
||||
return 1 if ranked.under_bar else 0
|
||||
|
||||
|
||||
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
|
||||
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
|
||||
texts = read_all(todo)
|
||||
if isinstance(texts, Failure):
|
||||
return texts
|
||||
ranked = rank(*texts)
|
||||
if isinstance(ranked, Failure):
|
||||
return ranked
|
||||
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
|
||||
return unwritten
|
||||
for line in ranked.notes + ranked.under_bar:
|
||||
print(f"{todo}: {line}", file=sys.stderr)
|
||||
return ranked
|
||||
|
||||
|
||||
def check_failures(todo: pathlib.Path) -> list[str]:
|
||||
"""Why --check fails on todo, empty when it passes."""
|
||||
texts = read_all(todo)
|
||||
if isinstance(texts, Failure):
|
||||
return [texts.reason]
|
||||
ranked = rank(*texts)
|
||||
if isinstance(ranked, Failure):
|
||||
return [ranked.reason]
|
||||
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
|
||||
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
|
||||
|
||||
|
||||
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")
|
||||
|
||||
|
||||
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
|
||||
"""todo.md, the README.md beside it, and its docs/decisions.md and docs/comprehension-history.md, each empty when there is none."""
|
||||
texts = []
|
||||
for path, missing in ((todo, "every project keeps a todo.md beside its README.md, and rank_todo.py --help shows one"), (todo.parent / "README.md", "rank_todo.py weighs goals from the README.md beside todo.md"), (todo.parent / "docs" / "decisions.md", None), (todo.parent / HISTORY, None)):
|
||||
try:
|
||||
texts.append(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
if missing:
|
||||
return Failure(f"{path}: not found; {missing}")
|
||||
texts.append("")
|
||||
except OSError as failure:
|
||||
return Failure(f"{path}: {failure.strerror}")
|
||||
except UnicodeDecodeError:
|
||||
return Failure(f"{path}: not UTF-8")
|
||||
return texts[0], texts[1], texts[2], texts[3]
|
||||
|
||||
|
||||
def write(path: pathlib.Path, text: str) -> Failure | None:
|
||||
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
|
||||
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
|
||||
|
||||
|
||||
def rank(text: str, readme: str, decisions: str, history: str) -> Ranked | Failure:
|
||||
lines = text.split("\n")
|
||||
table = read_table(lines)
|
||||
if isinstance(table, Failure):
|
||||
return table
|
||||
shape = shape_of(table.columns)
|
||||
scoring = read_scoring(text, lines, readme, decisions, history, shape)
|
||||
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 not item.exempt and round(value, 1) < 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 ["README.md voids code health and marks no goal **Achieve:**, so every item scores V 0"]
|
||||
return unweighed + dropped
|
||||
|
||||
|
||||
def blocked_through(id_: int, items: list[Item]) -> set[int]:
|
||||
"""The IDs of the items id_ blocks, and of those they block in turn."""
|
||||
found: set[int] = set()
|
||||
reached = {id_}
|
||||
while reached:
|
||||
reached = {other.id for other in items if reached.intersection(other.blocked_by)} - found
|
||||
found |= reached
|
||||
return found
|
||||
|
||||
|
||||
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], readme: str, decisions: str, history: str, shape: Shape) -> Scoring | Failure:
|
||||
goals = ranked_goals(readme, decisions)
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
formula = parse_formula(stated(text, "Score"), variables(shape))
|
||||
if isinstance(formula, Failure):
|
||||
return formula
|
||||
bar = number(stated(text, "Bar"), "the bar")
|
||||
if isinstance(bar, Failure):
|
||||
return bar
|
||||
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")
|
||||
weights = weigh(lines, history, goals, shape)
|
||||
if isinstance(weights, Failure):
|
||||
return weights
|
||||
return Scoring(shape, formula, bar, int(next_id), dict(goals), weights)
|
||||
|
||||
|
||||
def ranked_goals(readme: str, decisions: str) -> list[tuple[str, Mark]] | Failure:
|
||||
"""Every goal in rank order, each with its mark: code health first, unless README.md voids it, then README.md's goals in reading order. A **Void:** line other than `**Void:** code health, since <reason>.` fails, and so does a docs/decisions.md that opts out of the comprehension check where README.md keeps code health, since the goal then has no signal."""
|
||||
goals = readme_goals(readme)
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
voids = VOID.findall("".join(sections(readme).get("Goals", [])))
|
||||
if other := [void for void in voids if not void.startswith(f"{CODE_HEALTH}, since ")]:
|
||||
if other[0].lower().startswith(CODE_HEALTH):
|
||||
return Failure(f"README.md's ## Goals voids code health as `{other[0]}`; spell the void exactly `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
return Failure(f"README.md's ## Goals voids `{other[0]}`; only code health may be voided, as `**Void:** {CODE_HEALTH}, since <reason>.`")
|
||||
if voids:
|
||||
return goals
|
||||
if OPTED_OUT.search(decisions):
|
||||
return Failure(f"docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** {CODE_HEALTH}, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says")
|
||||
return [(CODE_HEALTH, "Achieve"), *goals]
|
||||
|
||||
|
||||
def weigh(lines: list[str], history: str, goals: list[tuple[str, Mark]], shape: Shape) -> dict[str, float] | Failure:
|
||||
"""Each goal's weight. In OLD_SHAPE, README.md'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)
|
||||
|
||||
|
||||
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 blockers_first(scored: list[tuple[Item, float]]) -> list[tuple[Item, float]] | Failure:
|
||||
"""scored, each blocker that ranks below an item it blocks moved up to just above the first such item; a blocker the table no longer holds was finished or deleted, and is dropped."""
|
||||
held = {item.id: (item, value) for item, value in scored}
|
||||
position = {item.id: index for index, (item, _) in enumerate(scored)}
|
||||
for item, _ in scored:
|
||||
for blocker in item.blocked_by:
|
||||
if blocker in held and held[blocker][0].release > item.release:
|
||||
later, earlier = version(held[blocker][0].release), version(item.release)
|
||||
return Failure(f"item {item.id}, in release {earlier}, is blocked by item {blocker}, in later release {later}; move item {blocker} to release {earlier} or earlier, or item {item.id} to release {later} or later")
|
||||
if loop := blocking_loop(held):
|
||||
return Failure(f"items {', '.join(map(str, loop[:-1]))} and {loop[-1]} block each other in a loop; drop one of the blockers")
|
||||
placed: set[int] = set()
|
||||
return [entry for item, _ in scored for entry in place(item.id, held, position, placed)]
|
||||
|
||||
|
||||
def blocking_loop(held: dict[int, tuple[Item, float]]) -> list[int] | None:
|
||||
"""The IDs of items that block each other in a loop, sorted; None where there is no loop."""
|
||||
graph = {id_: {blocker for blocker in item.blocked_by if blocker in held} for id_, (item, _) in held.items()}
|
||||
try:
|
||||
graphlib.TopologicalSorter(graph).prepare()
|
||||
except graphlib.CycleError as cycle:
|
||||
return sorted(set(cycle.args[1]))
|
||||
return None
|
||||
|
||||
|
||||
def place(id_: int, held: dict[int, tuple[Item, float]], position: dict[int, int], placed: set[int]) -> list[tuple[Item, float]]:
|
||||
"""The item id_, unless placed holds it, preceded by those of its blockers placed doesn't hold yet, each in score order, and theirs before them. Each item it returns joins placed. blocking_loop has ruled out a loop."""
|
||||
if id_ in placed:
|
||||
return []
|
||||
placed.add(id_)
|
||||
item, value = held[id_]
|
||||
blockers = sorted((blocker for blocker in set(item.blocked_by) if blocker in held), key=position.__getitem__)
|
||||
before = [entry for blocker in blockers for entry in place(blocker, held, position, placed)]
|
||||
return [*before, (dataclasses.replace(item, blocked_by=tuple(sorted(blockers))), value)]
|
||||
|
||||
|
||||
def check_citations(items: list[Item], decisions: str) -> Failure | None:
|
||||
"""Holds todo.md and docs/decisions.md to each other: a cited item is exempt, a decision row is cited."""
|
||||
cited = set(cited_items(decisions))
|
||||
if gone := sorted(cited - {item.id for item in items}):
|
||||
return Failure(f"docs/decisions.md cites \"`todo.md` item {gone[0]}\", which todo.md no longer holds; revise that decision to say what holds now")
|
||||
for item in sorted(items, key=lambda item: item.id):
|
||||
if item.id in cited and not item.exempt:
|
||||
return Failure(f"docs/decisions.md cites \"`todo.md` item {item.id}\"; mark it decision, or another reason the bar does not apply")
|
||||
if item.exempt == "decision" and item.id not in cited:
|
||||
return Failure(f"item {item.id} is marked decision, but docs/decisions.md does not cite \"`todo.md` item {item.id}\"; cite it there, or mark it with another reason the bar does not apply")
|
||||
return None
|
||||
|
||||
|
||||
def readme_goals(readme: str) -> list[tuple[str, Mark]] | Failure:
|
||||
"""README.md's goals in reading order: each one's number, a sub-goal as 4.1, and its mark, Maintain, Achieve or None."""
|
||||
found = sections(readme).get("Goals", [])
|
||||
if len(found) != 1:
|
||||
return Failure(f"README.md has ## Goals {len(found)} times; it needs it once")
|
||||
goals: list[tuple[str, Mark]] = []
|
||||
path: list[tuple[int, str]] = []
|
||||
for indent, position, mark in re.findall(r"^([ \t]*)(\d+)\. (?:\*\*(Maintain|Achieve):\*\*)?", found[0].expandtabs(4), re.M):
|
||||
while path and path[-1][0] >= len(indent):
|
||||
path.pop()
|
||||
path.append((len(indent), position))
|
||||
goals.append((".".join(part for _, part in path), typing.cast(Mark, mark or None)))
|
||||
numbers = [number for number, _ in goals]
|
||||
if not goals:
|
||||
return Failure("README.md's ## Goals has no numbered goal")
|
||||
if len(set(numbers)) < len(numbers):
|
||||
return Failure(f"README.md's ## Goals numbers {', '.join(numbers)}; number each goal by its position")
|
||||
return goals
|
||||
|
||||
|
||||
def goal_weights(goals: list[tuple[str, Mark]], overall: decimal.Decimal | None) -> dict[str, float] | Failure:
|
||||
"""Each achieve goal's weight: the one ranked k of n weighs GOAL_STEP ** (k - 1) / (1 + GOAL_STEP + ... + GOAL_STEP ** (n - 1)), so the weights sum to 1. Code health, where goals holds it, then weighs UNDER_FLOOR times that while the overall is under FLOOR or None, and the other goals keep their weights. Each maintain goal weighs as the heaviest achieve goal, since a broken one outranks any achieve goal; only a defect that restores it may name it. Every weight is 0 where goals holds no achieve goal, as where README.md voids code health and marks no goal **Achieve:**, so every item scores V 0 and only an exempt one passes the bar."""
|
||||
if unmarked := [number for number, mark in goals if mark is None]:
|
||||
return Failure(f"README.md's goal {unmarked[0]} is marked neither **Maintain:** nor **Achieve:**; mark it, as ~/.claude/rules/goals-and-audience.md says, so rank_todo.py knows which goals score")
|
||||
achieve = [number for number, mark in goals if mark == "Achieve"]
|
||||
total = sum(GOAL_STEP**rank for rank in range(len(achieve)))
|
||||
weights = {number: GOAL_STEP**rank / total for rank, number in enumerate(achieve)}
|
||||
if CODE_HEALTH in weights and (overall is None or overall < FLOOR):
|
||||
weights[CODE_HEALTH] *= UNDER_FLOOR
|
||||
heaviest = max(weights.values(), default=0.0)
|
||||
return weights | {number: heaviest for number, mark in goals if mark == "Maintain"}
|
||||
|
||||
|
||||
def cited_items(decisions: str) -> list[int]:
|
||||
return [int(id_) for cited in re.findall(r"`todo\.md` items? (\d+(?:(?:, | and )\d+)*)", decisions) for id_ in re.findall(r"\d+", cited)]
|
||||
|
||||
|
||||
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 parse_formula(source: str | Failure, variables: tuple[str, ...]) -> ast.Expression | Failure:
|
||||
if isinstance(source, Failure):
|
||||
return source
|
||||
# Deep nesting makes the parser itself run out of memory before LARGEST_FORMULA can count the parts.
|
||||
if len(source) > LONGEST_FORMULA:
|
||||
return Failure(f"the formula {source[:40]!r}... holds more than {LONGEST_FORMULA} characters")
|
||||
try:
|
||||
tree = ast.parse(source, mode="eval")
|
||||
except (SyntaxError, ValueError):
|
||||
return Failure(f"the formula {source!r} does not parse")
|
||||
nodes = list(ast.walk(tree))
|
||||
if len(nodes) > LARGEST_FORMULA:
|
||||
return Failure(f"the formula {source!r} holds more than {LARGEST_FORMULA} parts")
|
||||
for node in nodes:
|
||||
numeric = isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool) and abs(node.value) < 1e300
|
||||
if not (isinstance(node, OPERATORS) or numeric or (isinstance(node, ast.Name) and node.id in variables)):
|
||||
return Failure(f"the formula {source!r} may hold only numbers, {', '.join(variables)}, + - * / ** and parentheses")
|
||||
return tree
|
||||
|
||||
|
||||
def evaluate(node: ast.AST, values: dict[str, float]) -> float:
|
||||
"""Evaluates a tree parse_formula accepted; a division by zero, and a power that overflows or has no real value, give nan."""
|
||||
match node:
|
||||
case ast.Expression(body):
|
||||
return evaluate(body, values)
|
||||
case ast.Constant(value) if isinstance(value, (int, float)):
|
||||
return float(value)
|
||||
case ast.Name(name):
|
||||
return values[name]
|
||||
case ast.UnaryOp(ast.USub(), operand):
|
||||
return -evaluate(operand, values)
|
||||
case ast.UnaryOp(ast.UAdd(), operand):
|
||||
return evaluate(operand, values)
|
||||
case ast.BinOp(left, ast.Add(), right):
|
||||
return evaluate(left, values) + evaluate(right, values)
|
||||
case ast.BinOp(left, ast.Sub(), right):
|
||||
return evaluate(left, values) - evaluate(right, values)
|
||||
case ast.BinOp(left, ast.Mult(), right):
|
||||
return evaluate(left, values) * evaluate(right, values)
|
||||
case ast.BinOp(left, ast.Div(), right):
|
||||
divisor = evaluate(right, values)
|
||||
return evaluate(left, values) / divisor if divisor else math.nan
|
||||
case ast.BinOp(left, ast.Pow(), right):
|
||||
# math.pow raises on a negative base with a fractional exponent, zero to a negative power, and overflow; one catch covers all three.
|
||||
base, exponent = evaluate(left, values), evaluate(right, values)
|
||||
# A nan from a zero divisor stays nan, though math.pow(1, nan) and math.pow(nan, 0) give 1.
|
||||
if math.isnan(base) or math.isnan(exponent):
|
||||
return math.nan
|
||||
try:
|
||||
return math.pow(base, exponent)
|
||||
except (OverflowError, ValueError):
|
||||
return math.nan
|
||||
return math.nan
|
||||
|
||||
|
||||
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(scoring.weights[goal] * (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 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 README.md'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 dataclasses.replace(item, scores=item.scores | {"R": risk(item.scores["L"], item.scores["E"], item.scores["I"])})
|
||||
|
||||
|
||||
def cited_goals_failure(item: Item, scoring: Scoring) -> Failure | None:
|
||||
"""Why the item may not name one of the goals it names, such as one README.md voids or does not number; None when it may name each. todo_table's parse_moves holds the rules a Moves cell keeps on its own."""
|
||||
if scoring.shape is OLD_SHAPE:
|
||||
unknown = [goal for goal, _ in item.moves if goal not in scoring.weights]
|
||||
return Failure(f"item {item.id} 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"item {item.id} names {CODE_HEALTH}, which README.md voids; drop it from the item's {MOVES}, or the void from README.md")
|
||||
if goal not in scoring.goals:
|
||||
return Failure(f"item {item.id} cites goal {goal}, which README.md's ## Goals does not number")
|
||||
if scoring.goals[goal] == "Maintain" and item.exempt != "defect":
|
||||
return Failure(f"item {item.id} cites goal {goal}, a maintain goal, which only a defect that restores it may name; name the achieve goals the item moves")
|
||||
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 = {"ID": str(item.id), "Release": version(item.release), BLOCKED_BY: ", ".join(map(str, item.blocked_by)), "Exempt": item.exempt, "Item": item.tagline, **{name: str(score) for name, score in item.scores.items()}, shape.goals_column: shape.write_goals(item.moves), "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"### {item.id}. {item.tagline.strip('*').replace(chr(92) + '|', '|')}\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():]
|
||||
|
||||
@@ -2,8 +2,7 @@
|
||||
import re
|
||||
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
|
||||
from git_cli import git_repo
|
||||
Release = tuple[int, int, int]
|
||||
VERSION = r"[0-9]+\.[0-9]+\.[0-9]+"
|
||||
# The digits of a dated heading's year, month and day, which DATED and dated_heading_pattern each render.
|
||||
@@ -1,11 +1,11 @@
|
||||
"""How the plan stands to the last release cut: the next release, whether work has landed towards it, and whether it is to be planned, reviewed or cut; and, from that standing, the item the next chunk takes first, with what the default branch holds for the pick."""
|
||||
import dataclasses
|
||||
|
||||
from git_repo import commits_since, file_at, git
|
||||
from release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
|
||||
from git_cli.git_repo import commits_since, file_at, git
|
||||
from release_plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
|
||||
from failure import Failure
|
||||
from todo_table import Item, items, next_item, renames
|
||||
from markdown_text import sections
|
||||
from release_plan.todo_table import Item, items, next_item, renames
|
||||
from records.markdown_text import sections
|
||||
|
||||
# The version a branch with no v* tag and no dated CHANGELOG.md heading counts as cut: below every release, 0.0.0 included, so that every release todo.md names comes after it.
|
||||
BEFORE_FIRST_RELEASE = (-1, 0, 0)
|
||||
@@ -6,13 +6,12 @@ import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
import rank_todo
|
||||
from release_plan import ranking
|
||||
from repo_checks import ROOT
|
||||
import todo_table
|
||||
|
||||
from release_plan import todo_table
|
||||
# Voids code health, so these tests weigh only the project's own goals; class CodeHealth weighs it.
|
||||
VOID = "**Void:** code health, since a test project has no code to read.\n\n"
|
||||
|
||||
@@ -99,7 +98,7 @@ Kept as written.
|
||||
|
||||
class Rank(unittest.TestCase):
|
||||
def ranked(self, todo=TODO, readme=README, decisions=DECISIONS):
|
||||
return rank_todo.rank(todo, readme, decisions, "")
|
||||
return ranking.rank(todo, readme, decisions, "")
|
||||
|
||||
def test_scores_and_sorts_by_release_then_security_then_score_and_orders_the_details_to_match(self):
|
||||
ranked = self.ranked()
|
||||
@@ -120,17 +119,17 @@ class Rank(unittest.TestCase):
|
||||
|
||||
def test_weighs_each_achieve_goal_97_percent_of_the_one_above_and_a_defects_maintain_goal_as_the_first(self):
|
||||
readme = "## Goals\n\n1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
|
||||
self.assertEqual({goal: round(weight, 4) for goal, weight in rank_todo.goal_weights(rank_todo.readme_goals(readme), None).items()}, {"1": 0.3435, "1.1": 0.3435, "1.2": 0.3332, "2": 0.3232})
|
||||
self.assertEqual({goal: round(weight, 4) for goal, weight in ranking.goal_weights(ranking.readme_goals(readme), None).items()}, {"1": 0.3435, "1.1": 0.3435, "1.2": 0.3332, "2": 0.3232})
|
||||
|
||||
def test_weighs_5_achieve_goals_from_0212_to_0188_and_15_from_0082_to_0053_as_the_help_says(self):
|
||||
for count, first, last in ((5, 0.212, 0.188), (15, 0.082, 0.053)):
|
||||
with self.subTest(count=count):
|
||||
goals = rank_todo.readme_goals("## Goals\n\n" + "".join(f"{number}. **Achieve:** G.\n" for number in range(1, count + 1)))
|
||||
weights = list(rank_todo.goal_weights(goals, None).values())
|
||||
goals = ranking.readme_goals("## Goals\n\n" + "".join(f"{number}. **Achieve:** G.\n" for number in range(1, count + 1)))
|
||||
weights = list(ranking.goal_weights(goals, None).values())
|
||||
self.assertEqual((round(weights[0], 3), round(weights[-1], 3), round(sum(weights), 6)), (first, last, 1))
|
||||
for figure in (rank_todo.GOAL_STEP, first, last):
|
||||
self.assertIn(str(figure), rank_todo.__doc__)
|
||||
self.assertIn(f"While it is under {rank_todo.FLOOR}, or the history holds no scoring run, code health weighs {rank_todo.UNDER_FLOOR} times its weight by position, and the other goals keep theirs.", " ".join(rank_todo.__doc__.split()))
|
||||
for figure in (ranking.GOAL_STEP, first, last):
|
||||
self.assertIn(str(figure), ranking.__doc__)
|
||||
self.assertIn(f"While it is under {ranking.FLOOR}, or the history holds no scoring run, code health weighs {ranking.UNDER_FLOOR} times its weight by position, and the other goals keep theirs.", " ".join(ranking.__doc__.split()))
|
||||
|
||||
def test_scores_an_item_by_the_weights_of_the_goals_it_moves(self):
|
||||
readme = "## Goals\n\n" + VOID + "1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
|
||||
@@ -143,7 +142,7 @@ class Rank(unittest.TestCase):
|
||||
self.assertEqual(ranked.under_bar, ["item 2 scores 0.0, under the bar 2; delete it, or mark it with a reason the bar does not apply"])
|
||||
|
||||
def test_holds_each_item_a_decision_cites_and_says_how_to_settle_a_finished_one(self):
|
||||
self.assertIsInstance(self.ranked(decisions=DECISIONS + "Until `todo.md` item 4 lands.\n"), rank_todo.Ranked)
|
||||
self.assertIsInstance(self.ranked(decisions=DECISIONS + "Until `todo.md` item 4 lands.\n"), ranking.Ranked)
|
||||
gone = self.ranked(TODO.replace("| 5 | 0.1.0 | | decision | **Move the writes out.** | 1 | 1 | 4 | 5 | 5 | 2.1 by 1 | 0 |\n", ""))
|
||||
self.assertEqual(gone.reason, "docs/decisions.md cites \"`todo.md` item 5\", which todo.md no longer holds; revise that decision to say what holds now")
|
||||
|
||||
@@ -157,11 +156,11 @@ class Rank(unittest.TestCase):
|
||||
self.assertEqual(self.ranked(ranked.text.replace("| 2 | 0.1.0 | | |", "| 2 | 0.1.0 | | owner |")).under_bar, [])
|
||||
|
||||
def test_reads_goals_and_sub_goals_in_reading_order(self):
|
||||
self.assertEqual(rank_todo.readme_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
|
||||
self.assertEqual(rank_todo.readme_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
|
||||
self.assertEqual(rank_todo.readme_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
|
||||
self.assertEqual(rank_todo.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("README.md's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
|
||||
self.assertEqual(rank_todo.readme_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README.replace(" 1.", "\t1.")), [("1", "Achieve"), ("2", "Maintain"), ("2.1", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:** Correct.", "```\n## Goals\n```\n2. Correct.")), [("1", "Achieve"), ("2", None), ("2.1", "Achieve")])
|
||||
self.assertEqual(ranking.readme_goals(README.replace("2. **Maintain:**", "1. **Maintain:**")), Failure("README.md's ## Goals numbers 1, 1, 1.1; number each goal by its position"))
|
||||
self.assertEqual(ranking.readme_goals("## Goals\n\n1. **Achieve:** A.\n 1. **Achieve:** B.\n\t2. **Achieve:** C.\n"), [("1", "Achieve"), ("1.1", "Achieve"), ("1.2", "Achieve")])
|
||||
|
||||
def test_refuses_a_goal_it_cannot_weigh(self):
|
||||
cases = {
|
||||
@@ -187,7 +186,7 @@ class Rank(unittest.TestCase):
|
||||
readme = "## Goals\n\n" + VOID + "1. **Achieve:** A.\n 1. **Maintain:** B.\n 2. **Achieve:** C.\n2. **Achieve:** D.\n"
|
||||
todo = TODO.replace("2.1 by 8, 1 by 6", "1.2 by 2, 1 by 3").replace("| 2.1 by 1 |", "| 2 by 1 |")
|
||||
self.assertEqual(self.ranked(todo, readme), Failure("item 3 names goal 1 and its sub-goal 1.2; name one, never both: the sub-goal where the move serves it, else the parent"))
|
||||
self.assertIsInstance(self.ranked(todo.replace("1.2 by 2, 1 by 3", "1.2 by 2, 2 by 3"), readme), rank_todo.Ranked)
|
||||
self.assertIsInstance(self.ranked(todo.replace("1.2 by 2, 1 by 3", "1.2 by 2, 2 by 3"), readme), ranking.Ranked)
|
||||
|
||||
def test_scores_every_item_zero_where_readme_marks_no_goal_achieve(self):
|
||||
ranked = self.ranked(TODO.replace("2.1 by 8, 1 by 6", "").replace("| 2.1 by 1 |", "| |").replace("| 1 by 9 |", "| |"), README.replace("**Achieve:**", "**Maintain:**"))
|
||||
@@ -253,7 +252,7 @@ class CodeHealth(unittest.TestCase):
|
||||
todo = TODO.split("| 1 | 0.2.0", 1)[0].replace("`Bar = 2`", "`Bar = 0.1`") + "| 1 | 0.1.0 | | | **Read easier.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 0 |\n| 2 | 0.1.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 0 |\n"
|
||||
|
||||
def scores(self, history, readme=readme):
|
||||
ranked = rank_todo.rank(self.todo, readme, "", history)
|
||||
ranked = ranking.rank(self.todo, readme, "", history)
|
||||
return ranked if isinstance(ranked, Failure) else {line.split(" | ")[0]: line.rsplit(" | ", 1)[1].rstrip(" |") for line in ranked.text.splitlines() if line.startswith("| ") and " 0.1.0 " in line}
|
||||
|
||||
def entry(self, overall, at="2026-10-08T12", read="PR #1 at aaaaaaa"):
|
||||
@@ -304,7 +303,7 @@ class CodeHealth(unittest.TestCase):
|
||||
def test_drops_code_health_where_readme_voids_it(self):
|
||||
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
|
||||
self.assertEqual(self.scores("", voided), Failure("item 1 names code health, which README.md voids; drop it from the item's Moves, or the void from README.md"))
|
||||
ranked = rank_todo.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", "")
|
||||
ranked = ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", "")
|
||||
self.assertIn("| **Read easier.** | 1 | 1 | 1 | 1 | 1 | 1 by 2 | 100.0 |", ranked.text)
|
||||
|
||||
def test_weighs_a_defects_maintain_goal_as_code_health_four_times_over_under_an_overall_of_7(self):
|
||||
@@ -312,18 +311,18 @@ class CodeHealth(unittest.TestCase):
|
||||
todo = self.todo.replace("| 2 | 0.1.0 | | | **Do A.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 |", "| 2 | 0.1.0 | | defect | **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 |")
|
||||
for history, value in (("", "101.5"), (SCORED.format(overall="7.00"), "25.4")):
|
||||
with self.subTest(history=history):
|
||||
self.assertIn(f"| **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 | {value} |", rank_todo.rank(todo, readme, "", history).text)
|
||||
self.assertIn(f"| **Restore B.** | 1 | 1 | 1 | 1 | 1 | 2 by 1 | {value} |", ranking.rank(todo, readme, "", history).text)
|
||||
|
||||
def test_refuses_a_plan_whose_project_opts_out_of_the_comprehension_check_yet_keeps_code_health(self):
|
||||
opted_out = "## review opt-out: the architect and the comprehension check\n\nCosts rounds.\n"
|
||||
self.assertEqual(rank_todo.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
|
||||
self.assertIsInstance(rank_todo.rank(self.todo, self.readme, opted_out.replace(" and the comprehension check", ""), ""), rank_todo.Ranked)
|
||||
self.assertEqual(ranking.rank(self.todo, self.readme, opted_out, ""), Failure("docs/decisions.md opts out of the comprehension check, so code health has no signal; void it in README.md's ## Goals with `**Void:** code health, since <reason>.`, as ~/.claude/CLAUDE.md → 'Shared goal' says"))
|
||||
self.assertIsInstance(ranking.rank(self.todo, self.readme, opted_out.replace(" and the comprehension check", ""), ""), ranking.Ranked)
|
||||
voided = "## Goals\n\n**Void:** code health, since nobody reads the probes.\n\n1. **Achieve:** A.\n"
|
||||
self.assertIsInstance(rank_todo.rank(self.todo.replace("code health by 1", "1 by 2"), voided, opted_out, ""), rank_todo.Ranked)
|
||||
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, opted_out, ""), ranking.Ranked)
|
||||
|
||||
def test_ranks_a_project_that_voids_code_health_whatever_its_history_holds(self):
|
||||
voided = "## Goals\n\n**Void:** code health, since it is a one-off script.\n\n1. **Achieve:** A.\n"
|
||||
self.assertIsInstance(rank_todo.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", SCORED.format(overall="high")), rank_todo.Ranked)
|
||||
self.assertIsInstance(ranking.rank(self.todo.replace("code health by 1", "1 by 2"), voided, "", SCORED.format(overall="high")), ranking.Ranked)
|
||||
|
||||
def test_refuses_a_void_of_anything_but_code_health(self):
|
||||
self.assertEqual(self.scores("", "## Goals\n\n**Void:** speed, since nobody waits.\n\n1. **Achieve:** A.\n"), Failure("README.md's ## Goals voids `speed, since nobody waits.`; only code health may be voided, as `**Void:** code health, since <reason>.`"))
|
||||
@@ -346,14 +345,14 @@ class CodeHealth(unittest.TestCase):
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
pathlib.Path(temp, "docs", "comprehension-history.md").write_text(SCORED.format(overall="7.00"))
|
||||
with contextlib.redirect_stderr(io.StringIO()):
|
||||
self.assertEqual(rank_todo.main([str(todo)]), 0)
|
||||
self.assertEqual(ranking.main([str(todo)]), 0)
|
||||
self.assertIn("| code health by 1 | 25.4 |", todo.read_text())
|
||||
|
||||
|
||||
class Risk(unittest.TestCase):
|
||||
"""R is L + E + I - 2, which rank_todo.py writes, at least 7 when I is 5 and at least 5 when I is 4."""
|
||||
def ranked(self, todo):
|
||||
return rank_todo.rank(todo, README, DECISIONS, "")
|
||||
return ranking.rank(todo, README, DECISIONS, "")
|
||||
|
||||
def test_writes_r_from_l_e_and_i_over_a_stale_or_missing_r(self):
|
||||
ranked = self.ranked(TODO).text
|
||||
@@ -402,7 +401,7 @@ class Risk(unittest.TestCase):
|
||||
class OldShape(unittest.TestCase):
|
||||
"""A table with A, G and Goals, from before the Moves column, ranks by the formula and goal weights it states until its project reshapes it."""
|
||||
def ranked(self, todo=OLD_SHAPE, readme=README):
|
||||
return rank_todo.rank(todo, readme, DECISIONS, "")
|
||||
return ranking.rank(todo, readme, DECISIONS, "")
|
||||
|
||||
def test_scores_by_the_stated_weights_and_says_to_reshape(self):
|
||||
ranked = self.ranked()
|
||||
@@ -412,7 +411,7 @@ class OldShape(unittest.TestCase):
|
||||
| 5 | 0.1.0 | | decision | **Move the writes out.** | 5 | 5 | 3 | 4 | 5 | 2.1 | 5.1 |
|
||||
| 1 | 0.2.0 | | | **Ship the later thing.** | 1 | 1 | 3 | 9 | 9 | 1 | 34.8 |
|
||||
""", ranked.text)
|
||||
self.assertEqual(ranked.notes, [rank_todo.RESHAPE])
|
||||
self.assertEqual(ranked.notes, [ranking.RESHAPE])
|
||||
self.assertEqual(self.ranked(ranked.text), ranked)
|
||||
unmarked = "# P\n\n## Goals\n\n1. Fast.\n2. Correct.\n 1. Tested.\n"
|
||||
self.assertEqual(self.ranked(readme=unmarked), ranked)
|
||||
@@ -429,7 +428,7 @@ class OldShape(unittest.TestCase):
|
||||
|
||||
def test_ranks_a_table_from_before_c_joined_and_says_to_reshape_it(self):
|
||||
legacy = OLD_SHAPE.split("## Items")[0] + "## Items\n\n| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |\n|---|---|---|---|---|---|---|---|---|---|\n| 2 | 0.1.0 | | **Tighten the tests.** | 2 | 4 | 5 | 5 | 2.1 | 0 |\n"
|
||||
self.assertEqual(rank_todo.rank(legacy, README, "", "").notes, [rank_todo.RESHAPE])
|
||||
self.assertEqual(ranking.rank(legacy, README, "", "").notes, [ranking.RESHAPE])
|
||||
|
||||
def test_refuses_a_table_with_both_moves_and_goals(self):
|
||||
both = OLD_SHAPE.replace("| Goals | Score |\n|---|", "| Goals | Moves | Score |\n|---|---|").replace(" | 0 |\n", " | 1 by 1 | 0 |\n")
|
||||
@@ -439,14 +438,14 @@ class OldShape(unittest.TestCase):
|
||||
|
||||
def test_names_the_goals_column_a_table_misspells_by_its_shape(self):
|
||||
misspelt = TODO.replace("| S | Moves |", "| S | Move |")
|
||||
self.assertEqual(rank_todo.rank(misspelt, README, DECISIONS, ""), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
|
||||
self.assertEqual(ranking.rank(misspelt, README, DECISIONS, ""), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
|
||||
self.assertEqual(todo_table.items(misspelt), Failure("todo.md's items table has no Moves column; rank_todo.py --help shows a valid one"))
|
||||
self.assertEqual(self.ranked(OLD_SHAPE.replace("| G | Goals |", "| G | Goal |")), Failure("todo.md's items table has no Goals column; rank_todo.py --help shows a valid one"))
|
||||
|
||||
|
||||
class Blockers(unittest.TestCase):
|
||||
def ranked(self, todo):
|
||||
return rank_todo.rank(todo, README, DECISIONS, "")
|
||||
return ranking.rank(todo, README, DECISIONS, "")
|
||||
|
||||
def test_ranks_each_blocker_just_above_the_first_item_it_blocks(self):
|
||||
ranked = self.ranked(TODO.replace("| 3 | 0.1.0 | |", "| 3 | 0.1.0 | 5, 2 |"))
|
||||
@@ -525,7 +524,7 @@ class Blockers(unittest.TestCase):
|
||||
|
||||
def test_refuses_text_under_items_beside_the_table(self):
|
||||
last = TODO.split("\n## Details")[0] + "\n"
|
||||
self.assertIsInstance(self.ranked(last), rank_todo.Ranked)
|
||||
self.assertIsInstance(self.ranked(last), ranking.Ranked)
|
||||
beside = Failure("## 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")
|
||||
for ordered in (TODO.replace("## Items\n\n", "## Items\n\nRelease 0.1.0 takes item 5 first.\n\n"), TODO.replace("## Items\n\n", "## Items\nTake item 5 first.\n\n"), TODO.replace("| 2.1 by 1 | 0 |\n\n## Details", "| 2.1 by 1 | 0 |\n\nTake item 5 first.\n\n## Details"), last + "\nTake item 5 first.\n"):
|
||||
with self.subTest(ordered=ordered[-60:]):
|
||||
@@ -559,15 +558,15 @@ class Renamed(unittest.TestCase):
|
||||
self.assertIsInstance(todo_table.renames(f"## Renamed\n\n{bad}\n"), Failure)
|
||||
|
||||
def test_fails_on_a_renamed_section_that_does_not_parse(self):
|
||||
failed = rank_todo.rank(TODO + "\n## Renamed\n\nsoon\n", README, DECISIONS, "")
|
||||
failed = ranking.rank(TODO + "\n## Renamed\n\nsoon\n", README, DECISIONS, "")
|
||||
self.assertIsInstance(failed, Failure)
|
||||
self.assertIn("## Renamed", failed.reason)
|
||||
|
||||
def test_ranks_a_plan_with_a_valid_renamed_section(self):
|
||||
self.assertIsInstance(rank_todo.rank(TODO + "\n## Renamed\n\n- 0.3.0 renamed to 0.4.0\n", README, DECISIONS, ""), rank_todo.Ranked)
|
||||
self.assertIsInstance(ranking.rank(TODO + "\n## Renamed\n\n- 0.3.0 renamed to 0.4.0\n", README, DECISIONS, ""), ranking.Ranked)
|
||||
|
||||
def test_fails_on_an_item_filed_under_a_release_the_plan_marks_renamed(self):
|
||||
live = rank_todo.rank(TODO + "\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", README, DECISIONS, "")
|
||||
live = ranking.rank(TODO + "\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", README, DECISIONS, "")
|
||||
self.assertIsInstance(live, Failure)
|
||||
self.assertIn("marks release 0.2.0 renamed but files item 1 under it", live.reason)
|
||||
|
||||
@@ -576,7 +575,7 @@ class Renamed(unittest.TestCase):
|
||||
class Main(unittest.TestCase):
|
||||
def run_main(self, *argv):
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()) as said:
|
||||
code = rank_todo.main(list(argv))
|
||||
code = ranking.main(list(argv))
|
||||
return code, said.getvalue()
|
||||
|
||||
def test_ranks_the_file_in_place_and_check_writes_nothing(self):
|
||||
@@ -613,14 +612,14 @@ class Main(unittest.TestCase):
|
||||
pathlib.Path(temp, "README.md").write_text(README)
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
pathlib.Path(temp, "docs", "decisions.md").write_text(DECISIONS)
|
||||
self.assertEqual(self.run_main(str(todo)), (0, f"{todo}: {rank_todo.RESHAPE}\n"))
|
||||
self.assertEqual(self.run_main(str(todo)), (0, f"{todo}: {ranking.RESHAPE}\n"))
|
||||
self.assertEqual(self.run_main("--check", str(todo)), (0, ""))
|
||||
|
||||
def test_shows_a_valid_file_in_help_and_names_arguments_it_cannot_read(self):
|
||||
self.assertEqual(self.run_main("--help")[0], 0)
|
||||
skeleton = "\n".join(line[4:] for line in rank_todo.__doc__.split("\n") if line.startswith(" "))
|
||||
ranked = rank_todo.rank(skeleton, "## Goals\n\n1. **Achieve:** Work.\n", "", "")
|
||||
self.assertIsInstance(ranked, rank_todo.Ranked)
|
||||
skeleton = "\n".join(line[4:] for line in ranking.__doc__.split("\n") if line.startswith(" "))
|
||||
ranked = ranking.rank(skeleton, "## Goals\n\n1. **Achieve:** Work.\n", "", "")
|
||||
self.assertIsInstance(ranked, ranking.Ranked)
|
||||
self.assertEqual((ranked.under_bar, ranked.notes), ([], []))
|
||||
self.assertEqual(self.run_main("--fix"), (1, "rank_todo.py: cannot read the arguments --fix; usage: rank_todo.py [--check] [todo.md]\n"))
|
||||
|
||||
@@ -628,5 +627,5 @@ class Main(unittest.TestCase):
|
||||
class ThisRepo(unittest.TestCase):
|
||||
def test_todo_md_is_ranked_with_nothing_under_the_bar(self):
|
||||
text = (ROOT / "todo.md").read_text(encoding="utf-8")
|
||||
ranked = rank_todo.rank(text, *((ROOT / name).read_text(encoding="utf-8") for name in ("README.md", "docs/decisions.md", "docs/comprehension-history.md")))
|
||||
self.assertEqual(ranked, rank_todo.Ranked(text, [], []))
|
||||
ranked = ranking.rank(text, *((ROOT / name).read_text(encoding="utf-8") for name in ("README.md", "docs/decisions.md", "docs/comprehension-history.md")))
|
||||
self.assertEqual(ranked, ranking.Ranked(text, [], []))
|
||||
@@ -4,10 +4,10 @@ import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from test_env import isolated_env
|
||||
from release import newest_tag, tagged
|
||||
from release_plan.release import newest_tag, tagged
|
||||
|
||||
|
||||
class NewestTag(unittest.TestCase):
|
||||
@@ -4,13 +4,13 @@ import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from test_env import isolated_env
|
||||
import release_standing
|
||||
import todo_table
|
||||
from release import version
|
||||
from release_plan import release_standing
|
||||
from release_plan import todo_table
|
||||
from release_plan.release import version
|
||||
|
||||
|
||||
HEADER = "## Items\n\n| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |\n|---|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
@@ -3,8 +3,8 @@ import re
|
||||
import typing
|
||||
|
||||
from failure import Failure
|
||||
from markdown_text import FENCE, sections
|
||||
from release import parsed, Release, release_of, VERSION
|
||||
from records.markdown_text import FENCE, sections
|
||||
from release_plan.release import parsed, Release, release_of, VERSION
|
||||
|
||||
# Each score a Shape names, and each goal's move, runs from 1 to TOP_SCORE, but for the levels L, E and I, which run from 1 to their LEVELS: ~/.claude/rules/todo-items.md defines each level.
|
||||
TOP_SCORE = 10
|
||||
@@ -5,7 +5,7 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from review_passes import PASS_AGENTS, PASSES
|
||||
from review_rules.review_passes import PASS_AGENTS, PASSES
|
||||
from repo_checks import ROOT
|
||||
from rule_hook.reviewer_rung import SEAT, SECURITY_OPENER
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ import unittest
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from settings_filter import cleaned
|
||||
from git_repo import git
|
||||
from git_cli.git_repo import git
|
||||
from repo_checks import ROOT
|
||||
|
||||
INSTALL = "git config filter.settings.clean bin/settings_filter.py"
|
||||
|
||||
@@ -30,5 +30,5 @@ class Types(unittest.TestCase):
|
||||
self.assertEqual(ran.returncode, 0, ran.stdout + ran.stderr)
|
||||
|
||||
def test_mypy_checks_run_heavy_and_each_root_module(self):
|
||||
self.assertLessEqual({("-p", "run_heavy"), ("-p", "machine_load"), ("-m", "release_standing"), ("-m", "docker_command")}, set(zip(tools()[::2], tools()[1::2])))
|
||||
self.assertLessEqual({("-p", "run_heavy"), ("-p", "machine_load"), ("-p", "release_plan"), ("-m", "failure")}, set(zip(tools()[::2], tools()[1::2])))
|
||||
self.assertNotIn("repo_checks", tools())
|
||||
|
||||
@@ -41,7 +41,7 @@ import typing
|
||||
from transcript_archive.location import archive_root
|
||||
from rung_replay.command import arguments_or_exit, down_from, failed, limited_exit, projects_on
|
||||
from review_replay.rounds import authored_by, lost_inputs, report, reviewed_path, Round, round_from, sample, stamp_seconds
|
||||
from project_key import checkout_of
|
||||
from transcript_archive.project_key import checkout_of
|
||||
from claude_code.reply import claude_reply, Limited
|
||||
from loop_claude.effects import Effects
|
||||
from failure import Failure
|
||||
@@ -49,8 +49,8 @@ from rung_replay.search import first_reply, replayed
|
||||
from claude_code.transcript import first_timestamped_line, read_transcript
|
||||
from model_routing.ladder import LADDER, project_rung, Rung
|
||||
from claude_code.entries import parse_entry, structured_output
|
||||
from review_folder import REPORTS, review_folder
|
||||
from review_passes import ReviewedPass, REVIEWERS
|
||||
from review_rules.review_folder import REPORTS, review_folder
|
||||
from review_rules.review_passes import ReviewedPass, REVIEWERS
|
||||
|
||||
TOOL = "review-replay"
|
||||
USAGE = f"{TOOL} <pass> <model>, <pass> one of {', '.join(REVIEWERS)} and <model> a model on the routing ladder"
|
||||
|
||||
@@ -19,7 +19,7 @@ from loop_claude.effects import Effects, system_effects
|
||||
from failure import Failure
|
||||
from review_replay import main
|
||||
from rung_replay.search import Miss, Replay, Tried
|
||||
from review_passes import REVIEWERS
|
||||
from review_rules.review_passes import REVIEWERS
|
||||
from model_routing.ladder import Rung
|
||||
|
||||
TOOL = pathlib.Path(__file__).resolve().parents[1] / "review-replay"
|
||||
|
||||
@@ -3,8 +3,8 @@ import decimal
|
||||
import re
|
||||
|
||||
from failure import Failure
|
||||
from markdown_text import sections
|
||||
from utc_stamp import utc
|
||||
from records.markdown_text import sections
|
||||
from records.utc_stamp import utc
|
||||
|
||||
ARCHITECT = "Inherited architect"
|
||||
DECIDED_BY = "decided by"
|
||||
@@ -2,7 +2,7 @@
|
||||
import dataclasses
|
||||
import re
|
||||
|
||||
from review_passes import PASSES
|
||||
from review_rules.review_passes import PASSES
|
||||
|
||||
# The most rounds a pass takes per chunk, per `docs/decisions.md` → `review: a pass gets at most two rounds per chunk, …`. rule-hook's `round-cap` refuses a round commit that `past_cap` finds takes its pass past it, and `larv-review round-count` marks a pass that reached it.
|
||||
CAP = 2
|
||||
@@ -2,9 +2,9 @@ import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from review_folder import review_folder
|
||||
from review_rules.review_folder import review_folder
|
||||
|
||||
|
||||
class ReviewFolder(unittest.TestCase):
|
||||
@@ -3,9 +3,9 @@ import sys
|
||||
import typing
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from review_passes import PASS_AGENTS, PASSES, prose, ReviewedPass, REVIEWERS
|
||||
from review_rules.review_passes import PASS_AGENTS, PASSES, prose, ReviewedPass, REVIEWERS
|
||||
|
||||
|
||||
class ReviewPasses(unittest.TestCase):
|
||||
@@ -14,7 +14,7 @@ class ReviewPasses(unittest.TestCase):
|
||||
self.assertEqual(list(REVIEWERS), [name for name in PASSES if PASS_AGENTS[name]])
|
||||
|
||||
def test_names_each_agent_under_agents(self):
|
||||
agents = pathlib.Path(__file__).resolve().parents[1] / "agents"
|
||||
agents = pathlib.Path(__file__).resolve().parents[2] / "agents"
|
||||
self.assertEqual(sorted(REVIEWERS.values()), sorted(path.stem for path in agents.glob("*.md")))
|
||||
|
||||
def test_counts_markdown_an_agent_follows_as_config_and_the_rest_as_prose(self):
|
||||
@@ -2,9 +2,9 @@ import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from round_titles import Findings, lacks_counts, past_cap, round_counts, round_findings, rounds_past_first
|
||||
from review_rules.round_titles import Findings, lacks_counts, past_cap, round_counts, round_findings, rounds_past_first
|
||||
|
||||
|
||||
class Rounds(unittest.TestCase):
|
||||
@@ -10,12 +10,12 @@ import typing
|
||||
from transcript_archive.read import archived_outcomes, chunk_outcomes, finished_chunks
|
||||
from branch_chunks.read import branch_chunks
|
||||
from branch_chunks.cut import BranchChunk
|
||||
from project_key import checkout_of
|
||||
from transcript_archive.project_key import checkout_of
|
||||
from routing_figures.chunk import Chunk, chunk_figures, ChunkFigures, Subagent
|
||||
from git_repo import default_ref, Git
|
||||
from git_cli.git_repo import default_ref, Git
|
||||
from failure import Failure
|
||||
from claude_code.entries import parse_entry
|
||||
from file_writes import replace_file
|
||||
from records.file_writes import replace_file
|
||||
from transcript_archive.outcomes import VERDICT_AT
|
||||
|
||||
FIGURES = "routing-figures.md"
|
||||
|
||||
@@ -5,13 +5,13 @@ import re
|
||||
|
||||
from claude_code.entries import assistant_parts, parts, tool_call, tool_result
|
||||
from branch_chunks.cut import BranchChunk
|
||||
from git_command import commits
|
||||
from git_cli.git_command import commits
|
||||
from routing_figures.dollars import costed, Dollars, Message, messages, recorded_costs, Spent
|
||||
from model_routing.route import ESCALATION_MARKER, Route, route_from
|
||||
from transcript_archive.outcomes import judge_costs, UNFINISHED_AT, workers
|
||||
from round_titles import rounds_past_first
|
||||
from review_rules.round_titles import rounds_past_first
|
||||
from model_routing.ladder import Rung
|
||||
from shell_command import simple_commands
|
||||
from command_lines.shell_command import simple_commands
|
||||
|
||||
ESCALATION = re.compile(rf"{ESCALATION_MARKER} ([0-9]+):")
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@ import re
|
||||
|
||||
from routing_figures.calls import Call, SENTENCES
|
||||
from failure import Failure
|
||||
from file_writes import replace_file, replace_json
|
||||
from utc_stamp import STAMPED
|
||||
from records.file_writes import replace_file, replace_json
|
||||
from records.utc_stamp import STAMPED
|
||||
|
||||
CYCLES_PER_CHECK = 20
|
||||
RAISED = "routing-calls-raised.md"
|
||||
|
||||
@@ -20,9 +20,9 @@ from routing_figures.calls import Call, calls, totals
|
||||
from routing_figures.chunk import Chunk, chunk_figures, ChunkFigures, Reports, Subagent
|
||||
from routing_figures.state import due
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
from git_cli import git_repo
|
||||
from test_env import isolated_env
|
||||
from todo_table import Item
|
||||
from release_plan.todo_table import Item
|
||||
from model_routing.ladder import LADDER, Rung
|
||||
from transcript_archive import outcomes, write
|
||||
from routing_figures.render import render
|
||||
|
||||
@@ -1,9 +1,7 @@
|
||||
import pathlib
|
||||
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
|
||||
|
||||
from git_cli import git_repo
|
||||
def guarded_git(directory: str, *args: str) -> str | Failure:
|
||||
"""What git printed in directory, stripped, run guarded: the hook runs git in a checkout the call has not yet been allowed to touch."""
|
||||
ran = git_repo.git(*args, cwd=directory, guarded=True)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Whether a simple command is a heavy one, for the `run-heavy` rule: a docker build, or a run of a mutation tool."""
|
||||
from docker_command import docker_subcommand
|
||||
from shell_command import launched, tool_name
|
||||
from command_lines.docker_command import docker_subcommand
|
||||
from command_lines.shell_command import launched, tool_name
|
||||
|
||||
# Each mutation tool, and the words that make its call a mutation run when one of them follows it within two words; where the set is empty, every call is one.
|
||||
MUTATORS = {"cargo": {"mutants"}, "infection": set(), "mutmut": {"run"}, "stryker": {"run"}}
|
||||
|
||||
@@ -38,14 +38,14 @@ import typing
|
||||
|
||||
from rule_hook.call import applied, Call, FILE_TOOLS, parsed_call, text
|
||||
from rule_hook.rules import Breach, check, Checked, command_breaches, file_breaches, rules_help
|
||||
from git_command import commits
|
||||
from git_cli.git_command import commits
|
||||
from failure import Failure
|
||||
from rule_hook.override_log import Log, log_path, logged, print_overrides, write_override
|
||||
from rule_hook.repeat_read import read_breaches
|
||||
from rule_hook.reviewer_report import report_breaches
|
||||
from rule_hook.reviewer_rung import reviewer_breaches, skill_breaches
|
||||
from rule_hook.round_cap import round_cap_breaches
|
||||
from shell_command import simple_commands
|
||||
from command_lines.shell_command import simple_commands
|
||||
from rule_hook.todo_check import todo_breaches
|
||||
|
||||
|
||||
|
||||
@@ -6,10 +6,10 @@ import sys
|
||||
import typing
|
||||
|
||||
from rule_hook.rules import Breach
|
||||
from git_repo import default_ref
|
||||
from git_cli.git_repo import default_ref
|
||||
from rule_hook.git import existing, guarded_git
|
||||
from failure import Failure
|
||||
from utc_stamp import utc
|
||||
from records.utc_stamp import utc
|
||||
|
||||
LOG = "rule-overrides.tsv"
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ from rule_hook.call import Call, FILE_TOOLS, text
|
||||
from claude_code.transcript import current_thread, read_transcript
|
||||
from failure import Failure
|
||||
from claude_code.entries import parts, tool_call, tool_result, tool_use_id
|
||||
from shell_command import resolved, simple_commands
|
||||
from command_lines.shell_command import resolved, simple_commands
|
||||
|
||||
# The lines a Read without a limit returns.
|
||||
READ_LIMIT = 2000
|
||||
|
||||
@@ -4,7 +4,7 @@ import pathlib
|
||||
|
||||
from rule_hook.rules import Breach
|
||||
from rule_hook.call import Call
|
||||
from review_folder import REPORTS
|
||||
from review_rules.review_folder import REPORTS
|
||||
|
||||
# Each agent under agents/, read from the folder, so an agent the routing tables miss is still confined.
|
||||
AGENT_FILES = frozenset(path.stem for path in (pathlib.Path(__file__).resolve().parents[2] / "agents").glob("*.md"))
|
||||
|
||||
@@ -5,11 +5,11 @@ from rule_hook.rules import Breach
|
||||
from rule_hook.call import Call, text
|
||||
from claude_code.entries import content
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
from git_cli import git_repo
|
||||
from rule_hook.git import guarded_git
|
||||
from model_routing.worker_rungs import handed
|
||||
from model_routing.ladder import position, review_rung, ReviewKind, Rung
|
||||
from review_passes import prose, REVIEWERS
|
||||
from review_rules.review_passes import prose, REVIEWERS
|
||||
from claude_code.transcript import read_transcript
|
||||
|
||||
# The pass each agent under agents/ reviews.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
from rule_hook.rules import Breach
|
||||
from round_titles import cap, past_cap, round_counts, round_pass
|
||||
from git_command import CommitCall
|
||||
from review_rules.round_titles import cap, past_cap, round_counts, round_pass
|
||||
from git_cli.git_command import CommitCall
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
from review_passes import PASSES
|
||||
from git_cli import git_repo
|
||||
from review_rules.review_passes import PASSES
|
||||
|
||||
|
||||
def round_cap_breaches(commit: CommitCall) -> list[Breach]:
|
||||
|
||||
@@ -3,13 +3,13 @@ import posixpath
|
||||
import re
|
||||
import typing
|
||||
|
||||
from round_titles import CAP, lacks_counts, RELEASE_REVIEW_CAP
|
||||
from git_command import commits
|
||||
from review_rules.round_titles import CAP, lacks_counts, RELEASE_REVIEW_CAP
|
||||
from git_cli.git_command import commits
|
||||
from run_heavy.capped_docker import finds_this_docker
|
||||
from rule_hook.heavy_command import heavy
|
||||
from shell_command import launched, Simple
|
||||
from review_folder import REPORTS
|
||||
from docker_command import unlimited
|
||||
from command_lines.shell_command import launched, Simple
|
||||
from review_rules.review_folder import REPORTS
|
||||
from command_lines.docker_command import unlimited
|
||||
|
||||
RuleName = typing.Literal["action-pin", "commit-one-line", "docker-run-memory", "ignorefile-sorted", "image-pin", "no-ai-attribution", "repeat-read", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check"]
|
||||
|
||||
|
||||
@@ -15,13 +15,13 @@ from rule_hook.repeat_read import Asked, modified, read_breaches, result_lines
|
||||
from rule_hook.rules import blocks, Breach, check, command_breaches, file_breaches, overrides
|
||||
from rule_hook.main import breaches_of
|
||||
from rule_hook.call import Call, parsed_call
|
||||
from git_command import commit_message, CommitCall, commits
|
||||
from test_rank_todo import DECISIONS, README, TODO
|
||||
from git_cli.git_command import commit_message, CommitCall, commits
|
||||
from release_plan.test_ranking import DECISIONS, README, TODO
|
||||
from rule_hook.git import guarded_git
|
||||
from test_env import isolated_env
|
||||
from rule_hook.override_log import LogLine, parsed_entry, this_chunks
|
||||
from rule_hook.reviewer_rung import reviewer_breaches, skill_breaches
|
||||
from shell_command import segments, simple_commands
|
||||
from command_lines.shell_command import segments, simple_commands
|
||||
|
||||
HOOK = pathlib.Path(__file__).resolve().parents[1] / "rule-hook"
|
||||
# Built from parts, so this file carries no attribution of its own.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user