Files
claude-config/bin/do_epic/backend/protocol.py
T

131 lines
9.2 KiB
Python

"""What every backend of an epic's plan reads, files, labels, comments on and ranks: an EpicIssue, and the EpicStore protocol they all meet. do-epic reads an epic only through EpicStore, so another tracker can stand behind it; contract.py holds the tests every backend passes.
EpicStore is not plan_store's PlanStore. A PlanStore item names a release, but an epic item has none (`docs/decisions.md` → `do-epic: drives one Jira epic …`), and it may be a sub-task."""
import dataclasses
import re
import typing
from plan.todo_table import Exempt, item_fields, ItemFields, Moves, MOVES
from failure import Failure
from plan_store.jira_epic import SET_SCORES
# What a tracker accepts as a label: Jira refuses a label holding white space.
LABEL = re.compile(r"\S+")
@dataclasses.dataclass(frozen=True)
class EpicIssue:
"""One of an epic's child issues, or a sub-task of one, as a read found it."""
key: str
summary: str
# The description, as markdown; empty where the issue has none.
detail: str
# Sorted by name.
labels: tuple[str, ...]
# The assignee's display name; None where nobody is assigned.
assignee: str | None
# The status's name, such as "In Progress".
status: str
# Whether the status is one the tracker counts as done.
done: bool
# The epic's key for a child issue, the child's key for a sub-task.
parent: str
# The score of each column the issue has one for, such as {"L": 2}, as `plan_store` reads them from the issue's `plan-item` property. Empty where the issue has no scores.
scores: dict[str, int] = dataclasses.field(default_factory=dict)
# The goals the issue moves, and how far (the plan's Moves cell); empty where it names none.
moves: Moves = ()
# Why the issue is exempt from the plan's score bar, as the plan's Exempt cell names it; empty where it isn't.
exempt: Exempt = ""
# The key of each issue that blocks this one, in the tracker's order.
blockers: tuple[str, ...] = ()
# True where the loop filed the issue through EpicStore.file; False for an issue a person filed.
by_loop: bool = False
class EpicStore(typing.Protocol):
"""The issues of one epic. A write that fails doesn't file anything, except where its Failure says the tracker may have taken it all the same."""
@property
def epic_key(self) -> str:
"""The parent of each child issue."""
def read(self) -> list[EpicIssue] | Failure:
"""Each child issue, open or done, in the tracker's rank order, each followed by its sub-tasks in theirs."""
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...], blocked_by: str | None = None) -> str | Failure:
"""Files an open issue under parent, marked as filed by the loop, and answers its key: a child issue where parent is the epic, a sub-task where parent is one of its child issues. detail is markdown, and may be empty. Where blocked_by names an issue, a child issue of the epic or a sub-task of one, the new issue is blocked by it; any other issue is refused before anything is filed."""
def add_label(self, key: str, label: str) -> None | Failure:
"""Adds label to the epic's child issue named key, leaving its other labels as they are; adding one it already has leaves the labels as they are. A sub-task, or an issue outside the epic, is refused."""
def rank(self, key: str, before: str) -> None | Failure:
"""Ranks the child issue named key just before the child issue named before. The sub-tasks of key follow key. Pass only keys of the epic's child issues, as read answers them: some backends don't check, and Jira ranks any issue it is given."""
def comment(self, key: str, text: str) -> None | Failure:
"""Posts text, markdown, as a comment on the epic's child issue named key, for the people who work the epic to read. A sub-task, an issue outside the epic, or an empty or blank text is refused."""
def set_scores(self, key: str, scores: dict[str, int], moves: str, comment: str) -> None | Failure:
"""Posts comment, markdown, on the epic's child issue named key, or on a sub-task of one, then sets its scores. The comment tells the team the scores, since a tracker's screens may not show them. scores holds each of L, E, I and S, and moves is the plan's Moves cell, which may be empty. An issue that holds a score keeps what it holds and is refused, as are an issue outside the epic and a blank comment. Where the scores cannot be set after the comment is posted, the Failure says so."""
def start_issue(self, key: str) -> str | None | Failure:
"""Shows the team that the epic's child issue named key, or a sub-task of one, is being worked. It assigns an issue nobody holds to the account the store works as. An issue someone else holds stays theirs, and the answer is their display name; otherwise the answer is None. Where the backend's settings say so, it also moves an issue whose work hasn't started, and adds every starting issue to a sprint, whoever holds it. An issue outside the epic is refused. A Failure names each step that could not be made, and anyone else who holds the issue; the steps the tracker took stay taken."""
def move_issue(self, key: str, status: str) -> None | Failure:
"""Moves the epic's child issue named key, or a sub-task of one, to the status named status, in upper or lower case; one already there stays as it is. An issue outside the epic is refused. A Failure says why the move could not be made, such as a workflow that gives no way from the issue's status to that one."""
def move_issue_by(self, key: str, transition: str, to: tuple[str, ...]) -> str | Failure:
"""Moves the epic's child issue named key, or a sub-task of one, by the workflow transition named transition, where that transition leads to one of the statuses to. Names match in upper or lower case. An issue already at one of those statuses stays as it is. Answers the name of the status the issue has afterwards. An issue outside the epic is refused. A Failure says why the move was not made, such as a workflow that offers the issue no transition of that name from its status, or a transition that leads to another status."""
def finish_issue(self, key: str) -> None | Failure:
"""Moves the epic's child issue named key, or a sub-task of one, to a done status, so that read answers it as done; one already done stays as it is. An issue outside the epic is refused. A Failure says why the move could not be made: the issue's workflow gives no way to a done status, gives several the backend cannot choose between, or refuses the move."""
def closed(self) -> bool | Failure:
"""Whether the epic itself is in a status the tracker counts as done."""
def close(self, summary: str) -> None | Failure:
"""Posts summary, markdown, as a comment on the epic, then moves the epic to a status the tracker counts as done. Before anything is posted, it refuses a blank summary, and an epic the tracker cannot move to such a status. Where the move fails after the comment is posted, the Failure says so."""
def unfit(summary: str, labels: tuple[str, ...]) -> Failure | None:
"""Why no tracker can file an issue with this summary and these labels; None where a tracker can file it."""
if not summary.strip() or "\n" in summary:
return Failure("the summary must be one line of text")
return unfit_label(*labels)
def unfit_label(*labels: str) -> Failure | None:
"""Why no tracker can take one of these labels; None where a tracker can take every one."""
if bad := next((label for label in labels if not LABEL.fullmatch(label)), None):
return Failure(f"the label {bad!r} is empty or holds white space")
return None
def no_parent(epic_key: str, parent: str) -> Failure:
"""What every backend says when asked to file under parent, which is neither the epic nor one of its child issues."""
return Failure(f"{parent} is neither the epic {epic_key} nor one of its child issues, so nothing can be filed under it")
def no_blocker(epic_key: str, blocker: str) -> Failure:
"""What every backend says when asked to file an issue blocked by blocker, which is neither a child issue of the epic nor a sub-task of one."""
return Failure(f"{blocker} is neither a child issue of the epic {epic_key} nor a sub-task of one, so it cannot block a new issue")
def no_child(epic_key: str, key: str, done_to_it: str) -> Failure:
"""What every backend says when asked to change key, which is not one of the epic's child issues; done_to_it is the past participle of what was asked, such as "labelled"."""
return Failure(f"{key} is not one of the child issues of the epic {epic_key}, so it cannot be {done_to_it}")
def no_scores(key: str, scores: dict[str, int], moves: str, held: dict[str, int]) -> ItemFields | Failure:
"""The scores and Moves to set on the issue named key, each held to the plan's format, or why no tracker sets them; held are the scores the issue has."""
if held:
return Failure(f"{key} holds scores already, which stay as they are")
if sorted(scores) != sorted(SET_SCORES):
return Failure(f"{key} is given {', '.join(scores) or 'no score'}: set each of {', '.join(SET_SCORES[:-1])} and {SET_SCORES[-1]}, and nothing else")
return item_fields({name: str(value) for name, value in scores.items()} | {MOVES: moves}, f"item {key}")
def no_words(text: str) -> Failure | None:
"""Why no tracker can post this comment; None where one can."""
return None if text.strip() else Failure("the comment must hold some text")