104 lines
5.7 KiB
Python
104 lines
5.7 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, Moves
|
|
from failure import Failure
|
|
|
|
# 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, ...]) -> 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."""
|
|
|
|
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 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_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_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")
|