File findings, release reviews and added items as the issue types the settings name, and refuse a type the Jira project lacks

This commit is contained in:
Lilleman
2026-11-20 11:31:44 +01:00
parent 88fee92dcb
commit 34328b11b9
15 changed files with 179 additions and 30 deletions
+2 -1
View File
@@ -134,7 +134,7 @@ A client that plans in Jira Cloud names an epic as its project's plan: `plan = "
A read fails, naming the issue, where a child is in another Jira project or names no such Fix Version. The config's `env-file` must hold `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, an API token of that Atlassian account, and only its owner may read that file: `chmod 600` it.
The loop reads such a plan and files items into it, each as a Task under the epic. `todo-item add` needs the item's release among the Jira project's Fix Versions, named as `1.2.0` or `v1.2.0`. The config states the formula and the bar that a todo.md states under `## Scoring`, such as `jira-score-formula = "100 * V / (2**S + 8)"` and `jira-score-bar = 1`, and fails to load without them. `todo-item add` refuses an item that scores under the bar, unless it is exempt. It ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep the rank the team gave them, and `rank_todo.py` doesn't rank the plan.
The loop reads such a plan and files items into it, each as a Task under the epic, or as the type `jira-finding-type` names, such as `"Feature"`, for a Jira project that has no Task type. `todo-item add` fails, naming the project's types, where it lacks that type. It needs the item's release among the Jira project's Fix Versions, named as `1.2.0` or `v1.2.0`. The config states the formula and the bar that a todo.md states under `## Scoring`, such as `jira-score-formula = "100 * V / (2**S + 8)"` and `jira-score-bar = 1`, and fails to load without them. `todo-item add` refuses an item that scores under the bar, unless it is exempt. It ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep the rank the team gave them, and `rank_todo.py` doesn't rank the plan.
`todo-item edit` and `move` change only an issue the loop filed. Of an issue a person filed, `edit` sets only the scores, and posts its `--comment` on the issue to tell the team why; the summary, description and Fix Version stay the team's to change in Jira, as do its links. On an issue the loop filed, `edit --blocked-by` makes and deletes the links to the epic's open items. For `todo-item finish`, the config names the workflow transition that finishes an item and the status it leads to, both as Jira shows them: `jira-finish-transition = "Mark as done"` and `jira-finish-status = "Done"`. Finish then moves the item's issue by that transition. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
@@ -158,6 +158,7 @@ The last line prints each setting's path once the config is complete.
- `config.toml` fits do-epic to a team whose own automation moves issues, such as a CI job that moves an issue when its pull request merges. Two settings do:
- `jira-unblocking-statuses` lists the statuses at which an issue's work has landed though Jira doesn't count it done yet, such as `["Release Ready"]`, in upper or lower case. An issue in one of them takes no chunk and no longer blocks the issues it blocks, and `--status` names the statuses beside each blocker. A status Jira counts as done always does both. The release reviews, which are the epic's last chunk, still wait until Jira counts every issue done: run `do-epic <EPIC-KEY>` then, to start them.
- `jira-automation-moves-issues = true` keeps do-epic from moving the issue of a finished chunk in a repo: the automation moves it, and do-epic waits for that move before it starts what the issue blocks. An issue without a repo has no pull request, so do-epic still moves it, with `jira-finish-transition`. The setting needs `jira-unblocking-statuses`, which names the status the automation gives an issue whose pull request merged.
- `config.toml` may set `jira-finding-type` and `jira-review-type`, the issue types do-epic files a finding and a repo's release review as under the epic, such as `"Feature"` and `"Chore"`. Both are Task where left out. do-epic files nothing where the Jira project lacks the type, and says which types it has.
- `config.toml` may set `sub-task-summary`, which shapes the summary of each sub-task do-epic files for an issue that changes several repos, such as `sub-task-summary = "{label}: {Summary}"`. `{label}` is the team's label for the repo, else the repo's name, and `{Summary}` is the issue's summary with a capital first letter. It must hold `{Summary}`. Without it a summary is `[<repo>] <the issue's summary>`.
- `config.toml` may end with a `[label-repos]` table, for a team that already labels its issues by repo. Give it one line for each such label: the label, then the repo's name, such as `twu-4 = "tenant-web-ui-4"`. do-epic reads such a label as it reads its own `repo:<name>`. Where the label is the repo's name, map the name to itself, as in `core-4 = "core-4"`. Where several lines name one repo, do-epic writes the label of the first. Write every other setting above the table.
- `repo-rule.md` is prose that says how to tell an item's repo, such as "a label that equals a repo's name names that repo". It may not be blank. `do-epic <EPIC-KEY>` uses it to pick where each open issue without such a label is worked, and records the pick as a label. For a repo that is the team's own label from `[label-repos]`, else `repo:<name>`; for work of Claude's that changes no repo, `do-epic-claude`; for a task of yours, `do-epic-human`. Where the rule leaves an issue unclear, do-epic asks you on the terminal. Answer with the label, or with Enter alone to leave the issue waiting. Change a pick by editing the label in Jira.
+13
View File
@@ -6,6 +6,7 @@ import typing
from failure import Failure
from project_config.settings import Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from atlassian.client import Http
from text_files.markdown_text import listed
ISSUE_KEY = re.compile(r"([A-Z][A-Z0-9_]*)-([0-9]+)")
PAGE = 100
@@ -115,6 +116,18 @@ def transition_of(offered: object, key: str, finish: Finish) -> str | Failure:
return id_
def issue_type_refusal(site: str, project: str, kind: str, authorization: str, http: Http) -> str | None:
"""Why a new issue under an epic of the Jira project may not be of the type named kind: Jira didn't say which types the project has, or none of its types besides sub-task types has that name. None where one has."""
answered = http("GET", f"{site}/rest/api/3/issue/createmeta/{project}/issuetypes", authorization, None)
if isinstance(answered, Failure):
return f"cannot read {project}'s issue types: {answered.reason}"
types = answered.get("issueTypes") if isinstance(answered, dict) else None
if not isinstance(types, list) or not all(isinstance(each, dict) and isinstance(each.get("name"), str) for each in types):
return f"Jira answered {project}'s issue types in a shape its REST API version 3 doesn't document"
names = [each["name"] for each in types if each.get("subtask") is not True]
return None if kind in names else f"{project} has no issue type {kind!r} to file an issue under an epic as; its types are {listed(names, 'and') if names else 'none'}"
def project_of(key: str) -> str:
"""The key of the Jira project an issue key lies in."""
return key.rpartition("-")[0]
+33
View File
@@ -70,5 +70,38 @@ class TheCategoryOfAnIssuesStatus(unittest.TestCase):
self.assertEqual(jira.status_category(wrong), Failure("its status category has no key that is text"))
class TheRefusalOfAnIssueType(unittest.TestCase):
TYPES = {"issueTypes": [{"name": "Feature", "subtask": False}, {"name": "Bug", "subtask": False}, {"name": "Subtask", "subtask": True}]}
def refusal(self, kind: str, answer: object) -> str | None:
asked: list[tuple[str, str, object]] = []
def http(method: str, url: str, authorization: str, body: object) -> object:
asked.append((method, url, body))
return answer
refused = jira.issue_type_refusal("https://acme.atlassian.net", "ABC", kind, "Basic x", http)
self.assertEqual(asked, [("GET", "https://acme.atlassian.net/rest/api/3/issue/createmeta/ABC/issuetypes", None)])
return refused
def test_is_none_where_the_project_has_the_type(self):
self.assertIsNone(self.refusal("Bug", self.TYPES))
def test_names_the_types_the_project_has_other_than_sub_tasks_where_it_lacks_the_type(self):
self.assertEqual(self.refusal("Task", self.TYPES), "ABC has no issue type 'Task' to file an issue under an epic as; its types are Feature and Bug")
def test_a_sub_task_type_is_not_one_to_file_under_an_epic(self):
self.assertEqual(self.refusal("Subtask", self.TYPES), "ABC has no issue type 'Subtask' to file an issue under an epic as; its types are Feature and Bug")
def test_says_the_project_has_no_type_where_it_has_only_sub_task_types(self):
self.assertEqual(self.refusal("Bug", {"issueTypes": [{"name": "Subtask", "subtask": True}]}), "ABC has no issue type 'Bug' to file an issue under an epic as; its types are none")
def test_says_why_where_jira_fails_or_answers_in_another_shape(self):
self.assertEqual(self.refusal("Bug", Failure("Jira answered 403")), "cannot read ABC's issue types: Jira answered 403")
for wrong in ([], {}, {"issueTypes": "Bug"}, {"issueTypes": [{"subtask": False}]}):
with self.subTest(wrong=wrong):
self.assertEqual(self.refusal("Bug", wrong), "Jira answered ABC's issue types in a shape its REST API version 3 doesn't document")
if __name__ == "__main__":
unittest.main()
+14 -4
View File
@@ -5,11 +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 BLOCKS, FILED_BY, ISSUE_TYPE, PROPERTY, scores
from atlassian.jira import DONE, entry_of, finishing_transition, ISSUE_KEY, MAX_PAGES, move_refusal, PERHAPS_FILED, PERHAPS_MOVED, project_of, rank_refusal, searched, SHAPE, status_category, unshaped
from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from plan_store.jira_epic import BLOCKS, FILED_BY, PROPERTY, scores
from project_config.settings import DEFAULT_ISSUE_TYPE, Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from atlassian.jira import DONE, entry_of, finishing_transition, ISSUE_KEY, issue_type_refusal, MAX_PAGES, move_refusal, PERHAPS_FILED, PERHAPS_MOVED, project_of, rank_refusal, searched, SHAPE, status_category, unshaped
from do_epic.backend.protocol import EpicIssue, no_blocker, no_child, no_parent, no_words, unfit, unfit_label
from failure import Failure
from do_epic.repo_pick import REVIEW_LABEL
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.
@@ -35,6 +36,9 @@ class JiraEpic:
finish: Finish | None = None
# The pages a search may take before the read fails.
max_pages: int = MAX_PAGES
# The issue types a finding and a release review (an issue labelled REVIEW_LABEL) are filed as under the epic.
finding_type: str = DEFAULT_ISSUE_TYPE
review_type: str = DEFAULT_ISSUE_TYPE
@property
def epic_key(self) -> str:
@@ -66,7 +70,7 @@ class JiraEpic:
fields: dict[str, typing.Any] = {"project": {"key": project_of(parent)}, "parent": {"key": parent}, "summary": summary, "labels": list(labels)}
# Marks the issue as the loop'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)
kind = self.child_type(project_of(parent), REVIEW_LABEL in labels, authorization) if parent == self.epic_key else self.sub_task_type(project_of(parent), authorization)
if isinstance(kind, Failure):
return kind
if detail.strip():
@@ -244,6 +248,12 @@ class JiraEpic:
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 child_type(self, project: str, review: bool, authorization: str) -> dict[str, str] | Failure:
"""The issue type of a new child of the epic: the type of a release review where review, else of a finding, if the project has it."""
name = self.review_type if review else self.finding_type
refused = issue_type_refusal(self.epic.site, project, name, authorization, self.http)
return Failure(refused) if refused else {"name": name}
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)
+19 -4
View File
@@ -13,6 +13,7 @@ from do_epic.backend.contract import EpicStoreContract
from failure import Failure
from do_epic.backend.jira import JiraEpic
from adf_codec.convert import Refused
from do_epic.repo_pick import REVIEW_LABEL
SITE = "https://acme.atlassian.net"
EPIC = Epic(SITE, "ABC-12")
@@ -27,7 +28,7 @@ DONE = {"name": "Done", "statusCategory": {"key": "done"}}
TRANSITIONS = f"{ISSUES}/ABC-12/transitions"
EPIC_COMMENT = f"{ISSUES}/ABC-12/comment"
EPIC_STATUS = f"{ISSUES}/ABC-12?fields=status"
TYPES = {"issueTypes": [{"id": "10001", "name": "Task", "subtask": False}, {"id": "10003", "name": "Subtask", "subtask": True}]}
TYPES = {"issueTypes": [{"id": "10001", "name": "Task", "subtask": False}, {"id": "10002", "name": "Feature", "subtask": False}, {"id": "10004", "name": "Chore", "subtask": False}, {"id": "10003", "name": "Subtask", "subtask": True}]}
def to_adf(markdown: str) -> dict[str, object]:
@@ -46,6 +47,8 @@ class FakeJira:
answers: dict[tuple[str, str], object] = dataclasses.field(default_factory=dict)
calls: list[tuple[str, str]] = dataclasses.field(default_factory=list)
comments: dict[str, list[object]] = dataclasses.field(default_factory=dict)
# The issue type of each issue created, as the request names it.
filed_as: list[object] = dataclasses.field(default_factory=list)
# The ID of each transition made.
transitioned: list[str] = dataclasses.field(default_factory=list)
# The transitions Jira offers an issue that isn't done.
@@ -116,9 +119,10 @@ class FakeJira:
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
kind = fields["issuetype"] if parent == "ABC-12" and fields["issuetype"] in [{"name": "Task"}, {"name": "Feature"}, {"name": "Chore"}] 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")
self.filed_as.append(fields["issuetype"])
key = f"ABC-{len(self.issues) + 100}"
# The links Jira makes as it creates the issue: the inward issue blocks the new one, which then reads "is blocked by" it.
links = [{"id": "1", "type": {"inward": "is blocked by", "outward": "blocks"}, "inwardIssue": add["add"]["inwardIssue"]} for add in body.get("update", {}).get("issuelinks", []) if add["add"]["type"] == {"name": "Blocks"}]
@@ -296,9 +300,20 @@ class Jira(Case):
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:
def test_files_a_child_as_a_task_where_the_settings_name_no_type(self) -> None:
self.new_store().file("ABC-12", "Count the runs.", "", ())
self.assertNotIn(("GET", ISSUE_TYPES), self.jira.calls)
self.assertEqual(self.jira.filed_as, [{"name": "Task"}])
def test_files_a_finding_and_a_release_review_as_the_types_the_settings_name(self) -> None:
store = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, finding_type="Feature", review_type="Chore")
store.file("ABC-12", "Count the runs.", "", ("repo:api",))
store.file("ABC-12", "Review api.", "", ("repo:api", REVIEW_LABEL))
self.assertEqual(self.jira.filed_as, [{"name": "Feature"}, {"name": "Chore"}])
def test_files_nothing_where_the_project_lacks_the_type_and_names_the_types_it_has(self) -> None:
store = JiraEpic(EPIC, self.env_file, self.jira, to_markdown, to_adf, finding_type="Feature", review_type="Investigation")
self.assertEqual(store.file("ABC-12", "Review api.", "", (REVIEW_LABEL,)), Failure("ABC has no issue type 'Investigation' to file an issue under an epic as; its types are Task, Feature and Chore"))
self.assertEqual(self.jira.issues, [])
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")):
+12 -3
View File
@@ -19,6 +19,7 @@ One pair per machine, the same for every epic (docs/decisions.md → `do-epic: d
- `jira-finish-transition` and `jira-finish-status` name the workflow transition that moves a finished chunk's issue and closes a finished epic, such as "Mark as done", and the status it leads to, such as "Done". A project's config names a plan item's the same way. Set both or neither; without them do-epic moves no issue to done and closes no epic.
- `jira-unblocking-statuses` lists the statuses at which an issue's work has landed though Jira doesn't count it done yet, such as `["Release Ready"]`, in upper or lower case. An issue in one of them takes no chunk and no longer blocks the issues it blocks. A status Jira counts as done always does both, listed or not.
- `jira-automation-moves-issues = true` says the team's own automation moves an issue when its pull request merges. do-epic then moves only the issue of a chunk without a repo, which has no pull request, and waits for the automation to move each other. It needs `jira-unblocking-statuses`, which then names the status the automation gives an issue whose pull request merged. false where left out.
- `jira-finding-type` and `jira-review-type` name the Jira issue types do-epic files a finding and a repo's release review as under the epic, such as `"Feature"` and `"Chore"`, for a Jira project that has no Task type. Task where left out. do-epic files nothing where the project lacks the type, and says which types it has.
- `sub-task-summary` shapes the summary of each sub-task do-epic files for an issue that changes several repos, such as `"{label}: {Summary}"`. `{label}` is the team's label for the repo, else the repo's name, and `{Summary}` is the issue's summary with a capital first letter. It must hold `{Summary}`. Where left out, a summary is `[<repo>] <the issue's summary>`.
- `[label-repos]` has one line for each label of the team's own that names a repo: the label, then that repo's name, such as `twu-4 = "tenant-web-ui-4"`. do-epic reads such a label as it reads its own `repo:<name>`. A team whose label is the repo's name maps the name to itself. Where several lines name one repo, do-epic writes the label of the first.
- `repo-rule.md` is prose that says how to tell an item's repo, and mustn't be blank."""
@@ -28,7 +29,7 @@ import re
import string
import types
from project_config.settings import anywhere, CONFIG, DO_EPIC, ENV_FILE, Finish, finish_faults, finish_of, JIRA_FINISH, LANGUAGE, language_fault, lies_in, name_of, parsed, PROJECTS, SITE
from project_config.settings import anywhere, CONFIG, DEFAULT_ISSUE_TYPE, DO_EPIC, ENV_FILE, Finish, finish_faults, finish_of, JIRA_FINDING_TYPE, JIRA_FINISH, LANGUAGE, language_fault, lies_in, name_of, parsed, PROJECTS, SITE, type_fault
from failure import Failure
from do_epic.backend.protocol import LABEL
from do_epic.repo_pick import LabelRepos, of_label, REPO_NAME, REVIEW_LABEL
@@ -48,7 +49,9 @@ LABEL_REPOS = "label-repos"
UNBLOCKING_STATUSES = "jira-unblocking-statuses"
AUTOMATION_MOVES = "jira-automation-moves-issues"
SUB_TASK_SUMMARY = "sub-task-summary"
OPTIONAL = (CLONE_FOLDER, LANGUAGE, *JIRA_FINISH, UNBLOCKING_STATUSES, AUTOMATION_MOVES, LABEL_REPOS, SUB_TASK_SUMMARY)
REVIEW_TYPE = "jira-review-type"
ISSUE_TYPES = (JIRA_FINDING_TYPE, REVIEW_TYPE)
OPTIONAL = (CLONE_FOLDER, LANGUAGE, *JIRA_FINISH, UNBLOCKING_STATUSES, AUTOMATION_MOVES, LABEL_REPOS, SUB_TASK_SUMMARY, *ISSUE_TYPES)
LISTED = f"The settings are {', '.join(SETTINGS)}, and optionally {listed(OPTIONAL, 'and')}."
@@ -71,6 +74,9 @@ class DoEpicConfig:
automation_moves: bool = False
# The SUB_TASK_SUMMARY template; None where the config has none.
sub_task_summary: str | None = None
# The issue types a finding and a release review are filed as under the epic.
finding_type: str = DEFAULT_ISSUE_TYPE
review_type: str = DEFAULT_ISSUE_TYPE
def label_repo_faults(table: object) -> list[str]:
@@ -146,6 +152,7 @@ def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfi
*workflow_faults(values),
*(summary_template_faults(values[SUB_TASK_SUMMARY]) if SUB_TASK_SUMMARY in values else []),
*label_repo_faults(values.get(LABEL_REPOS, {})),
*(f"`{name}` is {values[name]!r}, {fault}" for name, example in zip(ISSUE_TYPES, ("Feature", "Chore")) if name in values and (fault := type_fault(values[name], example))),
*([rule.reason] if isinstance(rule, Failure) else [f"`{REPO_RULE}` is blank"] if not rule.strip() else []),
]
if faults:
@@ -158,4 +165,6 @@ def load(home: pathlib.Path, ladder_file: pathlib.Path = SHIPPED) -> DoEpicConfi
assert isinstance(statuses, list)
template = values.get(SUB_TASK_SUMMARY)
assert template is None or isinstance(template, str)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule, finish_of(values), types.MappingProxyType(labels), tuple(statuses), values.get(AUTOMATION_MOVES) is True, template)
finding_type, review_type = (values.get(name, DEFAULT_ISSUE_TYPE) for name in ISSUE_TYPES)
assert isinstance(finding_type, str) and isinstance(review_type, str)
return DoEpicConfig(folder, url, env_file, clone_folder, language, model, rule, finish_of(values), types.MappingProxyType(labels), tuple(statuses), values.get(AUTOMATION_MOVES) is True, template, finding_type, review_type)
+1 -1
View File
@@ -82,7 +82,7 @@ Backend = typing.Callable[[DoEpicConfig, str], tuple[EpicStore, EpicRecord]]
def jira_backend(config: DoEpicConfig, key: str) -> tuple[EpicStore, EpicRecord]:
epic = Epic(config.jira_url, key)
return JiraEpic(epic, config.env_file, finish=config.finish), EpicRecord(EpicDescription(epic, config.env_file))
return JiraEpic(epic, config.env_file, finish=config.finish, finding_type=config.finding_type, review_type=config.review_type), EpicRecord(EpicDescription(epic, config.env_file))
@dataclasses.dataclass(frozen=True)
+17
View File
@@ -123,6 +123,23 @@ class ConfigTest(unittest.TestCase):
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.unblocking, found.automation_moves), (("Release Ready", "Done"), True))
def test_reads_the_issue_types_of_a_finding_and_a_release_review_which_are_task_where_left_out(self) -> None:
self.write()
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.finding_type, found.review_type), ("Task", "Task"))
self.write(SETTINGS + 'jira-finding-type = "Feature"\njira-review-type = "Chore"\n')
found = load(self.home)
assert isinstance(found, DoEpicConfig), found
self.assertEqual((found.finding_type, found.review_type), ("Feature", "Chore"))
def test_refuses_an_issue_type_that_is_no_name(self) -> None:
for setting, example in (("jira-finding-type", "Feature"), ("jira-review-type", "Chore")):
for value in ("4", '" "'):
with self.subTest(setting=setting, value=value):
self.write(SETTINGS + f"{setting} = {value}\n")
self.assertIn(f'`{setting}` is {4 if value == "4" else repr(" ")}, not the name Jira shows, such as "{example}"', self.failure())
def test_refuses_unblocking_statuses_that_are_no_list_of_names_and_a_switch_that_is_no_boolean(self) -> None:
for value in ('"Done"', '["Done", " "]', "[]", "[1]"):
with self.subTest(value=value):
+5
View File
@@ -104,6 +104,11 @@ class TheJiraBackend(unittest.TestCase):
self.assertEqual((store.epic, store.env_file, store.finish), (Epic("https://acme.atlassian.net", "ABC-12"), pathlib.Path("/h/jira.env"), Finish("Mark as done", "Done"))) # type: ignore[attr-defined]
self.assertEqual((record.description.epic, record.description.env_file), (store.epic, store.env_file)) # type: ignore[attr-defined]
def test_files_the_issue_types_the_config_names(self) -> None:
config = DoEpicConfig(pathlib.Path("/c"), "https://acme.atlassian.net", pathlib.Path("/h/jira.env"), pathlib.Path("/h/code"), "English", "claude-opus-5-5", "rule", finding_type="Feature", review_type="Chore")
store, _ = main.jira_backend(config, "ABC-12")
self.assertEqual((store.finding_type, store.review_type), ("Feature", "Chore")) # type: ignore[attr-defined]
class TheLauncher(unittest.TestCase):
def test_the_repo_ships_a_do_epic_that_prints_its_help(self) -> None:
+10 -7
View File
@@ -12,8 +12,8 @@ from atlassian.client import basic_auth, Http, jira_json, ToAdf, ToMarkdown
from plan.todo_table import BLOCKED_BY, Item, item_fields, ItemFields, MOVES, SHAPE
from plan_store.markdown_edits import bold_cell, plain, unfit_text
from plan_store.plans import cells, no_item, Plan, Written
from atlassian.jira import entry_of, finishing_transition, ISSUE_KEY, Link, MAX_PAGES, move_refusal, PERHAPS_FILED, PERHAPS_MOVED, project_of, rank_refusal, searched, unshaped
from project_config.settings import Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from project_config.settings import DEFAULT_ISSUE_TYPE, Epic, Finish, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION
from atlassian.jira import entry_of, finishing_transition, ISSUE_KEY, issue_type_refusal, Link, MAX_PAGES, move_refusal, PERHAPS_FILED, PERHAPS_MOVED, project_of, rank_refusal, searched, unshaped
from failure import Failure
from plan.release import parsed, Release, tagged
from plan import ranking
@@ -23,7 +23,6 @@ PROPERTY = "plan-item"
# The key in PROPERTY's value that marks an issue the loop filed, and its value. An edit of an issue without it, which a person filed, writes only PROPERTY and a comment.
FILED_BY = ("Filed by", "loop")
# The issue type of an issue the loop files, which Jira Software's project templates all have; a project without it refuses the issue, saying so.
ISSUE_TYPE = "Task"
# The name of the link type whose inward side reads "is blocked by", as Jira Cloud ships it.
BLOCKS = "Blocks"
SECURITY = "security"
@@ -73,6 +72,8 @@ class JiraPlan:
finish_by: Finish | None = None
# The pages a search may take before the read fails.
max_pages: int = MAX_PAGES
# The issue type `add` files an item as.
finding_type: str = DEFAULT_ISSUE_TYPE
# How add scores an item: by the config's formula and bar, with the goal weights the project's records give.
scoring: ReadsScoring = dataclasses.field(kw_only=True)
@@ -98,7 +99,7 @@ class JiraPlan:
"""Files the item as a child issue, where it scores at the config's bar or above or is exempt, and ranks it as `placing` says.
Jira takes the links and the rank after the issue. One it refuses leaves the issue filed, so the write counts as landed, and a note says what to do by hand."""
filing = filing_of(fields, detail, self.epic)
filing = filing_of(fields, detail, self.epic, self.finding_type)
if isinstance(filing, Failure):
return filing
scoring = self.scoring.read()
@@ -113,6 +114,8 @@ class JiraPlan:
description = self.description_of(detail)
if isinstance(description, Failure):
return description
if refused := issue_type_refusal(self.epic.site, project_of(self.epic.key), self.finding_type, authorization, self.http):
return Failure(refused)
issue_fields = filing.fields | ({"description": description} if description else {})
version = self.fix_version(filing.release, authorization)
if isinstance(version, Failure):
@@ -276,8 +279,8 @@ class Filing:
item: Item
def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failure:
"""The issue to file for an item with these fields under epic, or why a field cannot be filed."""
def filing_of(fields: dict[str, str], detail: str, epic: Epic, issue_type: str) -> Filing | Failure:
"""The issue to file, of the type named issue_type, for an item with these fields under epic, or why a field cannot be filed."""
named = cells(fields)
summary = plain(named.get("Item", "")).strip()
if not summary:
@@ -290,7 +293,7 @@ def filing_of(fields: dict[str, str], detail: str, epic: Epic) -> Filing | Failu
return checked
assert checked.release is not None, "item_fields refuses an empty Release"
project = project_of(epic.key)
issue_fields: dict[str, typing.Any] = {"project": {"key": project}, "parent": {"key": epic.key}, "issuetype": {"name": ISSUE_TYPE}, "summary": summary}
issue_fields: dict[str, typing.Any] = {"project": {"key": project}, "parent": {"key": epic.key}, "issuetype": {"name": issue_type}, "summary": summary}
if checked.exempt == SECURITY:
issue_fields["labels"] = [SECURITY]
value = checked.scores | {MOVES: named.get(MOVES, ""), "Exempt": checked.exempt, FILED_BY[0]: FILED_BY[1]}
+1 -1
View File
@@ -24,7 +24,7 @@ def store(config: ProjectConfig) -> PlanStore:
# load refuses a config that names an epic and no formula or bar.
assert config.jira_scoring is not None
scoring = StatedScoring(config.jira_scoring, goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"), config.readability_floor)
return JiraPlan(config.epic, config.env_file, finish_by=config.jira_finish, scoring=scoring)
return JiraPlan(config.epic, config.env_file, finish_by=config.jira_finish, finding_type=config.jira_finding_type, scoring=scoring)
def file_plan(config: ProjectConfig, path: pathlib.Path | None = None) -> FilePlan:
+15 -5
View File
@@ -227,6 +227,7 @@ class JiraPlan(unittest.TestCase):
ISSUES = "https://acme.atlassian.net/rest/api/3/issue"
LINKS = "https://acme.atlassian.net/rest/api/3/issueLink"
VERSIONS = "https://acme.atlassian.net/rest/api/3/project/ABC/versions"
ISSUE_TYPES = "https://acme.atlassian.net/rest/api/3/issue/createmeta/ABC/issuetypes"
PERHAPS_FILED = "unless Jira refused the request, the issue may exist: look under ABC-12 before filing it again"
FIELDS = {"Release": "0.1.0", "Tagline": "Count the runs.", "L": "1", "E": "2", "I": "3", "S": "1", "Moves": "1 by 9"}
PROPERTY = {"L": 1, "E": 2, "I": 3, "S": 1, "Moves": "1 by 9", "Exempt": "", "Filed by": "loop"}
@@ -261,30 +262,39 @@ class Filing(unittest.TestCase):
self.linked: object = None
self.versions: object = [{"name": "0.1.0"}, {"name": "v0.2.0"}, "odd", {"name": ["0.1.0"]}, {"name": {"en": "0.1.0"}}]
self.ranked: object = None
self.types: object = {"issueTypes": [{"name": "Task", "subtask": False}, {"name": "Feature", "subtask": False}, {"name": "Subtask", "subtask": True}]}
self.scoring = Stated()
def http(self, method: str, url: str, authorization: str, body: object) -> object:
"""Stands in for Jira: answers the epic, self.versions for the project's Fix Versions, self.open to the search, self.created to a new issue, self.linked to a new link and self.ranked to a rank."""
"""Stands in for Jira: answers the epic, self.versions for the project's Fix Versions, self.types for the project's issue types, self.open to the search, self.created to a new issue, self.linked to a new link and self.ranked to a rank."""
self.calls.append((method, url, body))
assert authorization == AUTHORIZATION
return {SEARCH: {"issues": self.open}, ISSUES: self.created, LINKS: self.linked, VERSIONS: self.versions, RANK: self.ranked}.get(url, {"key": "ABC-12"})
return {SEARCH: {"issues": self.open}, ISSUES: self.created, LINKS: self.linked, VERSIONS: self.versions, ISSUE_TYPES: self.types, RANK: self.ranked}.get(url, {"key": "ABC-12"})
def to_adf(self, markdown: str) -> dict[str, object] | Failure:
return adf(markdown)
def add(self, fields: dict[str, str] = FIELDS, detail: str = ""):
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf, scoring=self.scoring).add(fields, detail)
def add(self, fields: dict[str, str] = FIELDS, detail: str = "", **plan: str):
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of, self.to_adf, scoring=self.scoring, **plan).add(fields, detail)
def sent(self, url: str) -> list[object]:
return [body for _, sent_to, body in self.calls if sent_to == url]
def test_files_the_item_as_a_task_under_the_epic_marked_as_the_loops(self):
self.assertEqual(self.add(), Written(40))
self.assertEqual([call for call in self.calls if call[1] != SEARCH and "/issue/ABC-12" not in call[1]], [("GET", VERSIONS, None), ("POST", ISSUES, {
self.assertEqual([call for call in self.calls if call[1] != SEARCH and "/issue/ABC-12" not in call[1]], [("GET", ISSUE_TYPES, None), ("GET", VERSIONS, None), ("POST", ISSUES, {
"fields": {"project": {"key": "ABC"}, "parent": {"key": "ABC-12"}, "issuetype": {"name": "Task"}, "summary": "Count the runs.", "fixVersions": [{"name": "0.1.0"}]},
"properties": [{"key": "plan-item", "value": PROPERTY}],
})])
def test_files_the_item_as_the_issue_type_the_plan_names(self):
self.assertEqual(self.add(finding_type="Feature"), Written(40))
self.assertEqual(self.sent(ISSUES)[0]["fields"]["issuetype"], {"name": "Feature"}) # type: ignore[index]
def test_files_nothing_where_the_project_lacks_the_issue_type_and_names_the_types_it_has(self):
self.assertEqual(self.add(finding_type="Chore"), Failure("ABC has no issue type 'Chore' to file an issue under an epic as; its types are Task and Feature"))
self.assertEqual(self.sent(ISSUES), [])
def test_a_bold_tagline_is_filed_plain(self):
self.add(FIELDS | {"Tagline": "**Count the runs.**"})
self.assertEqual(self.sent(ISSUES)[0]["fields"]["summary"], "Count the runs.") # type: ignore[index]
+5 -1
View File
@@ -51,6 +51,10 @@ which must be one Jira counts as done. Write both names as Jira shows them:
Where the config leaves them out, `todo-item finish` fails in a Jira plan. Each is printed with the others only where it is set.
`jira-finding-type` is an optional setting, allowed only beside such a plan: the Jira issue type
`todo-item add` files an item as, such as "Feature", for a Jira project that has no Task type.
Task where left out. `todo-item add` fails, naming the types the project has, where it has none of that name.
`goals-and-audience` may name a Jira Cloud epic the same way, where `plan` names one too. The
epic's description is then the goals file, with ## Goals and ## Audience as headings, and
`project-config goals-and-audience` prints the setting as the config spells it. The description is
@@ -152,7 +156,7 @@ without `env-file`, sets `jira-finish-transition` or `jira-finish-status` to any
without a `plan` in Jira, names a Jira `plan` and leaves out `jira-score-formula` or `jira-score-bar`, sets
one of those two without a `plan` in Jira, sets the formula to one that doesn't parse or the bar to anything
but a number, sets `readability-floor` to anything but a number
from 1 to 10, or sets `parallel-chunks` to anything but a whole number of 1 or more, and where `coding-conventions`, `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
from 1 to 10, sets `parallel-chunks` to anything but a whole number of 1 or more, or sets `jira-finding-type` to anything but a name or without a `plan` in Jira, and where `coding-conventions`, `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
"""
import pathlib
import sys
+13 -2
View File
@@ -62,8 +62,11 @@ JIRA_FINISH = (JIRA_FINISH_TRANSITION, JIRA_FINISH_STATUS)
JIRA_SCORE_FORMULA = "jira-score-formula"
JIRA_SCORE_BAR = "jira-score-bar"
JIRA_SCORE = (JIRA_SCORE_FORMULA, JIRA_SCORE_BAR)
# The issue type `todo-item add` files an item as, and do-epic files a finding as; the default is the one Jira ships in every project of its software templates, which a project may lack.
JIRA_FINDING_TYPE = "jira-finding-type"
DEFAULT_ISSUE_TYPE = "Task"
# The settings allowed only where `plan` names a Jira epic.
JIRA_PLAN_ONLY = (*JIRA_FINISH, *JIRA_SCORE)
JIRA_PLAN_ONLY = (*JIRA_FINISH, *JIRA_SCORE, JIRA_FINDING_TYPE)
# What opens a setting that names a Jira Cloud epic in place of a path: `jira:`, then the epic's address as the browser shows it. The settings below may name an epic; each reads its own part of it.
JIRA = "jira:"
EPIC_SPELLINGS = {
@@ -146,6 +149,8 @@ class ProjectConfig:
notifier: Notifier | None = None
# The config's `jira-finish-transition` and `jira-finish-status`, or None where it sets neither.
jira_finish: Finish | None = None
# The config's `jira-finding-type`, the issue type `todo-item add` files an item as.
jira_finding_type: str = DEFAULT_ISSUE_TYPE
# The config's `jira-score-formula` and `jira-score-bar`, which it sets where `plan` names an epic.
jira_scoring: JiraScoring | None = None
# The Confluence page of each record the config keeps on one, by the record's setting.
@@ -286,6 +291,11 @@ def text_read(fault: typing.Callable[[object], str | None]) -> typing.Callable[[
return read
def type_fault(value: object, example: str = "Feature") -> str | None:
"""Why value is no issue type's name; None where it is one. example is a name a message quotes."""
return None if name_of(value) else f'not the name Jira shows, such as "{example}"'
def formula_fault(value: object) -> str | None:
"""Why value is no formula that may score an item, as todo.md's `Score` line states one; None where it is one."""
if not isinstance(value, str):
@@ -359,8 +369,9 @@ SCALARS = (
Scalar(COMMIT_TITLE, "commit_title", text_read(templates.title_fault)),
Scalar(PULL_REQUEST_TITLE, "pull_request_title", text_read(templates.title_fault)),
Scalar(BRANCH, "branch", text_read(templates.branch_fault)),
Scalar(JIRA_FINDING_TYPE, "jira_finding_type", text_read(type_fault)),
)
OPTIONAL = tuple(sorted((CODING_CONVENTIONS, ENV_FILE, TOUCH_PREDICTIONS, *JIRA_PLAN_ONLY, *(scalar.name for scalar in SCALARS))))
OPTIONAL = tuple(sorted({CODING_CONVENTIONS, ENV_FILE, TOUCH_PREDICTIONS, *JIRA_PLAN_ONLY, *(scalar.name for scalar in SCALARS)}))
def lies_in(path: pathlib.Path, *places: pathlib.Path) -> bool:
+19 -1
View File
@@ -291,6 +291,24 @@ class LoadTest(ConfigCase):
(self.home / ".claude-projects" / "acme" / "config.toml").write_text(CLIENT + 'jira-finish-transition = "Mark as done"\njira-finish-status = "Done"\n')
self.assertIn("`jira-finish-transition` is set, so `plan` must name a Jira epic; `jira-finish-status` is set, so `plan` must name a Jira epic", self.failure())
def test_a_jira_plan_may_name_the_issue_type_it_files_findings_as_which_is_task_where_left_out(self) -> None:
folder = self.write("acme", JIRA_CLIENT)
left_out = load(self.checkout, self.checkout, self.home)
assert isinstance(left_out, ProjectConfig), left_out
self.assertEqual(left_out.jira_finding_type, "Task")
(folder / "config.toml").write_text(JIRA_CLIENT + 'jira-finding-type = "Feature"\n')
named = load(self.checkout, self.checkout, self.home)
assert isinstance(named, ProjectConfig), named
self.assertEqual(named.jira_finding_type, "Feature")
def test_a_finding_type_that_is_no_name_or_beside_a_plan_in_a_file_fails_naming_it(self) -> None:
folder = self.write("acme", JIRA_CLIENT + 'jira-finding-type = 3\n')
self.assertIn("`jira-finding-type` is 3, not the name Jira shows, such as \"Feature\"", self.failure())
(folder / "config.toml").write_text(JIRA_CLIENT + 'jira-finding-type = " "\n')
self.assertIn("`jira-finding-type` is ' ', not the name Jira shows, such as \"Feature\"", self.failure())
(folder / "config.toml").write_text(CLIENT + 'jira-finding-type = "Feature"\n')
self.assertIn("`jira-finding-type` is set, so `plan` must name a Jira epic", self.failure())
def test_a_jira_plan_holds_the_formula_and_bar_it_scores_by(self) -> None:
self.write("acme", JIRA_CLIENT.replace("jira-score-bar = 1", "jira-score-bar = 0.5"))
named = load(self.checkout, self.checkout, self.home)
@@ -527,7 +545,7 @@ class LoadTest(ConfigCase):
def test_the_failure_for_a_misplaced_env_file_and_a_missing_setting_names_both_and_lists_every_setting(self) -> None:
folder = self.write("acme", "".join(line + "\n" for line in CLIENT.splitlines() if not line.startswith("plan")) + 'env-file = "checkout:.env"\n')
self.assertEqual(self.failure(), f"{folder / 'config.toml'}: `plan` is missing; `env-file` is 'checkout:.env', not {OUTSIDE}. The settings are {', '.join(SETTINGS)}, and optionally branch, coding-conventions, commit-title, env-file, jira-finish-status, jira-finish-transition, jira-score-bar, jira-score-formula, language, merge, notifier, parallel-chunks, pull-request-title, readability-floor, tooling-on-host, touch-predictions and wait-for-approval.")
self.assertEqual(self.failure(), f"{folder / 'config.toml'}: `plan` is missing; `env-file` is 'checkout:.env', not {OUTSIDE}. The settings are {', '.join(SETTINGS)}, and optionally branch, coding-conventions, commit-title, env-file, jira-finding-type, jira-finish-status, jira-finish-transition, jira-score-bar, jira-score-formula, language, merge, notifier, parallel-chunks, pull-request-title, readability-floor, tooling-on-host, touch-predictions and wait-for-approval.")
def test_two_configs_naming_one_checkout_fail_naming_both(self) -> None:
self.write("acme", CLIENT)