Files
claude-config/bin/todo_item/main.py
T

150 lines
6.6 KiB
Python

"""File an item in todo.md or finish one, ranking the file as rank_todo.py does, or show one.
usage: todo-item add --release <version> --l <L> --e <E> --i <I> --s <S> [--moves <moves>]
[--blocked-by <IDs>] [--exempt <reason>] <tagline> [<<'EOF' detail EOF]
todo-item finish <ID> [--changelog <bullet> | --no-changelog]
todo-item show <ID>
All three work on the todo.md in the current folder. add and finish also use the CHANGELOG.md beside it,
and read the docs/decisions.md beside it and the goals file that todo.md's project config names.
The cells take the format rank_todo.py --help states; the letter flags take upper case too, as --L.
add takes Next ID as the item's ID and raises Next ID by one. It writes the row, with the tagline
in bold and each | in it escaped, and the detail it reads from stdin, if any, under ## Details.
The detail may hold no ## or ### heading.
It prints `Filed item <ID>.` It doesn't write anything where ranking fails or scores the item under the bar.
finish removes the item's row and its detail. With --changelog it adds the bullet first under
CHANGELOG.md's ## Unreleased, or a ## heading that says unreleased, creating the section, or the
file, where missing. It refuses where that section holds ### subsections: add the bullet by hand.
Where CHANGELOG.md exists, finish needs --changelog or --no-changelog, so no bullet is left out by
mistake. It prints `Finished item <ID>.` It doesn't write anything while docs/decisions.md cites the item.
show reads only todo.md. It prints the items table's header and divider, item <ID>'s row, and its detail
from its ### heading to the next item's, sub-headings included. It fails, saying so, where todo.md has
no row for <ID>.
Exit 2 on bad arguments, and 1, saying why, on any other failure. A message opening `not filed:`
or `not finished:` means it didn't write anything.
"""
import argparse
import pathlib
import sys
import typing
from todo_item.edits import added, finished, shown, with_bullet
from release_plan.todo_table import BLOCKED_BY, MOVES
from failure import Failure
from release_plan import plan_file, ranking
# Each score flag, as --l or --L, and the column it fills.
LETTERS = ("L", "E", "I", "S")
def main(argv: list[str], folder: pathlib.Path = pathlib.Path(), stdin: typing.TextIO = sys.stdin) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
args = parser().parse_args(argv)
if args.command == "show":
done = show(args, folder)
else:
done = add(args, folder, stdin) if args.command == "add" else finish(args, folder)
if isinstance(done, Failure):
print(done.reason, file=sys.stderr)
return 1
print(done)
return 0
def parser() -> argparse.ArgumentParser:
parsed = argparse.ArgumentParser(prog="todo-item")
commands = parsed.add_subparsers(dest="command", required=True)
adding = commands.add_parser("add")
adding.add_argument("--release", required=True)
for letter in LETTERS:
adding.add_argument(f"--{letter.lower()}", f"--{letter}", dest=letter, required=True)
adding.add_argument("--moves", default="")
adding.add_argument("--blocked-by", default="")
adding.add_argument("--exempt", default="")
adding.add_argument("tagline")
finishing = commands.add_parser("finish")
finishing.add_argument("id", type=int)
bullet = finishing.add_mutually_exclusive_group()
bullet.add_argument("--changelog")
bullet.add_argument("--no-changelog", action="store_true")
showing = commands.add_parser("show")
showing.add_argument("id", type=int)
return parsed
def show(args: argparse.Namespace, folder: pathlib.Path) -> str | Failure:
todo = folder / "todo.md"
try:
return shown(todo.read_text(encoding="utf-8"), args.id)
except OSError as failure:
return Failure(f"{todo}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{todo}: not UTF-8")
def add(args: argparse.Namespace, folder: pathlib.Path, stdin: typing.TextIO) -> str | Failure:
todo = folder / "todo.md"
texts = plan_file.read_all(todo)
if isinstance(texts, Failure):
return texts
named = {"Release": args.release, BLOCKED_BY: args.blocked_by, "Exempt": args.exempt, "Item": args.tagline, MOVES: args.moves}
# Claude Code's Bash tool gives a command /dev/null as stdin (readlink /proc/self/fd/0 shows it), so without a heredoc read() returns "" at once.
filed = added(texts[0], named | {letter: getattr(args, letter) for letter in LETTERS}, "" if stdin.isatty() else stdin.read())
if isinstance(filed, Failure):
return Failure(f"not filed: {filed.reason}")
id_, text = filed
ranked = ranking.rank(text, *texts[1:])
if isinstance(ranked, Failure):
return Failure(f"not filed: {ranked.reason}")
if under := [line for line in ranked.under_bar if line.startswith(f"item {id_} ")]:
return Failure(f"not filed: {under[0]}")
if unwritten := plan_file.write(todo, ranked.text):
return unwritten
plan_file.print_report(todo, ranked)
return f"Filed item {id_}."
def finish(args: argparse.Namespace, folder: pathlib.Path) -> str | Failure:
todo, changelog = folder / "todo.md", folder / "CHANGELOG.md"
texts = finish_texts(args, todo, changelog)
if isinstance(texts, Failure):
return Failure(f"not finished: {texts.reason}")
ranked, news = texts
if unwritten := plan_file.write(todo, ranked.text):
return Failure(f"not finished: {unwritten.reason}")
if news is not None and (unwritten := plan_file.write(changelog, news)):
return Failure(f"{unwritten.reason}; todo.md no longer holds item {args.id}, so add its bullet by hand")
plan_file.print_report(todo, ranked)
return f"Finished item {args.id}."
def finish_texts(args: argparse.Namespace, todo: pathlib.Path, changelog: pathlib.Path) -> tuple[ranking.Ranked, str | None] | Failure:
"""What finish writes: todo ranked without item args.id, and changelog's new text, None where finish leaves it as is."""
if changelog.exists() and args.changelog is None and not args.no_changelog:
return Failure("CHANGELOG.md exists beside todo.md; pass --changelog <bullet>, or --no-changelog where the repo doesn't publish anything")
texts = plan_file.read_all(todo)
if isinstance(texts, Failure):
return texts
text = finished(texts[0], args.id)
if isinstance(text, Failure):
return text
ranked = ranking.rank(text, *texts[1:])
if isinstance(ranked, Failure):
return ranked
if args.changelog is None:
return ranked, None
try:
news = with_bullet(changelog.read_text(encoding="utf-8") if changelog.exists() else "", args.changelog)
except OSError as failure:
return Failure(f"{changelog}: {failure.strerror}")
except UnicodeDecodeError:
return Failure(f"{changelog}: not UTF-8")
return news if isinstance(news, Failure) else (ranked, news)