This commit is contained in:
@@ -100,6 +100,8 @@ A project's config may set four more things, each optional, as `project-config -
|
||||
|
||||
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
|
||||
|
||||
A client that plans in Jira Cloud names an epic as the plan, as `plan = "jira:https://acme.atlassian.net/browse/ABC-12"`: `jira:` and the epic's address as the browser shows it. The plan is then the epic's open child issues in Jira's backlog order, which the team sets; an issue in a done status is a finished item. An issue's number is the item's ID, so every child lies in the epic's own Jira project, and a read fails naming one that doesn't. The summary is the tagline, the description the detail, the earliest Fix Version named as a semver version the release, and an "is blocked by" link to another open child a blocker. The scores sit in the issue property `plan-item`, a JSON object such as `{"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1.6 by 4", "Exempt": ""}`; an issue without it reads as an item nobody scored yet. The config's `env-file` must hold `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, an API token of that Atlassian account. The loop only reads such a plan so far: `todo-item add`, `edit`, `move` and `finish` fail saying so, `rank_todo.py` refuses it, and rule-hook's rank check skips it. What isn't supported for a plan outside the checkout, below, isn't for a plan in Jira either.
|
||||
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
|
||||
|
||||
```sh
|
||||
@@ -178,7 +180,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
|
||||
- `machine_load/` takes the machine's heavy slots, its shared lock files, for `run_heavy`, and reads the memory share that loop-claude waits for. It also gives `mutate_changes` a slot's CPU count.
|
||||
- `mattermost_dm/` sends the human a Mattermost DM, for `mattermost-dm` and for loop-claude through `loop_effects`.
|
||||
- `model_routing/` holds the routing ladder, which loop-claude, `rule_hook`, both replay tools and `subagent-rung` read, and the list prices, which `routing_figures` and `transcript_archive` read.
|
||||
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`), with the markdown file's edits in `markdown_edits.py`. `contract.py` holds the tests every backend must pass, and `fakes.py` a plan in memory.
|
||||
- `plan_store/` reads and writes a project's plan through the store the project's config names (`stores.py`), with the markdown file's edits in `markdown_edits.py` and the reader of a Jira epic's child issues in `jira_epic.py`. `contract.py` holds the tests every backend must pass, and `fakes.py` a plan in memory.
|
||||
- `rank_todo.py`, `settings_filter.py` and `statusline.py` are tools of one file each, tested beside them.
|
||||
- `record_store/` reads and writes a project's records, each through the store the project's config names (`stores.py`). `contract.py` holds the tests every backend must pass, and `fakes.py` a store in memory that the tests of other tools use.
|
||||
- `release_plan/` reads `todo.md`'s items table and release versions, says which release is next and whether it is ready to cut (`release_standing.py`), and ranks the plan (`ranking.py`, with its score formula in `formula.py` and its blocker order in `blockers.py`). `goals_file.py` reads the goals file's sections, goals and goal weights, for the ranking and for `loop_claude`'s premises, and `citations.py` holds `todo.md` and `docs/decisions.md` to each other. `plan_file.py` ranks, checks and writes a `todo.md`, for `larv_review`, `rank_todo.py` and `rule_hook`.
|
||||
|
||||
@@ -28,7 +28,7 @@ def unsupported(checkout: str | None, home: pathlib.Path, run: Git = git) -> str
|
||||
def held(config: ProjectConfig, name: str) -> tuple[str, str | None]:
|
||||
"""What a message calls the plan or the record that setting name names in config, and its path from the checkout's top, None where it is kept elsewhere."""
|
||||
if name == "plan":
|
||||
return str(config.paths[name]), config.tracked(name)
|
||||
return config.plan_label, config.tracked(name)
|
||||
record = store(config, name)
|
||||
return record.label, record.tracked
|
||||
|
||||
|
||||
@@ -20,12 +20,12 @@ def cut_name(cut: LastCut) -> str | None:
|
||||
return None if headed is None else f"{version(headed)} (dated in CHANGELOG.md)"
|
||||
|
||||
|
||||
def plan_name(default: str, outside: pathlib.Path | None) -> str:
|
||||
"""How the preflight names the plan it read: the default branch's todo.md, or the file, where the project's config puts it outside the checkout."""
|
||||
return str(outside) if outside else f"{default}'s todo.md"
|
||||
def plan_name(default: str, outside: str | None) -> str:
|
||||
"""How the preflight names the plan it read: the default branch's todo.md, or the file or Jira epic, where the project's config puts it outside the checkout."""
|
||||
return outside if outside else f"{default}'s todo.md"
|
||||
|
||||
|
||||
def planned(todo: plan_stores.Plan | Failure, cut: LastCut, default: str, branch: str, outside: pathlib.Path | None = None) -> Plan | NoItem:
|
||||
def planned(todo: plan_stores.Plan | Failure, cut: LastCut, default: str, branch: str, outside: str | None = None) -> Plan | NoItem:
|
||||
"""todo, which is the project's plan as its store read it and which plan_name names, with the item the next chunk takes first, release_standing.chunk_item's pick; else why there is none. branch is the project's `branch` template."""
|
||||
where = plan_name(default, outside)
|
||||
if isinstance(todo, NoItemsTable):
|
||||
|
||||
@@ -17,7 +17,7 @@ def render(found: Gathered) -> list[str]:
|
||||
note = [f"- {found.note}"] if found.note else []
|
||||
unseen = [f"- {UNSEEN_RELEASES}"] if found.plan_outside else []
|
||||
head = [*note, f"- {last_release(found.default, found.cut)}", *unseen]
|
||||
paths = f"- The project's config puts its files at: {'; '.join(f'{setting} {path}' for setting, path in found.paths.items())}."
|
||||
paths = f"- The project's config puts its files at: {'; '.join(f'{setting} {path}' for setting, path in found.places.items())}."
|
||||
texts = f"- The project's config sets: {'; '.join(f'{setting} {text}' for setting, text in found.texts.items())}."
|
||||
if isinstance(found.item, NoItem):
|
||||
return [*head, f"- No plan item: {found.item.why} No worktree was made.", paths, texts]
|
||||
|
||||
@@ -82,7 +82,7 @@ class Gathered:
|
||||
# The plan that was read, as choices.plan_name names it.
|
||||
plan: str
|
||||
# Each path the project's config sets, by its setting: in the item's worktree where one was made or continued, else in the checkout.
|
||||
paths: dict[str, pathlib.Path]
|
||||
places: dict[str, str]
|
||||
# Whether the project's config puts the plan outside the checkout, where a release whose items are all done is not seen.
|
||||
plan_outside: bool
|
||||
# The language and the templates the project's config names, by their settings.
|
||||
|
||||
@@ -127,13 +127,13 @@ def preflight(root: pathlib.Path, timeout: float, make: bool) -> list[str] | Fai
|
||||
config = located(str(root), pathlib.Path.home())
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
outside = None if config.tracked("plan") else config.paths["plan"]
|
||||
outside = None if config.tracked("plan") else config.plan_label
|
||||
held = project_plan(config, ref, str(root))
|
||||
plan = planned(held.todo, held.cut, ref, config.branch, outside)
|
||||
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make)
|
||||
# A `checkout:` path lands in the worktree the chunk works in.
|
||||
made = located(str(item.worktree.path), pathlib.Path.home()) if isinstance(item, ItemFacts) and isinstance(item.worktree, Worktree) else config
|
||||
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).paths, outside is not None, config.texts))
|
||||
return render(Gathered(ref, note, held.cut, item, plan_name(ref, outside), (config if isinstance(made, Failure) else made).places, outside is not None, config.texts))
|
||||
|
||||
|
||||
def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float, make: bool) -> ItemFacts:
|
||||
|
||||
@@ -80,7 +80,10 @@ def rerank(home: pathlib.Path, warn: Say) -> Failure | None:
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
todo = config.paths["plan"]
|
||||
todo = config.plan_file
|
||||
if todo is None:
|
||||
# A plan in Jira is ranked by Jira's backlog, which no score moves.
|
||||
return None
|
||||
ranked = plan_file.rank_file(todo, config)
|
||||
if isinstance(ranked, Failure):
|
||||
return Failure(f"recorded the run, but rank_todo.py cannot rank {todo}: {ranked.reason}. Fix what that names, then run rank_todo.py on {todo}, not record-scoring again")
|
||||
|
||||
@@ -26,7 +26,7 @@ def owed_scoring_run(default: str, home: pathlib.Path, warn: typing.Callable[[st
|
||||
record = store(config, "comprehension-history")
|
||||
plan, history = config.tracked("plan"), record.tracked
|
||||
if plan is None or history is None:
|
||||
name, where = ("plan", str(config.paths["plan"])) if plan is None else ("comprehension history", record.label)
|
||||
name, where = ("plan", config.plan_label) if plan is None else ("comprehension history", record.label)
|
||||
warn(f"larv-review doesn't support a {name} outside the checkout, so it cannot tell whether the chunk owes a scoring run: {where}")
|
||||
return None
|
||||
base = git("merge-base", default, "HEAD", cwd=checkout)
|
||||
|
||||
@@ -100,7 +100,7 @@ def plan_reasons(ref: str, ids: list[int] | None, home: pathlib.Path) -> list[st
|
||||
ids = sorted({item.id for item in planned} - {item.id for item in chunk})
|
||||
# A plan outside the checkout is read as it stands for both plans, so a finished item is in neither.
|
||||
if config.tracked("plan") is None and (gone := sorted(set(ids) - {item.id for item in chunk})):
|
||||
return Failure(f"todo.md as it stands holds no item {', '.join(map(str, gone))}, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {config.paths['plan']}")
|
||||
return Failure(f"todo.md as it stands holds no item {', '.join(map(str, gone))}, and larv-review doesn't support a plan outside the checkout, so it cannot read the plan as it stood before the item was finished: {config.plan_label}")
|
||||
return scoring_run_due(planned, chunk, ids, landed_release, renamed, unmeasured)
|
||||
|
||||
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import contextlib
|
||||
import decimal
|
||||
import itertools
|
||||
import json
|
||||
@@ -16,8 +17,9 @@ from larv_review.agreement import agreement_report, ruling_agreement, run_agreem
|
||||
from review_rules.comprehension_history import appended, entries, HistoryChange, latest_places, Place, recorded, ruling_entry, scoring_entry, ScoringRun, Seat
|
||||
from larv_review.plan import checkout_plan, EMPTIED_WORDS, landed_towards, plan_reasons, scoring_run_due
|
||||
from review_rules import comprehension_history
|
||||
from project_config.test_project_config import configured
|
||||
from larv_review.ruling import counted, ruling, split, surplus, votes
|
||||
from larv_review.history_commands import decided
|
||||
from larv_review.history_commands import decided, rerank
|
||||
from failure import Failure
|
||||
from plan_store.stores import FilePlan
|
||||
from larv_review.scoring import floor_step, means, under_floor
|
||||
@@ -942,6 +944,18 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
def test_a_plan_in_jira_is_not_reranked(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
checkout = pathlib.Path(temp, "acme")
|
||||
checkout.mkdir()
|
||||
config = configured(self, checkout) / "config.toml"
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"jira:https://acme.atlassian.net/browse/ABC-12"') + 'env-file = "~/acme.env"\n')
|
||||
(checkout / "todo.md").write_text("the owners' own notes\n")
|
||||
self.enterContext(contextlib.chdir(checkout))
|
||||
said: list[str] = []
|
||||
self.assertIsNone(rerank(pathlib.Path.home(), said.append))
|
||||
self.assertEqual((said, (checkout / "todo.md").read_text()), ([], "the owners' own notes\n"))
|
||||
|
||||
def test_reranks_todo_md_by_the_overall_it_records(self):
|
||||
self.plan()
|
||||
ran = self.record_sevens()
|
||||
|
||||
@@ -0,0 +1,213 @@
|
||||
"""A plan kept as the child issues of one Jira Cloud epic, read over Jira's REST API.
|
||||
|
||||
An item is an open child issue. Its ID is the issue's number, so the epic's children all lie in the epic's own Jira project: ABC-34 is item 34 of the plan under ABC-12. The summary is the tagline, the description the detail, the earliest Fix Version the release, and an "is blocked by" link a blocker. L, E, I, S, Moves and Exempt sit in one issue property, PROPERTY, which needs no Jira admin to set up; an issue a teammate filed holds none, and reads as an item without scores.
|
||||
|
||||
The store only reads so far: every write is a Failure."""
|
||||
import base64
|
||||
import concurrent.futures
|
||||
import dataclasses
|
||||
import http.client
|
||||
import json
|
||||
import pathlib
|
||||
import re
|
||||
import typing
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
from adf_codec.convert import adf_to_markdown
|
||||
from failure import Failure
|
||||
from mattermost_dm.dm import parse_env
|
||||
from plan_store.markdown_edits import bold_cell
|
||||
from plan_store.stores import Plan, Written
|
||||
from project_config.settings import Epic
|
||||
from release_plan.release import parsed, Release, tagged
|
||||
from release_plan.todo_table import is_exempt, Item, MOVES, parse_moves, parse_scores, SHAPE
|
||||
|
||||
# One pair of keys for Jira and Confluence, which one Atlassian account's API token opens both.
|
||||
KEYS = ("ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN")
|
||||
# The issue property that holds an item's scores, as a JSON object such as {"L": 2, "E": 2, "I": 3, "S": 3, "Moves": "1.6 by 4", "Exempt": ""}.
|
||||
PROPERTY = "plan-item"
|
||||
# Seconds each connect and each read may wait.
|
||||
TIMEOUT = 30
|
||||
PAGE = 100
|
||||
# The pages one read asks for at most, so an answer that never names a last page ends the read.
|
||||
MAX_PAGES = 100
|
||||
# The adf-codec containers run at once: each description is one run.
|
||||
CONVERSIONS = 8
|
||||
READ_ONLY = "a plan in Jira is only read so far: file, edit and finish its issues in Jira"
|
||||
|
||||
# Sends a request with the Authorization header given, the body as JSON, and returns the JSON answer, or a Failure saying why there is none.
|
||||
Http = typing.Callable[[str, str, str, object], object]
|
||||
ToMarkdown = typing.Callable[[dict[str, typing.Any]], str | Failure]
|
||||
|
||||
|
||||
class NoRedirect(urllib.request.HTTPRedirectHandler):
|
||||
"""Refuses every redirect, which Jira's API never sends: urllib would resend the credentials to the new location, even one off https."""
|
||||
|
||||
def redirect_request(self, *args: typing.Any, **kwargs: typing.Any) -> None:
|
||||
return None
|
||||
|
||||
|
||||
OPENER = urllib.request.build_opener(NoRedirect)
|
||||
|
||||
|
||||
def http_json(method: str, url: str, authorization: str, body: object) -> object:
|
||||
"""The JSON that url answers; a Failure naming the request where it answers an error, breaks HTTP or answers something other than JSON, and saying so where the site cannot be reached."""
|
||||
request_name = f"{method} {urllib.parse.urlsplit(url).path}"
|
||||
request = urllib.request.Request(url, json.dumps(body).encode(), {"Authorization": authorization, "Content-Type": "application/json", "Accept": "application/json"}, method=method)
|
||||
try:
|
||||
with OPENER.open(request, timeout=TIMEOUT) as response:
|
||||
raw = response.read()
|
||||
except urllib.error.HTTPError as failure:
|
||||
with failure:
|
||||
return Failure(f"{request_name} answered {failure.code}: {failure.reason}")
|
||||
except http.client.HTTPException as failure:
|
||||
return Failure(f"{request_name} got a broken answer: {failure!r}")
|
||||
except (OSError, ValueError) as failure:
|
||||
return Failure(f"cannot be reached: {getattr(failure, 'reason', failure)}")
|
||||
try:
|
||||
return json.loads(raw)
|
||||
except ValueError:
|
||||
return Failure(f"{request_name} answered with something other than JSON")
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class JiraPlan:
|
||||
"""The plan under epic, read with the credentials env_file holds."""
|
||||
epic: Epic
|
||||
env_file: pathlib.Path
|
||||
http: Http = http_json
|
||||
to_markdown: ToMarkdown = adf_to_markdown
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
return self.epic.spelling
|
||||
|
||||
@property
|
||||
def tracked(self) -> str | None:
|
||||
return None
|
||||
|
||||
def read(self) -> Plan | Failure:
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
issues = children(self.epic, authorization, self.http)
|
||||
if isinstance(issues, Failure):
|
||||
return Failure(f"{self.epic.site}: {issues.reason}")
|
||||
try:
|
||||
return plan_of(issues, self.epic, self.to_markdown)
|
||||
except (AttributeError, KeyError, TypeError):
|
||||
return Failure(f"{self.epic.site} answered issues in another shape than Jira Cloud's REST API version 3 documents")
|
||||
|
||||
def add(self, fields: dict[str, str], detail: str) -> Written | Failure:
|
||||
return Failure(READ_ONLY)
|
||||
|
||||
def edit(self, id_: int, fields: dict[str, str], detail: str | None) -> Written | Failure:
|
||||
return Failure(READ_ONLY)
|
||||
|
||||
def finish(self, id_: int) -> Written | Failure:
|
||||
return Failure(READ_ONLY)
|
||||
|
||||
|
||||
def basic_auth(env_file: pathlib.Path) -> str | Failure:
|
||||
"""The Authorization header for the email and API token that env_file's KEY=value lines hold."""
|
||||
try:
|
||||
mode = env_file.stat().st_mode
|
||||
text = env_file.read_text(encoding="utf-8")
|
||||
except FileNotFoundError:
|
||||
return Failure(f"{env_file} does not exist; it needs {' and '.join(KEYS)}")
|
||||
except (OSError, UnicodeDecodeError) as failure:
|
||||
return Failure(f"cannot read {env_file}: {failure}")
|
||||
if mode & 0o077:
|
||||
return Failure(f"{env_file} holds an API token, so only its owner may read it; run chmod 600 {env_file}")
|
||||
values = parse_env(text)
|
||||
if missing := [key for key in KEYS if not values.get(key)]:
|
||||
return Failure(f"{env_file} lacks {' and '.join(missing)}")
|
||||
return "Basic " + base64.b64encode(":".join(values[key] for key in KEYS).encode()).decode()
|
||||
|
||||
|
||||
def children(epic: Epic, authorization: str, http: Http) -> list[dict[str, typing.Any]] | Failure:
|
||||
"""The epic's open child issues in backlog order, which is the order the team ranks them in. An issue in a done status is a finished item, so it is no longer in the plan."""
|
||||
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,
|
||||
}
|
||||
found: list[dict[str, typing.Any]] = []
|
||||
for _ in range(MAX_PAGES):
|
||||
page = http("POST", f"{epic.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):
|
||||
return Failure("the search answered something other than a page of issues")
|
||||
found += page["issues"]
|
||||
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")
|
||||
|
||||
|
||||
def plan_of(issues: list[dict[str, typing.Any]], epic: Epic, to_markdown: ToMarkdown) -> Plan | Failure:
|
||||
"""The plan the issues hold, in their order. Raises AttributeError, KeyError or TypeError where an issue is not in the shape Jira documents."""
|
||||
project = epic.key.rpartition("-")[0]
|
||||
if strangers := [issue["key"] for issue in issues if not re.fullmatch(rf"{re.escape(project)}-[0-9]+", issue["key"])]:
|
||||
return Failure(f"{strangers[0]} is a child of {epic.key} in another Jira project, and an item's ID is its number in {project}; move it into {project} or out of the epic")
|
||||
ids = {number(issue["key"]) for issue in issues}
|
||||
with concurrent.futures.ThreadPoolExecutor(CONVERSIONS) as pool:
|
||||
details = list(pool.map(lambda issue: detail(issue, to_markdown), issues))
|
||||
items = [item(issue, ids, text) for issue, text in zip(issues, details)]
|
||||
return next((found for found in items if isinstance(found, Failure)), None) or Plan([found for found in items if isinstance(found, Item)])
|
||||
|
||||
|
||||
def number(key: str) -> int:
|
||||
return int(key.rpartition("-")[2])
|
||||
|
||||
|
||||
def detail(issue: dict[str, typing.Any], to_markdown: ToMarkdown) -> str | Failure:
|
||||
"""The issue's description as markdown; empty where it has none."""
|
||||
description = issue["fields"]["description"]
|
||||
if description is None:
|
||||
return ""
|
||||
text = to_markdown(description)
|
||||
return Failure(f"{issue['key']}'s description: {text.reason}") if isinstance(text, Failure) else text.strip()
|
||||
|
||||
|
||||
def item(issue: dict[str, typing.Any], ids: set[int], text: str | Failure) -> Item | Failure:
|
||||
"""The item an issue holds, blocked by each of its blockers among ids, the plan's items: a blocker that is done or lies outside the epic doesn't make the item wait."""
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
key, fields = issue["key"], issue["fields"]
|
||||
release = earliest_release([version["name"] for version in fields["fixVersions"]])
|
||||
if release is None:
|
||||
# Until a project can tie its releases to something other than semver versions, an item with no release cannot be placed in the plan.
|
||||
return Failure(f"{key} names no Fix Version that is a semver version, such as 1.2.0; set one in Jira")
|
||||
blockers = [number(link["inwardIssue"]["key"]) for link in fields["issuelinks"] if link["type"]["inward"] == "is blocked by" and "inwardIssue" in link and link["inwardIssue"]["key"].rpartition("-")[0] == key.rpartition("-")[0]]
|
||||
scored = scores(key, issue.get("properties", {}).get(PROPERTY, {}))
|
||||
if isinstance(scored, Failure):
|
||||
return scored
|
||||
return Item(number(key), release, scored[2], bold_cell(fields["summary"].strip()), scored[0], scored[1], tuple(sorted(set(blockers) & ids)), text)
|
||||
|
||||
|
||||
def earliest_release(names: list[str]) -> Release | None:
|
||||
"""The earliest release among Fix Versions named as a semver version, with a leading v or without; None where none is."""
|
||||
releases = [release for name in names if (release := parsed(name) or tagged(name))]
|
||||
return min(releases, default=None)
|
||||
|
||||
|
||||
def scores(key: str, held: object) -> tuple[dict[str, int], typing.Any, typing.Any] | Failure:
|
||||
"""The scores, Moves and Exempt that an issue's PROPERTY value holds, each in the format the items table of a todo.md takes."""
|
||||
if not isinstance(held, dict):
|
||||
return Failure(f"{key}'s issue property {PROPERTY} is not a JSON object")
|
||||
named = {name: str(value) for name, value in held.items()}
|
||||
levels = parse_scores(key, named, SHAPE.score_columns)
|
||||
if isinstance(levels, Failure):
|
||||
return levels
|
||||
moves = parse_moves(key, named.get(MOVES, ""))
|
||||
if isinstance(moves, Failure):
|
||||
return moves
|
||||
exempt = named.get("Exempt", "")
|
||||
if not is_exempt(exempt):
|
||||
return Failure(f"item {key}'s Exempt {exempt!r} is not one a todo.md's items table takes")
|
||||
return levels, moves, exempt
|
||||
@@ -1,6 +1,6 @@
|
||||
"""The one way a tool reads or writes a project's plan: through the store its config names.
|
||||
|
||||
The config's `plan` setting names the backend. A path names a markdown file, todo.md, the only backend so far. An agent reads and changes the plan with `todo-item`, which works through the same store.
|
||||
The config's `plan` setting names the backend. A path names a markdown file, todo.md. A Jira epic names its child issues, which `jira_epic` reads and nothing writes yet. An agent reads and changes the plan with `todo-item`, which works through the same store.
|
||||
|
||||
A tool that reads what a past commit held, such as `score-outcomes`, still parses that commit's todo.md itself, with `release_plan.todo_table`: only the markdown backend has commits, and todo.md's items 365, 366 and 368 port those tools to the other backends."""
|
||||
import dataclasses
|
||||
@@ -144,7 +144,13 @@ class FilePlan:
|
||||
|
||||
def store(config: ProjectConfig) -> PlanStore:
|
||||
"""The store config names for the plan."""
|
||||
return file_plan(config)
|
||||
if config.epic is None:
|
||||
return file_plan(config)
|
||||
# Imported here, since jira_epic builds on this module's Plan and Written.
|
||||
from plan_store.jira_epic import JiraPlan
|
||||
# load refuses a config that names an epic and no env-file.
|
||||
assert config.env_file is not None
|
||||
return JiraPlan(config.epic, config.env_file)
|
||||
|
||||
|
||||
def file_plan(config: ProjectConfig, path: pathlib.Path | None = None) -> FilePlan:
|
||||
|
||||
@@ -0,0 +1,165 @@
|
||||
import base64
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from plan_store import jira_epic
|
||||
from plan_store.stores import Plan
|
||||
from project_config.settings import Epic
|
||||
from release_plan.release import release_of
|
||||
|
||||
EPIC = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
SEARCH = "https://acme.atlassian.net/rest/api/3/search/jql"
|
||||
|
||||
|
||||
def issue(key: str, summary: str = "Count the runs.", versions: tuple[str, ...] = ("0.1.0",), scores: dict[str, object] | None = None, blocked_by: tuple[str, ...] = (), description: object = None, blocks: tuple[str, ...] = ()) -> dict[str, object]:
|
||||
links = [{"type": {"inward": "is blocked by", "outward": "blocks"}, "inwardIssue": {"key": blocker}} for blocker in blocked_by]
|
||||
links += [{"type": {"inward": "is blocked by", "outward": "blocks"}, "outwardIssue": {"key": blocked}} for blocked in blocks]
|
||||
return {
|
||||
"key": key,
|
||||
"fields": {"summary": summary, "description": description, "fixVersions": [{"name": name} for name in versions], "issuelinks": links},
|
||||
"properties": {} if scores is None else {jira_epic.PROPERTY: scores},
|
||||
}
|
||||
|
||||
|
||||
def adf(text: str) -> dict[str, object]:
|
||||
return {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": text}]}]}
|
||||
|
||||
|
||||
def text_of(document: dict[str, object]) -> str | Failure:
|
||||
"""Stands in for the adf-codec shim: the text of the one paragraph adf builds."""
|
||||
return document["content"][0]["content"][0]["text"] + "\n" # type: ignore[index]
|
||||
|
||||
|
||||
class JiraPlan(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.env = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "acme.env"
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\nATLASSIAN_API_TOKEN=s3cret\n")
|
||||
self.env.chmod(0o600)
|
||||
self.pages: list[object] = []
|
||||
self.calls: list[tuple[str, str, str, object]] = []
|
||||
|
||||
def http(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
self.calls.append((method, url, authorization, body))
|
||||
return self.pages[len(self.calls) - 1]
|
||||
|
||||
def store(self) -> jira_epic.JiraPlan:
|
||||
return jira_epic.JiraPlan(EPIC, self.env, self.http, text_of)
|
||||
|
||||
def read(self, *issues: dict[str, object]) -> Plan | Failure:
|
||||
self.pages, self.calls = [{"issues": list(issues)}], []
|
||||
return self.store().read()
|
||||
|
||||
def items(self, *issues: dict[str, object]):
|
||||
plan = self.read(*issues)
|
||||
assert isinstance(plan, Plan), plan
|
||||
return plan.items
|
||||
|
||||
def test_an_epic_with_no_open_child_reads_as_an_empty_plan(self):
|
||||
self.assertEqual(self.read(), Plan([]))
|
||||
|
||||
def test_asks_for_the_epics_open_children_in_backlog_order_with_basic_auth(self):
|
||||
self.read()
|
||||
method, url, authorization, body = self.calls[0]
|
||||
self.assertEqual((method, url), ("POST", SEARCH))
|
||||
self.assertEqual(authorization, "Basic " + base64.b64encode(b"me@example.com:s3cret").decode())
|
||||
self.assertEqual(body["jql"], 'parent = "ABC-12" AND statusCategory != Done ORDER BY Rank ASC') # type: ignore[index]
|
||||
self.assertEqual(body["properties"], [jira_epic.PROPERTY]) # type: ignore[index]
|
||||
|
||||
def test_an_issue_reads_as_an_item_under_its_number(self):
|
||||
scores = {"L": 1, "E": 2, "I": 3, "S": 1, "Moves": "1 by 9", "Exempt": "owner"}
|
||||
item, = self.items(issue("ABC-34", "Count the runs.", ("0.1.0",), scores, description=adf("Why it counts.")))
|
||||
self.assertEqual((item.id, item.release, item.tagline, item.detail), (34, release_of("0.1.0"), "**Count the runs.**", "Why it counts."))
|
||||
self.assertEqual((item.scores, item.moves, item.exempt, item.blocked_by), ({"L": 1, "E": 2, "I": 3, "S": 1}, (("1", 9),), "owner", ()))
|
||||
|
||||
def test_keeps_jiras_order_whatever_the_releases_and_scores(self):
|
||||
found = self.items(issue("ABC-40", versions=("0.2.0",)), issue("ABC-7", versions=("0.1.0",)), issue("ABC-21", versions=("0.3.0",)))
|
||||
self.assertEqual([item.id for item in found], [40, 7, 21])
|
||||
|
||||
def test_an_issue_nobody_scored_reads_without_scores(self):
|
||||
item, = self.items(issue("ABC-34"))
|
||||
self.assertEqual((item.scores, item.moves, item.exempt, item.detail, item.likelihood), ({}, (), "", "", 0))
|
||||
|
||||
def test_an_issue_is_blocked_by_each_blocker_still_in_the_plan(self):
|
||||
blocked, _ = self.items(issue("ABC-34", blocked_by=("ABC-35", "ABC-2", "OTHER-9"), blocks=("ABC-35",)), issue("ABC-35", blocks=("ABC-34",)))
|
||||
self.assertEqual(blocked.blocked_by, (35,))
|
||||
|
||||
def test_the_release_is_the_earliest_fix_version_with_or_without_a_v(self):
|
||||
item, = self.items(issue("ABC-34", versions=("v1.2.0", "0.9.1", "Later")))
|
||||
self.assertEqual(item.release, release_of("0.9.1"))
|
||||
|
||||
def test_an_issue_with_no_semver_fix_version_fails_the_read_naming_it(self):
|
||||
for versions in ((), ("Sprint 4",)):
|
||||
failure = self.read(issue("ABC-34", versions=versions))
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertIn("ABC-34", failure.reason) # type: ignore[union-attr]
|
||||
self.assertIn("Fix Version", failure.reason) # type: ignore[union-attr]
|
||||
|
||||
def test_a_child_in_another_jira_project_fails_the_read_naming_it(self):
|
||||
failure = self.read(issue("ABC-34"), issue("OTHER-5"))
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertIn("OTHER-5", failure.reason) # type: ignore[union-attr]
|
||||
|
||||
def test_scores_out_of_format_fail_the_read_naming_the_issue(self):
|
||||
for scores in ({"L": 9}, {"L": "high"}, {"Moves": "everything"}, {"Exempt": "because"}, "L 3"):
|
||||
failure = self.read(issue("ABC-34", scores=scores)) # type: ignore[arg-type]
|
||||
self.assertIsInstance(failure, Failure, scores)
|
||||
self.assertIn("ABC-34", failure.reason) # type: ignore[union-attr]
|
||||
|
||||
def test_reads_every_page(self):
|
||||
self.pages = [{"issues": [issue("ABC-1")], "nextPageToken": "t1"}, {"issues": [issue("ABC-2")]}]
|
||||
plan = self.store().read()
|
||||
self.assertEqual([item.id for item in plan.items], [1, 2]) # type: ignore[union-attr]
|
||||
self.assertNotIn("nextPageToken", self.calls[0][3]) # type: ignore[operator]
|
||||
self.assertEqual(self.calls[1][3]["nextPageToken"], "t1") # type: ignore[index]
|
||||
|
||||
def test_a_failing_request_fails_the_read(self):
|
||||
self.pages = [Failure("POST /rest/api/3/search/jql answered 401: no")]
|
||||
self.assertEqual(self.store().read(), Failure("https://acme.atlassian.net: POST /rest/api/3/search/jql answered 401: no"))
|
||||
|
||||
def test_an_answer_in_another_shape_fails_the_read(self):
|
||||
for page in ([], {"issues": "none"}, {"issues": [{"key": "ABC-1"}]}, {"issues": [{"key": 7, "fields": {}}]}, {"issues": [issue("ABC-1", summary=None)]}): # type: ignore[arg-type]
|
||||
self.pages, self.calls = [page], []
|
||||
self.assertIsInstance(self.store().read(), Failure, page)
|
||||
|
||||
def test_a_description_the_codec_refuses_fails_the_read_naming_the_issue(self):
|
||||
store = jira_epic.JiraPlan(EPIC, self.env, self.http, lambda document: Failure("adf-codec refused"))
|
||||
self.pages = [{"issues": [issue("ABC-34", description=adf("x"))]}]
|
||||
self.assertEqual(store.read(), Failure("ABC-34's description: adf-codec refused"))
|
||||
|
||||
def test_an_env_file_without_the_credentials_fails_before_any_request(self):
|
||||
self.env.write_text("ATLASSIAN_EMAIL=me@example.com\n")
|
||||
failure = self.read()
|
||||
self.assertIsInstance(failure, Failure)
|
||||
self.assertIn("ATLASSIAN_API_TOKEN", failure.reason) # type: ignore[union-attr]
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_an_env_file_others_may_read_fails_before_any_request(self):
|
||||
self.env.chmod(0o644)
|
||||
self.assertIsInstance(self.read(), Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_a_missing_env_file_fails(self):
|
||||
self.env.unlink()
|
||||
self.assertIsInstance(self.read(), Failure)
|
||||
|
||||
def test_no_failure_holds_the_token(self):
|
||||
self.pages = [{"issues": [issue("OTHER-5")]}]
|
||||
self.assertNotIn("s3cret", self.store().read().reason) # type: ignore[union-attr]
|
||||
|
||||
def test_every_write_fails_since_the_store_only_reads(self):
|
||||
store = self.store()
|
||||
for written in (store.add({}, ""), store.edit(34, {"L": "2"}, None), store.finish(34)):
|
||||
self.assertIsInstance(written, Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_names_itself_by_the_configs_spelling_and_no_commit_holds_it(self):
|
||||
self.assertEqual((self.store().label, self.store().tracked), ("jira:https://acme.atlassian.net/browse/ABC-12", None))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -7,8 +7,10 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import Epic, ProjectConfig, SETTINGS
|
||||
from failure import Failure
|
||||
from plan_store.contract import FIRST, PlanStoreContract, SECOND
|
||||
from plan_store.jira_epic import JiraPlan
|
||||
from plan_store.fakes import MemoryPlan
|
||||
from record_store.fakes import MemoryStore
|
||||
from release_plan.todo_table import NoItemsTable
|
||||
@@ -176,5 +178,21 @@ class HeldAt(unittest.TestCase):
|
||||
self.assertEqual(stores.held_at("origin/main", MemoryPlan(tracked="todo.md"), "/checkout", run), Failure("no git"))
|
||||
|
||||
|
||||
class Store(unittest.TestCase):
|
||||
def config(self, **named) -> ProjectConfig:
|
||||
paths = {name: pathlib.Path("/checkout", name) for name in SETTINGS[1:]}
|
||||
return ProjectConfig("acme", pathlib.Path("/folder"), pathlib.Path("/checkout"), paths, **named)
|
||||
|
||||
def test_a_path_picks_the_markdown_file(self):
|
||||
config = self.config()
|
||||
picked = stores.store(dataclasses.replace(config, paths=config.paths | {"plan": pathlib.Path("/checkout/todo.md")}))
|
||||
self.assertEqual((type(picked), picked.label, picked.tracked), (stores.FilePlan, "/checkout/todo.md", "todo.md"))
|
||||
|
||||
def test_an_epic_picks_jira_with_the_env_files_credentials(self):
|
||||
epic = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
picked = stores.store(self.config(epic=epic, env_file=pathlib.Path("/secrets/acme.env")))
|
||||
self.assertEqual(picked, JiraPlan(epic, pathlib.Path("/secrets/acme.env"), picked.http))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
@@ -21,6 +21,11 @@ starts with / or ~/. In a worktree, a "checkout:" path is the worktree's own fil
|
||||
goals-and-audience = "folder:goals.md"
|
||||
principles = "folder:principles"
|
||||
|
||||
`plan` may name a Jira Cloud epic in place of a path, as "jira:" and the epic's address:
|
||||
"jira:https://acme.atlassian.net/browse/ABC-12". The plan is then the epic's open child issues, in
|
||||
Jira's backlog order, and it is printed as the config spells it. Such a config must set `env-file`,
|
||||
and that file hold ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN.
|
||||
|
||||
`env-file` is an optional setting: the file of KEY=value credentials the project's tools read,
|
||||
a path that starts with / or ~/ and lies outside the checkout and the config's folder, such as
|
||||
"~/.claude-projects/acme-billing.env". Where it is left out, the project has no credentials file, and
|
||||
@@ -81,7 +86,7 @@ def main(argv: list[str]) -> int:
|
||||
if argv and argv[0] in config.texts:
|
||||
print(config.texts[argv[0]])
|
||||
return 0
|
||||
paths = {**config.paths, **({ENV_FILE: config.env_file} if config.env_file else {})}
|
||||
paths = {**config.places, **({ENV_FILE: str(config.env_file)} if config.env_file else {})}
|
||||
if argv and argv[0] not in paths:
|
||||
print(f"{config.folder / CONFIG} sets no `{ENV_FILE}`", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
@@ -25,6 +25,9 @@ COMMIT_TITLE = "commit-title"
|
||||
PULL_REQUEST_TITLE = "pull-request-title"
|
||||
BRANCH = "branch"
|
||||
OPTIONAL = (BRANCH, COMMIT_TITLE, ENV_FILE, LANGUAGE, PULL_REQUEST_TITLE, WAIT_FOR_APPROVAL)
|
||||
# The one setting that may name something other than a path: a plan kept as the child issues of a Jira Cloud epic, spelt as `jira:` and the epic's address as the browser shows it. Three readers, seated as the human who writes the config, picked that spelling from four candidates, and one ATLASSIAN_ pair of env-file keys for Jira and Confluence over a pair for each.
|
||||
JIRA = "jira:"
|
||||
EPIC_SPELLING = '"jira:https://<site>/browse/<epic\'s key>" for a plan kept as a Jira Cloud epic\'s child issues'
|
||||
OUTSIDE = "a path that starts with / or ~/ and lies outside the checkout and the config's folder, so that no git remote receives the credentials"
|
||||
|
||||
|
||||
@@ -33,9 +36,21 @@ class Unnamed(Failure):
|
||||
"""No config names a checkout here: none names the one asked for, or git finds no checkout. A reader of titles takes them bare there, as in a third party's clone; a config that is faulty or cannot be read is a plain Failure."""
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Epic:
|
||||
"""A Jira Cloud epic: site is its site's address, such as https://acme.atlassian.net, and key its issue key, such as ABC-12."""
|
||||
site: str
|
||||
key: str
|
||||
|
||||
@property
|
||||
def spelling(self) -> str:
|
||||
"""The epic as a config's `plan` setting spells it."""
|
||||
return f"{JIRA}{self.site}/browse/{self.key}"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class ProjectConfig:
|
||||
"""folder is `~/.claude-projects/<key>`, top is the worktree that asked, and paths holds each of SETTINGS as an absolute path."""
|
||||
"""folder is `~/.claude-projects/<key>`, top is the worktree that asked, and paths holds each of SETTINGS as an absolute path, but for a plan kept in Jira, which epic holds."""
|
||||
key: str
|
||||
folder: pathlib.Path
|
||||
top: pathlib.Path
|
||||
@@ -47,6 +62,23 @@ class ProjectConfig:
|
||||
commit_title: str = templates.TITLE
|
||||
pull_request_title: str = templates.TITLE
|
||||
branch: str = templates.BRANCH
|
||||
# The epic whose child issues are the plan, where the config's `plan` names one; paths then holds no "plan".
|
||||
epic: Epic | None = None
|
||||
|
||||
@property
|
||||
def plan_file(self) -> pathlib.Path | None:
|
||||
"""The plan's file; None where the plan is kept in Jira."""
|
||||
return self.paths.get("plan")
|
||||
|
||||
@property
|
||||
def plan_label(self) -> str:
|
||||
"""What a message calls the plan: its path, or the epic as the config spells it."""
|
||||
return self.epic.spelling if self.epic else str(self.paths["plan"])
|
||||
|
||||
@property
|
||||
def places(self) -> dict[str, str]:
|
||||
"""Where each of SETTINGS is kept, in SETTINGS' order: a path, or the epic as the config spells it."""
|
||||
return {name: self.plan_label if name == "plan" else str(self.paths[name]) for name in SETTINGS if name == "plan" or name in self.paths}
|
||||
|
||||
@property
|
||||
def texts(self) -> dict[str, str]:
|
||||
@@ -59,7 +91,9 @@ class ProjectConfig:
|
||||
|
||||
def tracked(self, setting: str) -> str | None:
|
||||
"""setting's path from top, as git names a file in a commit; None where the config puts it outside the checkout, whose commits hold no version of it."""
|
||||
path = self.paths[setting]
|
||||
path = self.paths.get(setting)
|
||||
if path is None:
|
||||
return None
|
||||
return path.relative_to(self.top).as_posix() if path.is_relative_to(self.top) else None
|
||||
|
||||
|
||||
@@ -82,6 +116,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
|
||||
return Failure(f"{' and '.join(str(file) for file, _ in named)} each name the checkout {main}; only one config may")
|
||||
file, values = named[0]
|
||||
paths = {name: placed(values[name], top, file.parent, home) for name in SETTINGS if name in values}
|
||||
epic = epic_of(values.get("plan"))
|
||||
env_file = anywhere(values.get(ENV_FILE), home)
|
||||
misplaced = ENV_FILE in values and (env_file is None or lies_in(env_file, top, main, file.parent))
|
||||
waits = values.get(WAIT_FOR_APPROVAL, False)
|
||||
@@ -89,14 +124,22 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
|
||||
faults = [
|
||||
*(f"`{name}` is missing" for name in SETTINGS if name not in values),
|
||||
*(f"`{name}` is not a setting" for name in values if name not in (*SETTINGS, *OPTIONAL)),
|
||||
*(f"`{name}` is {values[name]!r}, not {SPELLING}" for name, path in paths.items() if path is None),
|
||||
*(f"`{name}` is {values[name]!r}, not {SPELLING}" for name, path in paths.items() if path is None and name != "plan"),
|
||||
*([f"`plan` is {values['plan']!r}, not {SPELLING}, or {EPIC_SPELLING}"] if "plan" in values and paths["plan"] is None and epic is None else []),
|
||||
*([f"`plan` names a Jira epic, so `{ENV_FILE}` must name the file that holds its credentials"] if epic and ENV_FILE not in values else []),
|
||||
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, not {OUTSIDE}"] if misplaced else []),
|
||||
*([f"`{WAIT_FOR_APPROVAL}` is {waits!r}, not true or false"] if not isinstance(waits, bool) else []),
|
||||
*(f"`{name}` is {values[name]!r}, {fault}" for name, check in checks.items() if name in values and (fault := check(values[name]))),
|
||||
]
|
||||
if faults:
|
||||
return Failure(f"{file}: {'; '.join(faults)}. The settings are {', '.join(SETTINGS)}, and optionally {', '.join(OPTIONAL[:-1])} and {OPTIONAL[-1]}.")
|
||||
return ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, waits is True, **{name.replace("-", "_"): str(values[name]) for name in checks if name in values})
|
||||
return ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, waits is True, **{name.replace("-", "_"): str(values[name]) for name in checks if name in values}, epic=epic)
|
||||
|
||||
|
||||
def epic_of(value: object) -> Epic | None:
|
||||
"""The epic a `plan` setting's value spells; None where it spells none. Only https, so the credentials are never sent in the clear."""
|
||||
spelt = isinstance(value, str) and re.fullmatch(rf"{JIRA}(https://[A-Za-z0-9.-]+(?::[0-9]+)?)/browse/([A-Z][A-Z0-9_]*-[0-9]+)", value)
|
||||
return Epic(spelt.group(1), spelt.group(2)) if spelt else None
|
||||
|
||||
|
||||
def language_fault(value: object) -> str | None:
|
||||
|
||||
@@ -8,7 +8,7 @@ import unittest.mock
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import env_files, held, load, OUTSIDE, ProjectConfig, SETTINGS, Unnamed
|
||||
from project_config.settings import env_files, Epic, held, load, OUTSIDE, ProjectConfig, SETTINGS, Unnamed
|
||||
from failure import Failure
|
||||
from test_env import isolated_env
|
||||
from project_config.main import title_templates
|
||||
@@ -28,6 +28,9 @@ goals-and-audience = "folder:goals.md"
|
||||
principles = "~/.claude/principles"
|
||||
"""
|
||||
|
||||
JIRA_PLAN = "jira:https://acme.atlassian.net/browse/ABC-12"
|
||||
JIRA_CLIENT = CLIENT.replace("folder:todo.md", JIRA_PLAN) + 'env-file = "~/acme.env"\n'
|
||||
|
||||
|
||||
def write_config(home: pathlib.Path, checkout: pathlib.Path, goals: str = "checkout:README.md") -> pathlib.Path:
|
||||
"""A config under home that names checkout, every setting inside it but goals-and-audience; for the tests of each tool that reads the config."""
|
||||
@@ -83,6 +86,36 @@ class LoadTest(ConfigCase):
|
||||
self.assertEqual(found.paths["principles"], self.home / ".claude" / "principles")
|
||||
self.assertEqual(tuple(found.paths), SETTINGS)
|
||||
|
||||
def test_a_plan_spelt_as_a_jira_epic_is_no_path(self) -> None:
|
||||
self.write("acme", JIRA_CLIENT)
|
||||
found = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(found, ProjectConfig), found
|
||||
self.assertEqual(found.epic, Epic("https://acme.atlassian.net", "ABC-12"))
|
||||
self.assertEqual((found.plan_file, found.tracked("plan"), found.plan_label), (None, None, JIRA_PLAN))
|
||||
self.assertEqual(tuple(found.places), SETTINGS)
|
||||
self.assertEqual(found.places["plan"], JIRA_PLAN)
|
||||
self.assertEqual(tuple(found.paths), SETTINGS[1:])
|
||||
|
||||
def test_a_plan_kept_as_a_file_has_no_epic(self) -> None:
|
||||
folder = self.write("acme", CLIENT)
|
||||
found = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(found, ProjectConfig), found
|
||||
self.assertEqual((found.epic, found.plan_file, found.plan_label, found.places["plan"]), (None, folder / "todo.md", str(folder / "todo.md"), str(folder / "todo.md")))
|
||||
|
||||
def test_a_jira_plan_needs_an_env_file(self) -> None:
|
||||
self.write("acme", JIRA_CLIENT.replace('env-file = "~/acme.env"\n', ""))
|
||||
self.assertIn("`plan` names a Jira epic, so `env-file` must name the file that holds its credentials", self.failure())
|
||||
|
||||
def test_a_plan_that_spells_no_path_and_no_epic_names_both_spellings(self) -> None:
|
||||
for spelled in ("jira:http://acme.atlassian.net/browse/ABC-12", "jira:https://acme.atlassian.net/browse/abc-12", "jira:https://acme.atlassian.net/browse/ABC-12/x", "jira:https://acme.atlassian.net@evil.example/browse/ABC-12", "jira:ABC-12", "https://acme.atlassian.net/browse/ABC-12"):
|
||||
with self.subTest(spelled):
|
||||
self.write(f"acme-{len(spelled)}-{hash(spelled) % 1000}", CLIENT.replace("folder:todo.md", spelled) + 'env-file = "~/acme.env"\n')
|
||||
reason = self.failure()
|
||||
self.assertIn(f"`plan` is {spelled!r}, not ", reason)
|
||||
self.assertIn("jira:https://<site>/browse/<epic's key>", reason)
|
||||
for config in (self.home / ".claude-projects").glob("*/config.toml"):
|
||||
config.unlink()
|
||||
|
||||
def test_a_worktree_finds_the_main_checkouts_config_and_reads_its_own_files(self) -> None:
|
||||
self.write("acme", CLIENT)
|
||||
worktree = self.home / "code" / "acme-billing-item-3"
|
||||
@@ -325,6 +358,11 @@ class EnvFilesTest(ConfigCase):
|
||||
|
||||
|
||||
class ToolTest(ConfigCase):
|
||||
def test_prints_a_jira_plan_as_the_config_spells_it(self) -> None:
|
||||
self.write("acme", JIRA_CLIENT)
|
||||
self.assertEqual(self.run_tool("plan").stdout, JIRA_PLAN + "\n")
|
||||
self.assertEqual(self.run_tool().stdout.splitlines()[0], f"plan: {JIRA_PLAN}")
|
||||
|
||||
def run_tool(self, *args: str, cwd: pathlib.Path | None = None) -> subprocess.CompletedProcess[str]:
|
||||
return subprocess.run([sys.executable, str(TOOL), *args], cwd=cwd or self.checkout, env={**isolated_env(), "HOME": str(self.home)}, capture_output=True, text=True)
|
||||
|
||||
|
||||
+5
-3
@@ -106,10 +106,12 @@ def main(argv: list[str]) -> int:
|
||||
config = located(None, pathlib.Path.home())
|
||||
if isinstance(config, Failure):
|
||||
return fail(config)
|
||||
check, todo = args[0], args[1] or config.paths["plan"]
|
||||
if config.plan_file is None:
|
||||
return fail(Failure(f"rank_todo.py ranks a todo.md, and this checkout's config keeps the plan in Jira, whose backlog ranks it: {config.plan_label}"))
|
||||
check, todo = args[0], args[1] or config.plan_file
|
||||
# The goals, decisions and history are this checkout's project's, so another project's plan would be ranked by them.
|
||||
if todo.resolve() != config.paths["plan"].resolve():
|
||||
return fail(Failure(f"rank_todo.py: {todo} is not the plan this checkout's config names, {config.paths['plan'].resolve()}; run rank_todo.py in the checkout of the project whose plan it is"))
|
||||
if todo.resolve() != config.plan_file.resolve():
|
||||
return fail(Failure(f"rank_todo.py: {todo} is not the plan this checkout's config names, {config.plan_file.resolve()}; run rank_todo.py in the checkout of the project whose plan it is"))
|
||||
if check:
|
||||
failures = plan_file.check_failures(todo, config)
|
||||
for line in failures:
|
||||
|
||||
@@ -1217,6 +1217,14 @@ class TodoRankCheck(unittest.TestCase):
|
||||
(self.config.parent / "todo.md").write_text("# todo\n")
|
||||
self.assertEqual(self.details(checkout), [f"own script checked {self.config.parent}/todo.md"])
|
||||
|
||||
def test_a_plan_in_jira_is_not_checked_in_the_checkout_or_the_configs_folder(self):
|
||||
checkout = self.changed_plan(f"{self.folder}/clone", self.STUB)
|
||||
self.config.write_text(self.config.read_text().replace('"checkout:todo.md"', '"jira:https://acme.atlassian.net/browse/ABC-12"') + 'env-file = "~/acme.env"\n')
|
||||
folder = str(self.config.parent)
|
||||
git(folder, "init", "-q")
|
||||
(self.config.parent / "todo.md").write_text("# todo\n")
|
||||
self.assertEqual((self.details(checkout), self.details(folder)), ([], []))
|
||||
|
||||
def test_a_commit_in_the_configs_folder_checks_the_plan_it_keeps_there_once_it_changes(self):
|
||||
checkout = self.changed_plan(f"{self.folder}/clone", self.STUB)
|
||||
folder = str(self.config.parent)
|
||||
|
||||
@@ -32,9 +32,9 @@ def todo_breaches(directory: str, home: pathlib.Path, own: pathlib.Path = OWN) -
|
||||
# A checkout whose todo.md changes with no config is one whose config is still to write. An unchanged todo.md may be a third party's, whose clone needs no config.
|
||||
unconfigured = pathlib.Path(top) / "todo.md"
|
||||
return [Breach("todo-rank-check", config.reason, top)] if unconfigured.is_file() and changed(top, unconfigured, "todo.md") else []
|
||||
todo, tracked = config.paths["plan"], config.tracked("plan")
|
||||
# A plan outside the checkout has no commit in the checkout to differ from, so it is checked on every call.
|
||||
if not todo.is_file() or (tracked is not None and not changed(top, todo, tracked)):
|
||||
todo, tracked = config.plan_file, config.tracked("plan")
|
||||
# A plan outside the checkout has no commit in the checkout to differ from, so it is checked on every call. A plan in Jira is no file, and Jira's backlog ranks it.
|
||||
if todo is None or not todo.is_file() or (tracked is not None and not changed(top, todo, tracked)):
|
||||
return []
|
||||
return [Breach("todo-rank-check", line, top) for line in check_failures(top, todo, config, own)]
|
||||
|
||||
@@ -43,9 +43,9 @@ def folder_breaches(top: str, config: ProjectConfig | Failure, own: pathlib.Path
|
||||
"""Why the plan kept in top, a config's folder, is not ranked, where the plan has changed in that folder's repo; ranked as for a commit in the project's checkout.
|
||||
|
||||
A config that fails to load doesn't block anything here, so that the commit that fixes it goes through."""
|
||||
if isinstance(config, Failure) or not config.paths["plan"].is_relative_to(config.folder):
|
||||
todo = None if isinstance(config, Failure) else config.plan_file
|
||||
if isinstance(config, Failure) or todo is None or not todo.is_relative_to(config.folder):
|
||||
return []
|
||||
todo = config.paths["plan"]
|
||||
if not todo.is_file() or not changed(str(config.folder), todo, todo.relative_to(config.folder).as_posix()):
|
||||
return []
|
||||
return [Breach("todo-rank-check", line, top) for line in check_failures(str(config.top), todo, config, own)]
|
||||
|
||||
@@ -57,6 +57,17 @@ class Main(unittest.TestCase):
|
||||
(folder / "decisions.md").write_bytes(b"\xff")
|
||||
self.assertEqual(self.run_main(), (1, f"cannot read {folder}/decisions.md: not UTF-8 on line 1\n"))
|
||||
|
||||
def test_refuses_a_project_whose_plan_is_in_jira_and_writes_no_file(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
config = configured(self, pathlib.Path(temp)) / "config.toml"
|
||||
self.enterContext(contextlib.chdir(temp))
|
||||
config.write_text(config.read_text().replace('"checkout:todo.md"', '"jira:https://acme.atlassian.net/browse/ABC-12"') + 'env-file = "~/acme.env"\n')
|
||||
todo = pathlib.Path(temp, "todo.md")
|
||||
todo.write_text(TODO)
|
||||
for args in ((), ("--check",), (str(todo),)):
|
||||
self.assertEqual(self.run_main(*args), (1, "rank_todo.py ranks a todo.md, and this checkout's config keeps the plan in Jira, whose backlog ranks it: jira:https://acme.atlassian.net/browse/ABC-12\n"))
|
||||
self.assertEqual(todo.read_text(), TODO)
|
||||
|
||||
def test_refuses_a_file_that_is_not_the_plan_the_config_names_and_a_checkout_no_config_names(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
folder = configured(self, pathlib.Path(temp))
|
||||
|
||||
@@ -21,6 +21,7 @@ Each project principle states one rule that the decisions below apply; their ent
|
||||
- machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
|
||||
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
|
||||
- project config: a tool that reads a file's commits says where it does not support that file, and the work goes on
|
||||
- project config: `plan` names a Jira Cloud epic as `jira:` and its address, the plan is its open child issues in backlog order, and an issue's number is the item's ID
|
||||
- project config: `language` names the prose's language by its English name, and `commit-title`, `pull-request-title` and `branch` are brace templates over `{id}` and `{summary}`
|
||||
- review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
|
||||
- review: a reviewer or comprehension seat that rules the work below standard may ask to rerun once, one rung up, in the same round; the ruling that stands is an escalation trigger for the worker unless the fix changes only prose, and never for the judge
|
||||
@@ -277,6 +278,17 @@ Valid while the later fixes per finished chunk, which `score-outcomes` and the r
|
||||
|
||||
Messages keep each file's usual name, such as `todo.md`, as its label, since the config keeps the names. Revisit at 0.13.0, which plans the support for `score-outcomes`, the routing figures, the release standing and the owed scoring run.
|
||||
|
||||
## project config: `plan` names a Jira Cloud epic as `jira:` and its address, the plan is its open child issues in backlog order, and an issue's number is the item's ID
|
||||
|
||||
2026-11-14, larv-review, on lilleman's calls of 2026-11-12 and 2026-11-14. Serves goal 1.6: a client's team keeps planning in its own Jira. Valid while a client's plan fits one epic in one Jira project.
|
||||
|
||||
- **One epic is one project's plan, and Jira's backlog rank orders it.** The team sets the rank, so the loop's score doesn't break ties and the loop doesn't reorder anything (lilleman, 2026-11-12). An item is an open child issue; one in a done status category is finished.
|
||||
- **A bench of readers picked the spelling.** Three fresh readers, seated as the person who writes a client's `config.toml`, each picked `plan = "jira:https://<site>/browse/<key>"` over the bare address, a `jira:<key>` beside a `jira-site` key, and a `[plan]` table. Each also picked one pair of env-file keys, `ATLASSIAN_EMAIL` and `ATLASSIAN_API_TOKEN`, for Jira and Confluence over a pair for each, since one account's token opens both.
|
||||
- **An item's ID stays a whole number: the issue's number in the epic's Jira project.** About 30 modules read an ID as an int, and the `branch` and title templates already spell a ticket's name, as `ABC-{id}`. So the store refuses a child issue from another Jira project, and counts a blocker only among the plan's own items (`bin/plan_store/jira_epic.py`).
|
||||
- **The scores sit in one issue property, `plan-item`**, which needs no Jira admin (lilleman, 2026-11-12). An issue without it reads as an item nobody scored.
|
||||
- **The release is the earliest Fix Version named as a semver version**, and an issue with none fails the read, naming it, until todo.md's item 359 ties releases to something else.
|
||||
- **The store only reads**, until todo.md's item 352 writes. A tool that works on the file, such as `rank_todo.py` or rule-hook's rank check, refuses or skips a plan in Jira.
|
||||
|
||||
## project config: `language` names the prose's language by its English name, and `commit-title`, `pull-request-title` and `branch` are brace templates over `{id}` and `{summary}`
|
||||
|
||||
2026-11-14, larv-review. Serves goal 1.6: a client's team reads its docs, Jira text, commits and pull requests in its own language and format. Valid while one language and one template per title serve a project.
|
||||
|
||||
Reference in New Issue
Block a user