150 lines
6.6 KiB
Python
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)
|
|
|