Refuse a Touches: list touch-predictions cannot read in todo-item add and edit, and in rank_todo.py --check
This commit is contained in:
@@ -11,6 +11,7 @@ from plan import ranking
|
||||
from record_store.stores import RecordStore
|
||||
from text_files.file_writes import replace_file
|
||||
from plan_store.scoring import weighing_texts
|
||||
from touch_predictions.prediction import predicted
|
||||
|
||||
# What the reader of a missing todo.md is told.
|
||||
MISSING = "every project keeps a todo.md, and rank_todo.py --help shows one"
|
||||
@@ -84,7 +85,7 @@ class FilePlan:
|
||||
return ranked
|
||||
|
||||
def check(self) -> list[str]:
|
||||
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, or an item scores under the bar."""
|
||||
"""Why `rank_todo.py --check` fails on the file, empty when it passes: the file is not ranked, an item scores under the bar, or an item's `Touches:` list is one touch-predictions cannot read."""
|
||||
texts = self.texts()
|
||||
if isinstance(texts, Failure):
|
||||
return [texts.reason]
|
||||
@@ -92,7 +93,7 @@ class FilePlan:
|
||||
if isinstance(ranked, Failure):
|
||||
return [ranked.reason]
|
||||
unranked = [] if ranked.text == texts[0] else [f"{self.path}: not ranked; run rank_todo.py on it"]
|
||||
return unranked + [f"{self.path}: {line}" for line in ranked.under_bar]
|
||||
return unranked + [f"{self.path}: {line}" for line in ranked.under_bar + unreadable_touches(texts[0])]
|
||||
|
||||
def reported(self, ranked: ranking.Ranked) -> list[str]:
|
||||
"""Ranking's notes and under-bar lines, each prefixed with the file's path, as a tool prints them on stderr."""
|
||||
@@ -115,6 +116,14 @@ class FilePlan:
|
||||
return weighing if isinstance(weighing, Failure) else (plan, *weighing)
|
||||
|
||||
|
||||
def unreadable_touches(todo: str) -> list[str]:
|
||||
"""Why touch-predictions cannot read each item's `Touches:` list that it cannot. Every item is read, not only the next release's: a later item moves into the next release with its detail, and the list is fixed most cheaply where it was written."""
|
||||
details = item_details(todo)
|
||||
if isinstance(details, Failure):
|
||||
return [details.reason]
|
||||
return [f"item {id_}: {read.reason}" for id_, detail in details.items() if isinstance(read := predicted(detail), Failure)]
|
||||
|
||||
|
||||
def plan_of(todo: str) -> Plan | Failure:
|
||||
"""The plan a todo.md's text holds."""
|
||||
found = items(todo)
|
||||
|
||||
+3
-2
@@ -11,7 +11,8 @@ question rows come first, then security rows, then the rest, each group by score
|
||||
then by ID. Then it moves each blocker, an item another's Blocked by cell names, that ranks below
|
||||
an item it blocks to just above the first such item. Orders the details to match. Writes each
|
||||
item's R, and adds the Blocked by and R columns to a table without them. --check doesn't write
|
||||
anything and fails when the file is not ranked as it would be.
|
||||
anything and fails when the file is not ranked as it would be, or when an item's detail holds a
|
||||
`Touches:` list that touch-predictions cannot read, as `touch-predictions --help` spells it.
|
||||
|
||||
A valid todo.md; ## Details and each item's detail are optional:
|
||||
|
||||
@@ -87,7 +88,7 @@ Exit 1, saying why, on bad arguments, a checkout no config names or a config tha
|
||||
file given that is not the config's plan, a file that cannot be read or written, a todo.md, goals file or docs/decisions.md that breaks the
|
||||
rules above, a scoring run on docs/comprehension-history.md's newest scored commit with no Mean row
|
||||
ending in its overall, an item that is not exempt scoring under the bar, or --check finding the file
|
||||
unranked.
|
||||
unranked or a `Touches:` list it cannot read.
|
||||
"""
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
@@ -11,6 +11,7 @@ from project_config.test_project_config import configured
|
||||
from plan.test_ranking import DECISIONS, OLD_SHAPE, README, TODO
|
||||
from project_config.settings import DEFAULT_FLOOR
|
||||
from plan import goals_file, ranking
|
||||
from todo_item.test_todo_item import READABLE_TOUCHES, UNREADABLE_BULLETS
|
||||
import rank_todo
|
||||
|
||||
|
||||
@@ -102,6 +103,25 @@ class Main(unittest.TestCase):
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{todo}: {under}\n"))
|
||||
self.assertEqual(self.run_main("--check", str(todo)), (1, f"{todo}: {under}\n"))
|
||||
|
||||
def test_check_fails_on_each_item_whose_touches_list_it_cannot_read(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
configured(self, pathlib.Path(temp))
|
||||
self.enterContext(contextlib.chdir(temp))
|
||||
pathlib.Path(temp, "README.md").write_text(README)
|
||||
pathlib.Path(temp, "docs").mkdir()
|
||||
pathlib.Path(temp, "docs", "decisions.md").write_text(DECISIONS)
|
||||
for bullet in UNREADABLE_BULLETS:
|
||||
with self.subTest(bullet):
|
||||
# Item 1 sits in a later release than item 3: the check reads every item's list, not only the next release's.
|
||||
todo.write_text(TODO.replace("Fast detail.", READABLE_TOUCHES).replace("Later detail.", f"Touches:\n\n{bullet}"))
|
||||
self.assertEqual(self.run_main(str(todo))[0], 0)
|
||||
code, said = self.run_main("--check", str(todo))
|
||||
self.assertEqual(code, 1)
|
||||
self.assertTrue(said.startswith(f"{todo}: item 1: "), said)
|
||||
self.assertIn(repr(bullet), said)
|
||||
self.assertEqual(said.count("\n"), 1)
|
||||
|
||||
def test_says_to_reshape_an_old_shape_table_but_passes_the_check(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
|
||||
+14
-4
@@ -27,7 +27,8 @@ list and show read only the plan, and print no Score: an item's place in list's
|
||||
|
||||
add files the item under the next free ID, with the tagline in bold, and the detail it reads from
|
||||
stdin, if any. The detail may hold no ## or ### heading.
|
||||
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar.
|
||||
It prints `Filed item <ID> in <plan>.` It doesn't write anything where ranking fails or scores the item under the bar,
|
||||
or where the detail holds a `Touches:` list that touch-predictions cannot read, as `touch-predictions --help` spells it.
|
||||
In a Jira epic, add files a Task under the epic, and <ID> is the new issue's number. The release
|
||||
must be one of the Jira project's Fix Versions, named as 1.2.0 or v1.2.0 there, and --exempt
|
||||
security also labels the issue `security`. The item scores by the config's `jira-score-formula`, and
|
||||
@@ -41,7 +42,8 @@ edit sets the cells whose flag is given and leaves the rest; an empty value, as
|
||||
empties the cell. --detail replaces the detail with the text on stdin, and --clear-detail removes it.
|
||||
Text on stdin without --detail, and --detail without text on stdin, are refused, so no detail is
|
||||
dropped or wiped by mistake. It prints `Edited item <ID> in <plan>.` It doesn't write anything where
|
||||
ranking fails or scores the item under the bar.
|
||||
ranking fails or scores the item under the bar, or where a new detail holds a `Touches:` list that
|
||||
touch-predictions cannot read.
|
||||
In a Jira epic, edit changes an issue the loop filed: its summary, description and scores, the label
|
||||
`security` with --exempt, and its "is blocked by" links with --blocked-by: it makes a link for each
|
||||
blocker added and deletes the link of each blocker dropped. Each blocker must be an open child of the
|
||||
@@ -92,6 +94,7 @@ from plan_store.stores import store as plan_store
|
||||
from record_store.stores import RecordStore, store
|
||||
from todo_item.table import shown, table
|
||||
from todo_item.edits import with_bullet
|
||||
from touch_predictions.prediction import predicted
|
||||
|
||||
# Each score flag, as --l or --L, and the field it sets.
|
||||
LETTERS = ("L", "E", "I", "S")
|
||||
@@ -115,7 +118,8 @@ def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.T
|
||||
case "show":
|
||||
done = show(args, plan)
|
||||
case "add":
|
||||
done = reported(plan.add(fields(args), piped(stdin)), "not filed", lambda written: f"Filed item {written.id} in {plan.label}.")
|
||||
detail = piped(stdin)
|
||||
done = unreadable(detail, "not filed") or reported(plan.add(fields(args), detail), "not filed", lambda written: f"Filed item {written.id} in {plan.label}.")
|
||||
case "edit":
|
||||
done = edit(args, plan, piped(stdin))
|
||||
case "move":
|
||||
@@ -194,6 +198,12 @@ def reported(written: Written | Failure, refusal: str, done: typing.Callable[[Wr
|
||||
return done(written)
|
||||
|
||||
|
||||
def unreadable(detail: str | None, refusal: str) -> Failure | None:
|
||||
"""A Failure opened with refusal where detail holds a `Touches:` list touch-predictions cannot read; checked here, before the plan's backend gets the detail, so a plan in Jira is held to it too. chunk-preflight reads the list first, and on such a list starts no chunk beside the item without saying why."""
|
||||
read = None if detail is None else predicted(detail)
|
||||
return Failure(f"{refusal}: {read.reason}") if isinstance(read, Failure) else None
|
||||
|
||||
|
||||
def list_(args: argparse.Namespace, plan: PlanStore) -> str | Failure:
|
||||
read = plan.read()
|
||||
if isinstance(read, Failure):
|
||||
@@ -220,7 +230,7 @@ def edit(args: argparse.Namespace, plan: PlanStore, text: str) -> str | Failure:
|
||||
detail = text if args.detail else "" if args.clear_detail else None
|
||||
if not fields(args) and detail is None:
|
||||
return Failure("not edited: no flag names a change; todo-item --help lists them")
|
||||
return reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
|
||||
return unreadable(detail, f"not edited: item {args.id}'s detail") or reported(plan.edit(args.id, fields(args), detail, args.comment), "not edited", lambda written: f"Edited item {written.id} in {plan.label}.")
|
||||
|
||||
|
||||
def finish(args: argparse.Namespace, plan: PlanStore, changelog: RecordStore | None) -> str | Failure:
|
||||
|
||||
@@ -25,6 +25,16 @@ CHANGELOG = "# Changelog\n\n## Unreleased\n\n- Older news.\n\n## 0.1.0\n\n- Firs
|
||||
# ## Details of the ranked fixture, without the trailing ## Notes.
|
||||
HEADER = "| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves |\n|---|---|---|---|---|---|---|---|---|---|---|\n"
|
||||
DETAILS = "## Details\n\n### 3. Make it fast, `a | b`.\n\nFast detail.\n\n### 1. Ship the later thing.\n\nLater detail.\n\n"
|
||||
# The bullets six items held on 2026-11-18, which touch-predictions cannot read: `(small)` after a bare path, and a part not in backticks.
|
||||
UNREADABLE_BULLETS = (
|
||||
"- `bin/judge_replay/main.py` (small)",
|
||||
"- `bin/do_epic/main.py` (small)",
|
||||
"- `principles/technical-principles.md`: the tests bullet group, `A valuable test checks behaviour` (small)",
|
||||
"- `README.md`: loop-claude's section (small)",
|
||||
"- `bin/rule_hook/rules.py`: the rule table (small)",
|
||||
"- `settings.json`: the PreToolUse matcher (small)",
|
||||
)
|
||||
READABLE_TOUCHES = "Why.\n\nTouches:\n\n- `bin/a.py`: `main`, `Plan.branch` (small)\n- `bin/run.sh`: lines 10-20\n- `docs/new.md`\n"
|
||||
|
||||
|
||||
class Terminal(io.StringIO):
|
||||
@@ -488,6 +498,37 @@ class Edit(TodoItem):
|
||||
self.assertEqual(self.todo.read_text(), before)
|
||||
|
||||
|
||||
class UnreadableTouches(TodoItem):
|
||||
"""A `Touches:` list touch-predictions cannot read is refused when written, since chunk-preflight would silently start no chunk beside the item."""
|
||||
|
||||
def test_add_and_edit_refuse_each_bullet_that_stalled_the_loop_and_write_nothing(self):
|
||||
for bullet in UNREADABLE_BULLETS:
|
||||
for argv, refusal in ((ADD, "not filed: "), (["edit", "3", "--detail"], "not edited: item 3's detail: ")):
|
||||
with self.subTest(bullet=bullet, command=argv[0]):
|
||||
before = self.todo.read_text()
|
||||
code, out, err = self.run_main(*argv, stdin=f"Why.\n\nTouches:\n\n- `bin/a.py`: `main`\n{bullet}\n")
|
||||
self.assertEqual((code, out), (1, ""))
|
||||
self.assertTrue(err.startswith(refusal), err)
|
||||
self.assertIn(repr(bullet), err)
|
||||
self.assertEqual(self.todo.read_text(), before)
|
||||
|
||||
def test_add_and_edit_take_a_readable_list_and_a_detail_without_one(self):
|
||||
for detail in (READABLE_TOUCHES, "Why, without a list.\n"):
|
||||
with self.subTest(detail):
|
||||
self.assertEqual(self.run_main(*ADD, stdin=detail)[0], 0)
|
||||
self.assertEqual(self.run_main("edit", "3", "--detail", stdin=detail)[0], 0)
|
||||
self.assertIn(detail, self.todo.read_text())
|
||||
|
||||
def test_a_plan_in_jira_gets_no_unreadable_list_either(self):
|
||||
self.config.write_text(self.config.read_text().replace('"checkout:todo.md"', f'"{JIRA_PLAN}"') + 'env-file = "~/acme.env"\n' + JIRA_SCORING)
|
||||
plan = MemoryPlan({3: {"Release": "0.1.0", "Item": "**Count the runs.**", "L": "1", "E": "2", "I": "3", "S": "1"}})
|
||||
self.enterContext(unittest.mock.patch.object(main, "plan_store", return_value=plan))
|
||||
detail = f"Touches:\n\n{UNREADABLE_BULLETS[0]}\n"
|
||||
self.assertEqual(self.run_main(*ADD, stdin=detail)[:2], (1, ""))
|
||||
self.assertEqual(self.run_main("edit", "3", "--detail", stdin=detail)[:2], (1, ""))
|
||||
self.assertEqual((list(plan.rows), plan.details), ([3], {}))
|
||||
|
||||
|
||||
class Move(TodoItem):
|
||||
def test_sets_the_items_release_and_keeps_the_rest(self):
|
||||
self.assertEqual(self.run_main("move", "3", "--release", "0.2.0"), (0, f"Moved item 3 to release 0.2.0 in {self.todo}.\n", ""))
|
||||
|
||||
+1
-1
@@ -30,4 +30,4 @@ paths:
|
||||
- **The Exempt cell keeps an item whatever its score:** `security` for a security finding, `defect` for a 🔴 finding or an item that restores a maintain goal the project breaks today, `question` for a question only the human can answer, which ranks first in its release, `decision` for an item `docs/decisions.md` cites, `owner` for an item the human told you to keep, and, where no other reason fits, `principle` for a 🟡 finding against a file in the config's principles folder, whose item's detail names that principle. Every item `docs/decisions.md` cites carries one of these reasons.
|
||||
- **A maintain goal vetoes an item that breaks it,** whatever the item scores: redesign the item so it holds the goal, or drop it.
|
||||
- **When you remove an item that no chunk built, title the commit `Drop item <ID>: <why>`,** or `Drop items 12, 14 and 15: <why>` for several. Such an item was deleted under the bar, vetoed, superseded or moot; a finished item is not one. Without the title, `score-outcomes` credits the item with the work of the chunk that removed it, where that chunk changed more than `todo.md`.
|
||||
- **Predict, in the detail of each item of the next release, what the item will touch.** When you plan the next release, or file or move an item into it, give the item's detail a `Touches:` line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. `~/.claude/bin/touch-predictions --help` shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part `(small)` where the item changes only a few lines of it. Leave out the plan and the project's records, which every chunk writes. `chunk-preflight` reads the predictions to name the items that may start chunks at once, and `touch-predictions record` keeps each beside what its chunk touched.
|
||||
- **Predict, in the detail of each item of the next release, what the item will touch.** When you plan the next release, or file or move an item into it, give the item's detail a `Touches:` line, then one bullet per file the item will change. Each bullet names the file, then the parts of it the item will change: a function, a class or a section heading, or line ranges where the file has none of these. A path alone means the whole file. Read the code first; a prediction from the item's text alone misses. `~/.claude/bin/touch-predictions --help` shows the spelling and how a part is named; a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. Mark a part `(small)` where the item changes only a few lines of it. `(small)` follows a part, never a bare path, and a part is a name in backticks or `lines <first>-<last>`. BANNED: ``- `bin/a.py` (small)``, ``- `README.md`: loop-claude's section (small)``. GOOD: ``- `bin/a.py`: `main` (small)``, ``- `README.md`: `## Loop` (small)``. `todo-item add`, `todo-item edit` and `rank_todo.py --check` refuse a list touch-predictions cannot read. Leave out the plan and the project's records, which every chunk writes. `chunk-preflight` reads the predictions to name the items that may start chunks at once, and `touch-predictions record` keeps each beside what its chunk touched.
|
||||
|
||||
Reference in New Issue
Block a user