Read and file an epic's child issues and sub-tasks through a plan backend interface, with a Jira backend and an in-memory fake #594

Merged
lilleman merged 8 commits from item-403 into main 2026-11-18 10:56:19 +01:00
12 changed files with 565 additions and 28 deletions
+4
View File
@@ -53,6 +53,10 @@
!bin/deploy-release
!bin/deploy_release/
!bin/deploy_release/*.py
!bin/do_epic/
!bin/do_epic/*.py
!bin/do_epic/backend/
!bin/do_epic/backend/*.py
!bin/failure.py
!bin/forge/
!bin/forge/*.py
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- Add do-epic's epic backend: one interface that reads a Jira epic's child issues and their sub-tasks, with labels, assignee, status and parent, and files new ones, met by a Jira backend and an in-memory fake that pass the same contract tests.
- Fix for an outside reviewer's comment on a PR now ends with a change to the setup that would have caught it, in claude-config first, then the principles and standards, then the project.
- larv-review reruns the pass that raised a 🟡 when the fix removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test. Other 🟡 fixes still rerun no pass.
- Add `markdown-section <file> <fragment>`, which prints the section of a markdown file under the heading the fragment picks, to the next heading of its level or a higher one. It fails, listing the headings, where several hold the fragment.
View File
View File
+88
View File
@@ -0,0 +1,88 @@
"""What every backend of an epic's plan must hold, as tests. A backend's test case inherits EpicStoreContract and unittest.TestCase, and builds an epic with no issues in new_store. Its assign and close change an issue as a person would in the tracker."""
import re
import typing
from do_epic.backend.protocol import EpicIssue, EpicStore
from failure import Failure
class EpicStoreContract:
assertEqual: typing.Callable[..., None]
assertIsInstance: typing.Callable[..., None]
subTest: typing.Callable[..., typing.ContextManager[None]]
def new_store(self) -> EpicStore:
raise NotImplementedError
def assign(self, store: EpicStore, key: str, name: str) -> None:
"""Assigns the issue named key to the person whose display name is name."""
raise NotImplementedError
def close(self, store: EpicStore, key: str, status: str) -> None:
"""Moves the issue named key to the done status named status."""
raise NotImplementedError
def filed(self, store: EpicStore, parent: str, summary: str, detail: str = "", labels: tuple[str, ...] = ()) -> str:
key = store.file(parent, summary, detail, labels)
assert isinstance(key, str), key
return key
def issues(self, store: EpicStore) -> list[EpicIssue]:
read = store.read()
assert isinstance(read, list), read
return read
def test_an_epic_with_no_issues_reads_empty(self) -> None:
self.assertEqual(self.new_store().read(), [])
def test_reads_back_a_child_issue_it_filed(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.", "Why it counts.\n\nA second paragraph.", ("security", "api"))
self.assertEqual(self.issues(store), [EpicIssue(key, "Count the runs.", "Why it counts.\n\nA second paragraph.", ("api", "security"), None, "To Do", False, store.epic_key)])
def test_reads_back_a_sub_task_it_filed_after_its_parent(self) -> None:
store = self.new_store()
first = self.filed(store, store.epic_key, "Count the runs.")
second = self.filed(store, store.epic_key, "Ship the later thing.")
task = self.filed(store, first, "Count them in the api.", labels=("api",))
read = self.issues(store)
self.assertEqual([(issue.key, issue.parent) for issue in read], [(first, store.epic_key), (task, first), (second, store.epic_key)])
self.assertEqual((read[1].summary, read[1].labels, read[1].detail), ("Count them in the api.", ("api",), ""))
def test_files_each_issue_under_its_own_key_in_the_epics_project(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
keys = [child, self.filed(store, store.epic_key, "Count the runs."), self.filed(store, child, "Count them in the api.")]
self.assertEqual(len(set(keys)), 3)
project = store.epic_key.rpartition("-")[0]
self.assertEqual([re.fullmatch(f"{project}-[1-9][0-9]*", key) is not None for key in keys], [True] * 3)
def test_reads_the_assignee_and_a_done_status(self) -> None:
store = self.new_store()
first = self.filed(store, store.epic_key, "Count the runs.")
second = self.filed(store, store.epic_key, "Ship the later thing.")
self.assign(store, first, "Ada Lovelace")
self.close(store, second, "Done")
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual((read[first].assignee, read[first].status, read[first].done), ("Ada Lovelace", "To Do", False))
self.assertEqual((read[second].assignee, read[second].status, read[second].done), (None, "Done", True))
def test_refuses_to_file_under_a_sub_task(self) -> None:
store = self.new_store()
child = self.filed(store, store.epic_key, "Count the runs.")
task = self.filed(store, child, "Count them in the api.")
self.assertEqual(store.file(task, "Count more.", "", ()), Failure(f"{task} is neither the epic {store.epic_key} nor one of its child issues, so nothing can be filed under it"))
self.assertEqual(len(self.issues(store)), 2)
def test_refuses_to_file_under_an_issue_outside_the_epic(self) -> None:
store = self.new_store()
for parent in ("ZZZ-1", "not a key"):
with self.subTest(parent=parent):
self.assertIsInstance(store.file(parent, "Count more.", "", ()), Failure)
self.assertEqual(self.issues(store), [])
def test_refuses_a_label_with_white_space_and_a_summary_of_two_lines(self) -> None:
store = self.new_store()
self.assertEqual(store.file(store.epic_key, "Count the runs.", "", ("two words",)), Failure("the label 'two words' is empty or holds white space"))
self.assertEqual(store.file(store.epic_key, "Count\nthe runs.", "", ()), Failure("the summary must be one line of text"))
self.assertEqual(self.issues(store), [])
+33
View File
@@ -0,0 +1,33 @@
"""An epic held in memory, for do-epic's tests, held to contract.py like every backend."""
import dataclasses
from do_epic.backend.protocol import EpicIssue, no_parent, unfit
from failure import Failure
@dataclasses.dataclass
class MemoryEpic:
"""An epic whose issues rank in the order filed. Where fails is set, every read and filing fails with it as the reason."""
epic_key: str
issues: list[EpicIssue] = dataclasses.field(default_factory=list)
fails: str | None = None
def read(self) -> list[EpicIssue] | Failure:
if self.fails:
return Failure(self.fails)
return [issue for child in self.issues if child.parent == self.epic_key for issue in (child, *(task for task in self.issues if task.parent == child.key))]
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
if self.fails:
return Failure(self.fails)
if refused := unfit(summary, labels):
return refused
if parent != self.epic_key and parent not in {issue.key for issue in self.issues if issue.parent == self.epic_key}:
return no_parent(self.epic_key, parent)
key = f"{self.epic_key.rpartition('-')[0]}-{len(self.issues) + 100}"
self.issues.append(EpicIssue(key, summary, detail.strip(), tuple(sorted(labels)), None, "To Do", False, parent))
return key
def change(self, key: str, **fields: object) -> None:
"""Changes the issue named key as a person would in the tracker, such as assignee="Ada Lovelace"."""
self.issues = [dataclasses.replace(issue, **fields) if issue.key == key else issue for issue in self.issues] # type: ignore[arg-type]
+148
View File
@@ -0,0 +1,148 @@
"""An epic's plan kept as a Jira Cloud epic's child issues and their sub-tasks, read and filed over Jira's REST API version 3."""
import dataclasses
import pathlib
import typing
from adf_codec.convert import adfs_to_markdown, markdown_to_adf, Refused
from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown
from project_config.settings import Epic
from do_epic.backend.protocol import EpicIssue, no_parent, unfit
from failure import Failure
from plan_store.jira_epic import ISSUE_KEY, ISSUE_TYPE, project_of, searched
FIELDS = ["summary", "description", "labels", "assignee", "status", "parent"]
# How many child issues one search for sub-tasks names, which keeps its JQL well inside the length Jira takes.
PARENTS_PER_SEARCH = 50
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under {parent} before filing it again"
@dataclasses.dataclass(frozen=True)
class Found:
"""An issue as Jira answered it, its description still in Jira's document format."""
issue: EpicIssue
description: dict[str, typing.Any] | None
@dataclasses.dataclass(frozen=True)
class JiraEpic:
"""The issues of a Jira epic, read and filed with the credentials env_file holds."""
epic: Epic
env_file: pathlib.Path
http: Http = jira_json
to_markdown: ToMarkdown = adfs_to_markdown
to_adf: ToAdf = markdown_to_adf
@property
def epic_key(self) -> str:
return self.epic.key
def read(self) -> list[EpicIssue] | Failure:
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
found = self.found(authorization)
if isinstance(found, Failure):
return found
# A container run converts every description at once. It comes after every other check, since a read that fails doesn't need it.
described = [each for each in found if each.description is not None]
texts = self.to_markdown([each.description for each in described if each.description is not None])
if isinstance(texts, Refused):
return Failure(f"{described[texts.index].issue.key}'s description: {texts.failure.reason}")
if isinstance(texts, Failure):
return Failure(f"cannot convert the descriptions of {self.epic_key}'s issues to markdown: {texts.reason}")
details = {each.issue.key: text.strip() for each, text in zip(described, texts)}
return [dataclasses.replace(each.issue, detail=details.get(each.issue.key, "")) for each in found]
def file(self, parent: str, summary: str, detail: str, labels: tuple[str, ...]) -> str | Failure:
authorization = basic_auth(self.env_file)
if isinstance(authorization, Failure):
return authorization
if refused := unfit(summary, labels) or self.not_a_parent(parent, authorization):
return refused
fields: dict[str, typing.Any] = {"project": {"key": project_of(parent)}, "parent": {"key": parent}, "summary": summary, "labels": list(labels)}
kind = {"name": ISSUE_TYPE} if parent == self.epic_key else self.sub_task_type(project_of(parent), authorization)
if isinstance(kind, Failure):
return kind
if detail.strip():
description = self.to_adf(detail)
if isinstance(description, Failure):
return Failure(f"cannot convert the detail to a Jira description: {description.reason}")
fields["description"] = description
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, {"fields": fields | {"issuetype": kind}})
if isinstance(created, Failure):
return Failure(f"cannot file the issue under {parent}: {created.reason}; {PERHAPS_FILED.format(parent=parent)}")
key = created.get("key") if isinstance(created, dict) else None
if not isinstance(key, str) or not ISSUE_KEY.fullmatch(key):
return Failure(f"Jira answered the new issue without an issue key; {PERHAPS_FILED.format(parent=parent)}")
return key
def not_a_parent(self, parent: str, authorization: str) -> Failure | None:
"""Why nothing can be filed under parent; None where it is the epic or one of its child issues."""
if parent == self.epic_key:
return None
if not ISSUE_KEY.fullmatch(parent):
return no_parent(self.epic_key, parent)
# A search may not show an issue filed a moment ago, so the parent is asked for by its key.
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{parent}?fields=parent", authorization, None)
if isinstance(answered, Failure):
return Failure(f"cannot read {parent} to file under it: {answered.reason}")
fields = answered.get("fields") if isinstance(answered, dict) else None
above = fields.get("parent") if isinstance(fields, dict) else None
return None if isinstance(above, dict) and above.get("key") == self.epic_key else no_parent(self.epic_key, parent)
def found(self, authorization: str) -> list[Found] | Failure:
"""Each child issue, each followed by its sub-tasks."""
# The search answers no issues for an epic the account cannot see; asking for the epic itself tells that from an epic without children.
seen = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{self.epic_key}?fields=summary", authorization, None)
if isinstance(seen, Failure):
return Failure(f"cannot read the epic {self.epic_key}: {seen.reason}")
children = self.searched(f"{self.epic_key}'s child issues", (self.epic_key,), authorization)
if isinstance(children, Failure):
return children
keys = [each.issue.key for each in children]
tasks: list[Found] = []
for start in range(0, len(keys), PARENTS_PER_SEARCH):
batch = self.searched(f"the sub-tasks of {self.epic_key}'s child issues", tuple(keys[start:start + PARENTS_PER_SEARCH]), authorization)
if isinstance(batch, Failure):
return batch
tasks += batch
return [each for child in children for each in (child, *(task for task in tasks if task.issue.parent == child.issue.key))]
def searched(self, what: str, parents: tuple[str, ...], authorization: str) -> list[Found] | Failure:
"""The issues whose parent is one of parents, in rank order."""
named = ", ".join(f'"{key}"' for key in parents)
answered = searched(self.epic.site, what, f"parent in ({named}) ORDER BY Rank ASC", {"fields": FIELDS}, authorization, self.http)
if isinstance(answered, Failure):
return answered
found = [found_of(raw) for raw in answered]
return next((each for each in found if isinstance(each, Failure)), None) or [each for each in found if isinstance(each, Found)]
def sub_task_type(self, project: str, authorization: str) -> dict[str, str] | Failure:
"""The project's sub-task issue type, by id, since sites name it differently, such as Subtask or Sub-task."""
answered = self.http("GET", f"{self.epic.site}/rest/api/3/issue/createmeta/{project}/issuetypes", authorization, None)
if isinstance(answered, Failure):
return Failure(f"cannot read {project}'s issue types: {answered.reason}")
types = answered.get("issueTypes") if isinstance(answered, dict) else None
if not isinstance(types, list):
return Failure(f"Jira answered {project}'s issue types in a shape its REST API version 3 doesn't document")
found = next((kind["id"] for kind in types if isinstance(kind, dict) and kind.get("subtask") is True and isinstance(kind.get("id"), str)), None)
return Failure(f"{project} has no sub-task issue type; turn sub-tasks on in Jira") if found is None else {"id": found}
def found_of(raw: object) -> Found | Failure:
"""The issue in one entry of a search's answer, or which issue is not in the shape Jira documents."""
key = raw.get("key") if isinstance(raw, dict) else None
if not isinstance(raw, dict) or not isinstance(key, str) or not ISSUE_KEY.fullmatch(key):
return Failure("the search answered an issue without an issue key")
# The answer's nested fields are read as Jira documents them; one missing or of another type ends the read here.
try:
fields = raw["fields"]
summary, labels, assignee, status, parent, description = fields["summary"], fields["labels"], fields["assignee"], fields["status"], fields["parent"]["key"], fields["description"]
name = assignee["displayName"] if assignee is not None else None
state, done = status["name"], status["statusCategory"]["key"] == "done"
except (AttributeError, KeyError, TypeError) as failure:
return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: {failure!r}")
texts = (summary, *labels, state, parent) if isinstance(labels, list) else ()
if not texts or not all(isinstance(text, str) for text in texts) or not isinstance(name, str | None) or not ISSUE_KEY.fullmatch(parent) or not isinstance(description, dict | None):
return Failure(f"{key} is not in the shape Jira Cloud's REST API version 3 documents: its summary, labels, assignee, status, parent or description holds another kind of value")
return Found(EpicIssue(key, summary.strip(), "", tuple(sorted(labels)), name, state, done, parent), description)
+58
View File
@@ -0,0 +1,58 @@
"""What every backend of an epic's plan reads and files: 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 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
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 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 unfit(summary: str, labels: tuple[str, ...]) -> Failure | None:
"""Why no tracker can file an issue with this summary and these labels; None where one can."""
if not summary.strip() or "\n" in summary:
return Failure("the summary must be one line of text")
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")
+30
View File
@@ -0,0 +1,30 @@
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
from do_epic.backend.contract import EpicStoreContract
from failure import Failure
from do_epic.backend.fake import MemoryEpic
class MemoryEpicContract(EpicStoreContract, unittest.TestCase):
def new_store(self) -> MemoryEpic:
return MemoryEpic("ABC-12")
def assign(self, store: MemoryEpic, key: str, name: str) -> None: # type: ignore[override]
store.change(key, assignee=name)
def close(self, store: MemoryEpic, key: str, status: str) -> None: # type: ignore[override]
store.change(key, status=status, done=True)
class Failing(unittest.TestCase):
def test_every_read_and_filing_fails_with_the_reason_given(self) -> None:
store = MemoryEpic("ABC-12", fails="Jira is down")
self.assertEqual((store.read(), store.file("ABC-12", "Count the runs.", "", ())), (Failure("Jira is down"), Failure("Jira is down")))
if __name__ == "__main__":
unittest.main()
+190
View File
@@ -0,0 +1,190 @@
import base64
import dataclasses
import pathlib
import re
import sys
import tempfile
import unittest
import unittest.mock
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
from project_config.settings import Epic
from do_epic.backend.contract import EpicStoreContract
from failure import Failure
from plan_store import jira_epic
from do_epic.backend.jira import JiraEpic
from adf_codec.convert import Refused
SITE = "https://acme.atlassian.net"
EPIC = Epic(SITE, "ABC-12")
AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode()
EPIC_URL = f"{SITE}/rest/api/3/issue/ABC-12?fields=summary"
ISSUE_TYPES = f"{SITE}/rest/api/3/issue/createmeta/ABC/issuetypes"
SEARCH = f"{SITE}/rest/api/3/search/jql"
ISSUES = f"{SITE}/rest/api/3/issue"
TO_DO = {"name": "To Do", "statusCategory": {"key": "new"}}
TYPES = {"issueTypes": [{"id": "10001", "name": "Task", "subtask": False}, {"id": "10003", "name": "Subtask", "subtask": True}]}
def to_adf(markdown: str) -> dict[str, object]:
"""Stands in for the adf-codec shim: one paragraph holding the markdown."""
return {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": markdown}]}]}
def to_markdown(documents: list[dict[str, object]]) -> list[str]:
return [document["content"][0]["content"][0]["text"] + "\n" for document in documents] # type: ignore[index]
@dataclasses.dataclass
class FakeJira:
"""Jira Cloud's REST API as JiraEpic calls it. It holds issues as Jira answers them, in rank order. A search answers two issues a page, with only the fields it asks for. A call whose method and URL are in answers gets the answer held there instead."""
issues: list[dict[str, object]] = dataclasses.field(default_factory=list)
answers: dict[tuple[str, str], object] = dataclasses.field(default_factory=dict)
calls: list[tuple[str, str]] = dataclasses.field(default_factory=list)
def __call__(self, method: str, url: str, authorization: str, body: object) -> object:
self.calls.append((method, url))
if authorization != AUTHORIZATION:
return Failure("Jira answered 401")
if (method, url) in self.answers:
return self.answers[method, url]
if method == "GET" and url == EPIC_URL:
return {"key": "ABC-12"}
if method == "GET" and url == ISSUE_TYPES:
return TYPES
if method == "POST" and url == SEARCH:
return self.page(body)
if method == "GET" and (held := next((issue for issue in self.issues if url == f"{ISSUES}/{issue['key']}?fields=parent"), None)):
return {"key": held["key"], "fields": {"parent": held["fields"]["parent"]}} # type: ignore[index]
if method == "POST" and url == ISSUES:
return self.created(body)
return Failure(f"Jira answered 404 for {method} {url}")
def page(self, body: object) -> object:
assert isinstance(body, dict)
matched = re.fullmatch(r'parent in \(("[A-Z]+-[0-9]+"(?:, "[A-Z]+-[0-9]+")*)\) ORDER BY Rank ASC', body["jql"])
if matched is None:
return Failure("Jira answered 400: the JQL is not valid")
parents = re.findall(r'"([A-Z]+-[0-9]+)"', matched[1])
found = [{"key": issue["key"], "fields": {name: value for name, value in issue["fields"].items() if name in body.get("fields", [])}} for issue in self.issues if issue["fields"]["parent"]["key"] in parents] # type: ignore[index, attr-defined]
start = int(body.get("nextPageToken", 0))
return {"issues": found[start:start + 2]} | ({"nextPageToken": str(start + 2)} if start + 2 < len(found) else {})
def created(self, body: object) -> object:
assert isinstance(body, dict)
fields = body["fields"]
parent = fields["parent"]["key"]
kind = {"name": "Task"} if parent == "ABC-12" else {"id": "10003"} if any(issue["key"] == parent for issue in self.issues) else None
if fields["project"] != {"key": "ABC"} or kind is None or fields["issuetype"] != kind:
return Failure("Jira answered 400: the project, parent or issue type is not valid")
key = f"ABC-{len(self.issues) + 100}"
self.issues.append({"key": key, "fields": {"summary": fields["summary"], "description": fields.get("description"), "labels": fields["labels"], "assignee": None, "status": TO_DO, "parent": {"key": parent}}})
return {"id": "1", "key": key}
def change(self, key: str, **fields: object) -> None:
next(issue for issue in self.issues if issue["key"] == key)["fields"].update(fields) # type: ignore[union-attr]
class Case(unittest.TestCase):
def setUp(self) -> None:
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
self.env_file = pathlib.Path(folder.name) / "jira.env"
self.env_file.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
self.env_file.chmod(0o600)
self.jira = FakeJira()
def new_store(self) -> JiraEpic:
return JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf)
class JiraEpicContract(Case, EpicStoreContract):
def assign(self, store: JiraEpic, key: str, name: str) -> None: # type: ignore[override]
self.jira.change(key, assignee={"accountId": "5b10a2844c20165700ede21g", "displayName": name})
def close(self, store: JiraEpic, key: str, status: str) -> None: # type: ignore[override]
self.jira.change(key, status={"name": status, "statusCategory": {"key": "done"}})
class Jira(Case):
def test_reads_the_sub_tasks_of_more_children_than_one_search_names(self) -> None:
store = self.new_store()
children = [store.file("ABC-12", f"Item {n}.", "", ()) for n in range(60)]
tasks = [store.file(child, "A task.", "", ()) for child in children]
read = store.read()
assert isinstance(read, list), read
self.assertEqual([issue.key for issue in read], [key for pair in zip(children, tasks) for key in pair])
def test_files_a_child_without_asking_for_issue_types(self) -> None:
self.new_store().file("ABC-12", "Count the runs.", "", ())
self.assertNotIn(("GET", ISSUE_TYPES), self.jira.calls)
def test_a_filing_jira_fails_or_answers_without_a_key_says_the_issue_may_exist(self) -> None:
for answer, reason in ((Failure("Jira answered 503"), "cannot file the issue under ABC-12: Jira answered 503"), ({"id": "1"}, "Jira answered the new issue without an issue key"), (["ABC-100"], "Jira answered the new issue without an issue key")):
with self.subTest(answer=answer):
self.jira.answers[("POST", ISSUES)] = answer
self.assertEqual(self.new_store().file("ABC-12", "Count the runs.", "", ()), Failure(f"{reason}; unless Jira refused the request, the issue may exist: look under ABC-12 before filing it again"))
def test_a_detail_the_codec_refuses_leaves_the_epic_as_it_was(self) -> None:
store = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, lambda markdown: Failure("adf-codec refused it"))
self.assertEqual(store.file("ABC-12", "Count the runs.", "Why.", ()), Failure("cannot convert the detail to a Jira description: adf-codec refused it"))
self.assertEqual(self.jira.issues, [])
def test_files_no_sub_task_where_the_project_has_no_sub_task_type_or_its_types_cannot_be_read(self) -> None:
store = self.new_store()
child = store.file("ABC-12", "Count the runs.", "", ())
for answer, reason in ((Failure("Jira answered 403"), "cannot read ABC's issue types: Jira answered 403"), ({"issueTypes": [{"id": "10001", "subtask": False}]}, "ABC has no sub-task issue type; turn sub-tasks on in Jira"), ({}, "Jira answered ABC's issue types in a shape its REST API version 3 doesn't document"), ([], "Jira answered ABC's issue types in a shape its REST API version 3 doesn't document")):
with self.subTest(answer=answer):
self.jira.answers[("GET", ISSUE_TYPES)] = answer
self.assertEqual(store.file(str(child), "A task.", "", ()), Failure(reason))
self.assertEqual(len(self.jira.issues), 1)
def test_an_issue_in_another_shape_fails_the_read(self) -> None:
valid = {"summary": "Count the runs.", "description": None, "labels": [], "assignee": None, "status": TO_DO, "parent": {"key": "ABC-12"}}
shape = "ABC-34 is not in the shape Jira Cloud's REST API version 3 documents"
for raw, reason in (
("ABC-34", "the search answered an issue without an issue key"),
({"fields": valid}, "the search answered an issue without an issue key"),
({"key": "abc-34", "fields": valid}, "the search answered an issue without an issue key"),
({"key": "ABC-34", "fields": {"summary": "Count the runs.", "parent": {"key": "ABC-12"}}}, shape + ": KeyError('labels')"),
*((({"key": "ABC-34", "fields": valid | changed}, shape + ": its summary, labels, assignee, status, parent or description holds another kind of value") for changed in (
{"summary": 3}, {"labels": "api"}, {"labels": [3]}, {"assignee": {"displayName": 0}}, {"status": {"name": 0, "statusCategory": {"key": "new"}}}, {"parent": {"key": "ABC"}}, {"parent": {"key": 12}}, {"description": "text"},
))),
):
with self.subTest(raw=raw):
self.jira.answers[("POST", SEARCH)] = {"issues": [raw]}
self.assertEqual(self.new_store().read(), Failure(reason))
def test_a_description_the_codec_cannot_convert_fails_the_read(self) -> None:
self.new_store().file("ABC-12", "Count the runs.", "Why.", ())
for converted, reason in ((Refused(0, Failure("a table cell holds a list")), "ABC-100's description: a table cell holds a list"), (Failure("docker is not running"), "cannot convert the descriptions of ABC-12's issues to markdown: docker is not running")):
with self.subTest(converted=converted):
self.assertEqual(JiraEpic(EPIC, self.env_file, self.jira, lambda documents: converted, to_adf).read(), Failure(reason))
def test_a_search_that_does_not_end_names_the_issues_it_sought(self) -> None:
store = self.new_store()
children = [store.file("ABC-12", "Count the runs.", "", ()) for _ in range(2)]
for _ in range(3):
store.file(str(children[0]), "A task.", "", ())
with unittest.mock.patch.object(jira_epic, "MAX_PAGES", 1):
self.assertEqual(store.read(), Failure("the search for the sub-tasks of ABC-12's child issues did not end within 1 pages"))
store.file("ABC-12", "Count the runs.", "", ())
self.assertEqual(store.read(), Failure("the search for ABC-12's child issues did not end within 1 pages"))
def test_refuses_to_file_under_another_epics_child_or_an_issue_it_cannot_read(self) -> None:
self.jira.issues.append({"key": "ABC-5", "fields": {"parent": {"key": "ABC-1"}}})
store = self.new_store()
self.assertEqual(store.file("ABC-5", "Count more.", "", ()), Failure("ABC-5 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it"))
self.assertEqual(store.file("ABC-77", "Count more.", "", ()), Failure(f"cannot read ABC-77 to file under it: Jira answered 404 for GET {ISSUES}/ABC-77?fields=parent"))
self.jira.answers[("GET", f"{ISSUES}/ABC-78?fields=parent")] = ["ABC-12"]
self.assertEqual(store.file("ABC-78", "Count more.", "", ()), Failure("ABC-78 is neither the epic ABC-12 nor one of its child issues, so nothing can be filed under it"))
self.assertEqual([call for call in self.jira.calls if call[0] == "POST" and call[1] == ISSUES], [])
def test_an_epic_the_account_cannot_see_fails_the_read(self) -> None:
store = JiraEpic(Epic(SITE, "ABC-99"), self.env_file, self.jira, to_markdown, to_adf)
self.assertEqual(store.read(), Failure(f"cannot read the epic ABC-99: Jira answered 404 for GET {SITE}/rest/api/3/issue/ABC-99?fields=summary"))
if __name__ == "__main__":
unittest.main()
+8 -8
View File
@@ -448,15 +448,15 @@ def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failu
seen = http("GET", f"{epic.site}/rest/api/3/issue/{epic.key}?fields=summary", authorization, None)
if isinstance(seen, Failure):
return Failure(f"cannot read the epic {epic.key}: {seen.reason}")
body: dict[str, object] = {
"jql": f'parent = "{epic.key}" AND statusCategory != Done ORDER BY Rank ASC',
"fields": ["summary", "description", "fixVersions", "issuelinks"],
"properties": [PROPERTY],
"maxResults": PAGE,
}
return searched(epic.site, f"{epic.key}'s children", f'parent = "{epic.key}" AND statusCategory != Done ORDER BY Rank ASC', {"fields": ["summary", "description", "fixVersions", "issuelinks"], "properties": [PROPERTY]}, authorization, http)
def searched(site: str, what: str, jql: str, asked: dict[str, object], authorization: str, http: Http) -> list[object] | Failure:
"""Every issue a JQL search on site finds, page by page. The dict asked holds the request's `fields` and `properties` lists. The text what names the issues sought, in the Failure of a search that doesn't end."""
body: dict[str, object] = {"jql": jql, "maxResults": PAGE} | asked
found: list[object] = []
for _ in range(MAX_PAGES):
page = http("POST", f"{epic.site}/rest/api/3/search/jql", authorization, body)
page = http("POST", f"{site}/rest/api/3/search/jql", authorization, body)
if isinstance(page, Failure):
return page
if not isinstance(page, dict) or not isinstance(page.get("issues"), list):
@@ -465,7 +465,7 @@ def children(epic: Epic, authorization: str, http: Http) -> list[object] | Failu
if not page.get("nextPageToken"):
return found
body = body | {"nextPageToken": page["nextPageToken"]}
return Failure(f"the search for {epic.key}'s children did not end within {MAX_PAGES} pages")
return Failure(f"the search for {what} did not end within {MAX_PAGES} pages")
def issue_of(raw: object) -> Issue | Failure:
+5 -20
View File
@@ -15,20 +15,19 @@
| 404 | 0.12.0 | | | **Read do-epic's machine-wide settings from `~/.claude-projects/do-epic/config.toml` and its prose repo rule from `repo-rule.md` beside it, and refuse to start while either is missing or misspelt.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 407 | 0.12.0 | 404 | | **Find an epic repo's checkout and project config by the repo's name, clone a missing one from the host of the epic's other repos, and ask the human where unsure.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 401 | 0.12.0 | | | **Move loop-claude's cycle, judge, interrupt, tmux and routing into a package a second entry point drives, with loop-claude's behaviour unchanged.** | 3 | 2 | 3 | 6 | 6 | 1 by 3, code health by 2 | 1.8 |
| 403 | 0.12.0 | | | **Read and file an epic's child issues and sub-tasks, with labels, assignee, status and parent, through a plan backend interface with a Jira backend and an in-memory fake.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 406 | 0.12.0 | 403, 404 | | **Pick each epic item's repo, or for an item without one whether it is Claude's work or a human task, by `repo-rule.md`, record the pick on the issue, and ask the human where the rule leaves it unclear.** | 2 | 2 | 2 | 4 | 4 | 1 by 5 | 1.6 |
| 406 | 0.12.0 | 404 | | **Pick each epic item's repo, or for an item without one whether it is Claude's work or a human task, by `repo-rule.md`, record the pick on the issue, and ask the human where the rule leaves it unclear.** | 2 | 2 | 2 | 4 | 4 | 1 by 5 | 1.6 |
| 402 | 0.12.0 | | | **Read and write a Jira epic's description as sections, Goals, Audience, Scoring, Decisions and a language line, and write Goals or Audience only after the human approves.** | 2 | 2 | 3 | 5 | 4 | 1 by 5 | 1.6 |
| 408 | 0.12.0 | 402, 403 | | **Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.** | 3 | 2 | 2 | 5 | 4 | 1 by 5 | 1.6 |
| 410 | 0.12.0 | 401, 403, 404, 406, 407, 408 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 408 | 0.12.0 | 402 | | **Rank an epic's items by one weight chain, the epic's achieve goals, then code health, then the item's repo goals, then by Blocked by, and re-rank Jira's backlog to match, with people's issues keeping their rank.** | 3 | 2 | 2 | 5 | 4 | 1 by 5 | 1.6 |
| 410 | 0.12.0 | 401, 404, 406, 407, 408 | | **Run `do-epic <EPIC-KEY>`: one tmux session per epic, a window per chunk, up to the epic's cap of running chunks and each repo's `parallel-chunks`, and never in a repo a loop-claude is running chunks in.** | 3 | 2 | 3 | 6 | 6 | 1 by 5 | 0.8 |
| 416 | 0.12.0 | 410 | | **Finish an epic's repo item with a bullet under its repo's `CHANGELOG.md` → `## Unreleased`, or with none where the repo's plan is in Jira.** | 1 | 1 | 1 | 1 | 2 | 1 by 5 | 2.1 |
| 413 | 0.12.0 | 402, 410 | | **File a finding about an epic goal in the epic and one about a repo goal by that repo's rules, ask the human where unsure which, and give the judge the epic's records beside the repo's.** | 3 | 2 | 3 | 6 | 4 | 1 by 5 | 1.6 |
| 415 | 0.12.0 | 402, 410, 413 | | **Finish an epic: run release-review passes on each repo it changed, work what they file, have the human confirm each goal, post a summary comment, and close the epic in Jira last.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 418 | 0.12.0 | 415 | | **Describe do-epic in `README.md`'s tools and setup, with its machine settings and `repo-rule.md`.** | 1 | 2 | 1 | 2 | 2 | 1 by 5 | 2.1 |
| 400 | 0.12.0 | | | **Forbid a test that decides at run time whether to check anything in `principles/technical-principles.md`, and point stability-reviewer's Tests checks at it.** | 1 | 2 | 3 | 4 | 2 | 1.1 by 5 | 2.0 |
| 409 | 0.12.0 | 403, 406 | | **Split an epic item that changes several repos into one Jira sub-task per repo, each labelled for its repo, with the parent tracking the whole change, when do-epic plans the item.** | 2 | 2 | 3 | 5 | 3 | 1 by 5 | 1.9 |
| 409 | 0.12.0 | 406 | | **Split an epic item that changes several repos into one Jira sub-task per repo, each labelled for its repo, with the parent tracking the whole change, when do-epic plans the item.** | 2 | 2 | 3 | 5 | 3 | 1 by 5 | 1.9 |
| 411 | 0.12.0 | 410 | | **Park a chunk whose PR waits on a long gate, keeping its worktree, PR and session in a state file that survives a reboot, and resume its session when the gate passes or a reviewer comments.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
| 412 | 0.12.0 | 410, 411 | | **Print each chunk of an epic, running, parked with its gate and since when, or stopped, each human task and each open interrupt with `do-epic <key> --status`, and name a parked chunk's gate in its tmux window's name.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | 403, 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 414 | 0.12.0 | 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
| 299 | 0.12.0 | | | **Replay the archived judge verdicts through code rules and a classifier trained locally on the archive, and file an item for each verdict kind one of them decides with no missed interrupt.** | 2 | 2 | 2 | 4 | 3 | 1.4 by 3 | 1.0 |
| 311 | 0.12.0 | | | **Hand each worker's claude a Bash output ceiling that saves longer output to a file, and refuse a Read of a session transcript under `~/.claude/projects`.** | 2 | 2 | 3 | 5 | 3 | 1.4 by 3 | 1.0 |
@@ -130,20 +129,6 @@ Touches:
- `bin/rung_replay/search.py` (small)
- `README.md`: `` ### Packages under `bin/` `` (small)
### 403. Read and file an epic's child issues and sub-tasks, with labels, assignee, status and parent, through a plan backend interface with a Jira backend and an in-memory fake.
Other backends come later (`docs/decisions.md` → `do-epic: drives one Jira epic …`), so do-epic reads the epic only through the interface. The fake passes the same contract tests as the Jira backend. Sub-task creation is a new POST.
Touches:
- `bin/plan_store/jira_epic.py`: `Issue`, `issue_of`, `children`, `JiraPlan.read`, `JiraPlan.add`, `JiraPlan.edit`
- `bin/plan_store/plans.py`: `PlanStore`
- `bin/plan_store/fakes.py`: `MemoryPlan`
- `bin/plan_store/contract.py`: `PlanStoreContract`
- `bin/do_epic/backend/protocol.py`
- `bin/do_epic/backend/jira.py`
- `bin/do_epic/backend/fake.py`
### 406. Pick each epic item's repo, or for an item without one whether it is Claude's work or a human task, by `repo-rule.md`, record the pick on the issue, and ask the human where the rule leaves it unclear.
The pick is a headless claude call with a JSON schema, as the judge makes (`docs/decisions.md` → `do-epic: drives one Jira epic …`). A recorded pick is read back without a new call.