Read each epic issue's scores, blockers and whether the loop filed it, from both backends
CI / tests (pull_request) Successful in 2m41s

This commit is contained in:
2026-11-18 17:16:37 +01:00
parent 5e75655771
commit 2c1a84518f
8 changed files with 136 additions and 18 deletions
+45 -2
View File
@@ -1,9 +1,10 @@
"""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."""
"""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, close, person_files, score and block change the tracker as a person, or the plan store, would."""
import re
import typing
from do_epic.backend.protocol import EpicIssue, EpicStore
from failure import Failure
from plan.todo_table import ItemFields
class EpicStoreContract:
@@ -22,6 +23,18 @@ class EpicStoreContract:
"""Moves the issue named key to the done status named status."""
raise NotImplementedError
def person_files(self, store: EpicStore, summary: str) -> str:
"""Files a child issue of the epic as a person does in the tracker, not through the store, and answers its key."""
raise NotImplementedError
def score(self, store: EpicStore, key: str, scores: dict[str, str]) -> None:
"""Sets the scores of the issue named key, as `plan_store` writes them: each column's name with its value as text, such as {"L": "2", "Moves": "1 by 5"}."""
raise NotImplementedError
def block(self, store: EpicStore, key: str, blocker: str) -> None:
"""Makes the issue named key blocked by the issue named blocker, as a person would link them in the tracker."""
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
@@ -38,7 +51,7 @@ class EpicStoreContract:
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)])
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, by_loop=True)])
def test_reads_back_a_sub_task_it_filed_after_its_parent(self) -> None:
store = self.new_store()
@@ -107,3 +120,33 @@ class EpicStoreContract:
self.assertEqual(store.add_label(key, label), Failure(reason))
self.assertIsInstance(store.add_label("ZZZ-1", "repo:log"), Failure)
self.assertEqual([issue.labels for issue in self.issues(store)], [(), ()])
def test_reads_an_issue_without_scores_or_blockers_as_one_with_none(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
[issue] = self.issues(store)
self.assertEqual((issue.key, issue.scores, issue.blockers), (key, ItemFields(), ()))
def test_reads_the_scores_a_person_or_the_plan_store_set(self) -> None:
store = self.new_store()
key = self.filed(store, store.epic_key, "Count the runs.")
self.score(store, key, {"L": "2", "E": "3", "I": "4", "S": "3", "Moves": "1 by 5", "Exempt": "security"})
[issue] = self.issues(store)
self.assertEqual((issue.scores.scores, issue.scores.moves, issue.scores.exempt), ({"L": 2, "E": 3, "I": 4, "S": 3}, (("1", 5),), "security"))
self.assertEqual((issue.scores.release, issue.scores.blocked_by), (None, ()))
def test_reads_each_blocker_of_an_issue_and_none_for_a_blocker_of_another(self) -> None:
store = self.new_store()
first, second, third = (self.filed(store, store.epic_key, f"Item {n}.") for n in range(3))
self.block(store, third, first)
self.block(store, third, second)
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual([read[key].blockers for key in (first, second, third)], [(), (), (first, second)])
def test_reads_whether_the_loop_filed_an_issue(self) -> None:
store = self.new_store()
ours = self.filed(store, store.epic_key, "Count the runs.")
theirs = self.person_files(store, "A person's issue.")
task = self.filed(store, ours, "Count them in the api.")
read = {issue.key: issue for issue in self.issues(store)}
self.assertEqual([read[key].by_loop for key in (ours, theirs, task)], [True, False, True])
+1 -1
View File
@@ -25,7 +25,7 @@ class MemoryEpic:
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))
self.issues.append(EpicIssue(key, summary, detail.strip(), tuple(sorted(labels)), None, "To Do", False, parent, by_loop=True))
return key
def add_label(self, key: str, label: str) -> None | Failure:
+17 -8
View File
@@ -5,12 +5,12 @@ 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 plan_store.jira_epic import blocked_by_links, FILED_BY, ISSUE_KEY, ISSUE_TYPE, project_of, PROPERTY, scores, searched
from project_config.settings import Epic
from do_epic.backend.protocol import EpicIssue, no_child, no_parent, unfit, unfit_label
from failure import Failure
from plan_store.jira_epic import ISSUE_KEY, ISSUE_TYPE, project_of, searched
FIELDS = ["summary", "description", "labels", "assignee", "status", "parent"]
FIELDS = ["summary", "description", "labels", "assignee", "status", "parent", "issuelinks"]
# 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"
@@ -60,6 +60,8 @@ class JiraEpic:
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)}
# The mark that tells the loop's issues from a person's, as plan_store marks the items it files.
properties = [{"key": PROPERTY, "value": {FILED_BY[0]: FILED_BY[1]}}]
kind = {"name": ISSUE_TYPE} if parent == self.epic_key else self.sub_task_type(project_of(parent), authorization)
if isinstance(kind, Failure):
return kind
@@ -68,7 +70,7 @@ class JiraEpic:
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}})
created = self.http("POST", f"{self.epic.site}/rest/api/3/issue", authorization, {"fields": fields | {"issuetype": kind}, "properties": properties})
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
@@ -130,7 +132,7 @@ class JiraEpic:
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)
answered = searched(self.epic.site, what, f"parent in ({named}) ORDER BY Rank ASC", {"fields": FIELDS, "properties": [PROPERTY]}, authorization, self.http)
if isinstance(answered, Failure):
return answered
found = [found_of(raw) for raw in answered]
@@ -159,9 +161,16 @@ def found_of(raw: object) -> Found | Failure:
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"
blockers = tuple(link.blocker for link in blocked_by_links(fields))
held = raw.get("properties", {}).get(PROPERTY, {})
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)
texts = (summary, *labels, state, parent, *blockers) 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 all(ISSUE_KEY.fullmatch(each) for each in (parent, *blockers)) 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, description or a linked issue's key holds another kind of value")
if not isinstance(held, dict):
return Failure(f"{key}'s issue property {PROPERTY} is not a JSON object")
read = scores(key, held)
if isinstance(read, Failure):
return read
return Found(EpicIssue(key, summary.strip(), "", tuple(sorted(labels)), name, state, done, parent, read, blockers, held.get(FILED_BY[0]) == FILED_BY[1]), description)
+8 -1
View File
@@ -6,6 +6,7 @@ import re
import typing
from failure import Failure
from plan.todo_table import ItemFields
# What a tracker accepts as a label: Jira refuses a label holding white space.
LABEL = re.compile(r"\S+")
@@ -28,6 +29,12 @@ class EpicIssue:
done: bool
# The epic's key for a child issue, the child's key for a sub-task.
parent: str
# The scores, Moves and Exempt a plan-item issue property holds, as `plan_store` reads them; its release and blocked_by stay unset, since an epic's items have no release and `blockers` holds theirs. Empty where the issue holds none, as a person's issue does.
scores: ItemFields = dataclasses.field(default_factory=ItemFields)
# The key of each issue this one is blocked by, in the tracker's order.
blockers: tuple[str, ...] = ()
# Whether the loop filed the issue, through EpicStore.file, rather than a person.
by_loop: bool = False
class EpicStore(typing.Protocol):
@@ -41,7 +48,7 @@ class EpicStore(typing.Protocol):
"""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."""
"""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."""
+12
View File
@@ -6,6 +6,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
from do_epic.backend.contract import EpicStoreContract
from failure import Failure
from plan_store import jira_epic
from do_epic.backend.fake import MemoryEpic
@@ -19,6 +20,17 @@ class MemoryEpicContract(EpicStoreContract, unittest.TestCase):
def close(self, store: MemoryEpic, key: str, status: str) -> None: # type: ignore[override]
store.change(key, status=status, done=True)
def person_files(self, store: MemoryEpic, summary: str) -> str: # type: ignore[override]
key = self.filed(store, store.epic_key, summary)
store.change(key, by_loop=False)
return key
def score(self, store: MemoryEpic, key: str, scores: dict[str, str]) -> None: # type: ignore[override]
store.change(key, scores=jira_epic.scores(key, scores))
def block(self, store: MemoryEpic, key: str, blocker: str) -> None: # type: ignore[override]
store.change(key, blockers=(*next(issue for issue in store.issues if issue.key == key).blockers, blocker))
class Failing(unittest.TestCase):
def test_every_read_and_filing_fails_with_the_reason_given(self) -> None:
+30 -5
View File
@@ -72,7 +72,7 @@ class FakeJira:
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]
found = [{"key": issue["key"], "fields": {name: value for name, value in issue["fields"].items() if name in body.get("fields", [])}, "properties": {name: value for name, value in issue.get("properties", {}).items() if name in body.get("properties", [])}} 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 {})
@@ -84,12 +84,21 @@ class FakeJira:
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}}})
self.issues.append({"key": key, "fields": {"summary": fields["summary"], "description": fields.get("description"), "labels": fields["labels"], "assignee": None, "status": TO_DO, "parent": {"key": parent}, "issuelinks": []}, "properties": {entry["key"]: entry["value"] for entry in body["properties"]}})
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]
def person_files(self, summary: str) -> str:
"""Files a child issue as the Jira website does: with no issue property."""
key = f"ABC-{len(self.issues) + 100}"
self.issues.append({"key": key, "fields": {"summary": summary, "description": None, "labels": [], "assignee": None, "status": TO_DO, "parent": {"key": "ABC-12"}, "issuelinks": []}})
return key
def set_property(self, key: str, value: dict[str, object]) -> None:
next(issue for issue in self.issues if issue["key"] == key).setdefault("properties", {})["plan-item"] = value # type: ignore[attr-defined, union-attr]
class Case(unittest.TestCase):
def setUp(self) -> None:
@@ -111,6 +120,17 @@ class JiraEpicContract(Case, EpicStoreContract):
def close(self, store: JiraEpic, key: str, status: str) -> None: # type: ignore[override]
self.jira.change(key, status={"name": status, "statusCategory": {"key": "done"}})
def person_files(self, store: JiraEpic, summary: str) -> str: # type: ignore[override]
return self.jira.person_files(summary)
def score(self, store: JiraEpic, key: str, scores: dict[str, str]) -> None: # type: ignore[override]
held = next(issue for issue in self.jira.issues if issue["key"] == key).get("properties", {}).get("plan-item", {}) # type: ignore[attr-defined, union-attr]
self.jira.set_property(key, held | scores)
def block(self, store: JiraEpic, key: str, blocker: str) -> None: # type: ignore[override]
links = next(issue for issue in self.jira.issues if issue["key"] == key)["fields"]["issuelinks"] # type: ignore[index]
links.append({"id": str(len(links) + 1), "type": {"inward": "is blocked by", "outward": "blocks"}, "inwardIssue": {"key": blocker}})
class Jira(Case):
def test_reads_the_sub_tasks_of_more_children_than_one_search_names(self) -> None:
@@ -146,16 +166,21 @@ class Jira(Case):
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"}}
valid = {"summary": "Count the runs.", "description": None, "labels": [], "assignee": None, "status": TO_DO, "parent": {"key": "ABC-12"}, "issuelinks": []}
linked = {"id": "1", "type": {"inward": "is blocked by"}, "inwardIssue": {"key": "ABC-2"}}
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"},
*((({"key": "ABC-34", "fields": valid | changed}, shape + ": its summary, labels, assignee, status, parent, description or a linked issue's key 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"}, {"issuelinks": [linked | {"inwardIssue": {"key": 7}}]}, {"issuelinks": [linked | {"inwardIssue": {"key": "ABC-x"}}]},
))),
({"key": "ABC-34", "fields": {key: value for key, value in valid.items() if key != "issuelinks"}}, shape + ": KeyError('issuelinks')"),
({"key": "ABC-34", "fields": valid, "properties": {"plan-item": "L 2"}}, "ABC-34's issue property plan-item is not a JSON object"),
({"key": "ABC-34", "fields": valid, "properties": {"plan-item": {"L": "many"}}}, "item ABC-34's L 'many' is not a whole number from 1 to 4; ABC-34 holds it in its issue property plan-item"),
({"key": "ABC-34", "fields": valid, "properties": None}, shape + ": AttributeError(\"'NoneType' object has no attribute 'get'\")"),
):
with self.subTest(raw=raw):
self.jira.answers[("POST", SEARCH)] = {"issues": [raw]}
+6 -1
View File
@@ -476,7 +476,7 @@ def issue_of(raw: object) -> Issue | Failure:
# The answer's nested fields are read as Jira documents them; one missing or of another type ends the read here, as a Failure, so no later step meets it.
try:
fields = raw["fields"]
links = tuple(Link(link["inwardIssue"]["key"], link["id"]) for link in fields["issuelinks"] if "inwardIssue" in link and link["type"]["inward"] == "is blocked by")
links = blocked_by_links(fields)
held = raw.get("properties", {}).get(PROPERTY, {})
summary, description, versions = fields["summary"].strip(), fields["description"], tuple(version["name"] for version in fields["fixVersions"])
except (AttributeError, KeyError, TypeError) as failure:
@@ -489,6 +489,11 @@ def issue_of(raw: object) -> Issue | Failure:
return issue
def blocked_by_links(fields: dict[str, typing.Any]) -> tuple[Link, ...]:
"""The "is blocked by" links among an issue's `issuelinks` field; a KeyError, TypeError or AttributeError where it isn't in the shape Jira documents."""
return tuple(Link(link["inwardIssue"]["key"], link["id"]) for link in fields["issuelinks"] if "inwardIssue" in link and link["type"]["inward"] == "is blocked by")
def keys_of(answered: list[object]) -> set[object]:
"""The key of each issue in the search's answer."""
return {raw.get("key") for raw in answered if isinstance(raw, dict)}
+17
View File
@@ -2725,3 +2725,20 @@ Read most (opens and searches):
- `bin/loop_claude/test_loop_claude.py` 2
- `bin/review_replay/main.py` 2
- `bin/rule_hook/main.py` 2
## Reading cost, chunk 755c22e12ace, finished 2026-11-18T16:10:53Z
114613 new input tokens before the first commit.
Read most (opens and searches):
- `bin/plan/ranking.py` 6
- `bin/plan_store/jira_epic.py` 5
- `rules/todo-items.md` 4
- `bin/plan/goals_file.py` 2
- `bin/do_epic/backend/jira.py` 1
- `bin/do_epic/backend/protocol.py` 1
- `bin/do_epic/config.py` 1
- `bin/plan/blockers.py` 1
- `bin/plan/todo_table.py` 1
- `docs/decisions.md` 1