Take a project's goals and audience from a Jira epic's description where its config names one
CI / tests (pull_request) Successful in 2m1s
CI / tests (pull_request) Successful in 2m1s
This commit is contained in:
@@ -127,7 +127,7 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
|
||||
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from the premises or the judge's records.
|
||||
- **gate** — the merge gate: the checks a PR passes before it merges.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`, which `~/.claude/bin/project-config goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder.
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`, which `~/.claude/bin/project-config goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder, or in a Jira epic's description, which the loop only reads.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal, for a decision that is theirs. They type a one-line answer there, or `/talk` to open the worker's session there with `claude --resume`. A release ready to cut opens that session at once. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/` and `~/.claude/skills/larv-review/standards/`.
|
||||
|
||||
@@ -113,6 +113,8 @@ 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 only reads such a plan so far. `todo-item add`, `edit`, `move` and `finish` fail, so file, edit and finish its issues in Jira. `rank_todo.py` doesn't rank it, since Jira's backlog does. The four things not supported for a plan outside the checkout, above, are not supported for a plan in Jira either.
|
||||
|
||||
A client that keeps its goals and audience in an epic's description names that epic as the goals file: `goals-and-audience = "jira:https://acme.atlassian.net/browse/ABC-12"`, which may be the plan's own epic. The description needs `## Goals` and `## Audience` as headings, level-2 headings in Jira's editor, and the same `env-file`. The loop only reads it, so edit the description in Jira. Whoever may edit that description sets the premises every worker and judge follows, so keep its edit rights to the people who own the project's goals.
|
||||
|
||||
To name a chunk's branch, worktree, commits and pull request by the issue key, as in `ABC-123` and `ABC-123 - …`, set these three templates, with your Jira project's key in place of `ABC`: `branch = "ABC-{id}"`, `commit-title = "ABC-{id} - {summary}"` and `pull-request-title = "ABC-{id} - {summary}"`. `project-config --help` says how the templates work.
|
||||
|
||||
```sh
|
||||
|
||||
@@ -110,8 +110,8 @@ def same_origin(clone: str, checkout: str) -> Failure | None:
|
||||
|
||||
def clone_plan(clone: str) -> FilePlan:
|
||||
"""The clone's plan, at the path this repo keeps it. ready_release only reads it; FilePlan also takes the files a write would rank it against."""
|
||||
decisions, history = (FileStore(pathlib.Path(clone, path), path) for path in ("docs/decisions.md", "docs/comprehension-history.md"))
|
||||
return FilePlan(pathlib.Path(clone, "todo.md"), "todo.md", pathlib.Path(clone, "README.md"), decisions, history)
|
||||
goals, decisions, history = (FileStore(pathlib.Path(clone, path), path) for path in ("README.md", "docs/decisions.md", "docs/comprehension-history.md"))
|
||||
return FilePlan(pathlib.Path(clone, "todo.md"), "todo.md", goals, decisions, history)
|
||||
|
||||
|
||||
def ready_release(clone: str, ref: str) -> Release | Failure:
|
||||
|
||||
@@ -6,8 +6,8 @@ from git_cli.git_repo import branch_titles, git, top
|
||||
from review_rules.round_titles import cap, round_counts
|
||||
from failure import Failure
|
||||
from chunk_preflight.choices import forge_of
|
||||
from record_store.stores import goals_store, local_file, store
|
||||
from larv_review.history_commands import history_file, places_report
|
||||
from record_store.stores import local_file, store
|
||||
from project_config.main import located, title_templates
|
||||
from review_rules.review_folder import made_review_folder
|
||||
from deploy_release.forge import open_pull, runner
|
||||
@@ -99,7 +99,11 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
decisions = local_file(store(config, "decisions"), folder / "decisions.md")
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, config.paths["goals-and-audience"], starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
# A reviewer reads files, so goals kept in a Jira epic's description are copied into the review folder.
|
||||
goals = local_file(goals_store(config), folder / "goals.md")
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, goals, starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
if rerun and not launch.asked().exists():
|
||||
return Failure(f"no report asked for a rerun of {pass_}'s round {round_}: {launch.asked()} is missing; relaunch before you commit the round's answers")
|
||||
written = write_inputs(launch, base, home)
|
||||
|
||||
@@ -22,13 +22,13 @@ from larv_review.ruling import counted, ruling, split, surplus, votes
|
||||
from larv_review.history_commands import decided, rerank
|
||||
from failure import Failure
|
||||
from plan_store.stores import FilePlan
|
||||
from record_store.stores import FileStore
|
||||
from larv_review.scoring import floor_step, means, under_floor
|
||||
from test_env import isolated_env
|
||||
from release_plan.todo_table import Item, items, NoItemsTable
|
||||
from release_plan.release_standing import LastCut
|
||||
from larv_review.ruling_base import measured_commit
|
||||
from record_store.fakes import MemoryStore
|
||||
from record_store.fakes import MemoryStore
|
||||
from larv_review.seats import score_line, scores, seats_file, SeatsFile
|
||||
from larv_review.owed import shortfall
|
||||
|
||||
@@ -154,7 +154,7 @@ class Seats(unittest.TestCase):
|
||||
def test_checkout_plan_fails_on_a_missing_or_tableless_todo(self):
|
||||
with tempfile.TemporaryDirectory() as checkout:
|
||||
path = pathlib.Path(checkout, "todo.md")
|
||||
plan = FilePlan(path, "todo.md", pathlib.Path(checkout, "README.md"), MemoryStore(), MemoryStore())
|
||||
plan = FilePlan(path, "todo.md", FileStore(pathlib.Path(checkout, "README.md"), None), MemoryStore(), MemoryStore())
|
||||
with self.subTest("missing"):
|
||||
self.assertEqual(checkout_plan(plan).reason, f"the project's plan: {path}: not found; every project keeps a todo.md, and rank_todo.py --help shows one")
|
||||
with self.subTest("no items table"):
|
||||
@@ -932,7 +932,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
# This checkout has no README.md beside its todo.md.
|
||||
ran = self.record_sevens()
|
||||
self.assertEqual(ran.returncode, 1)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: {self.checkout / 'README.md'}: not found", ran.stderr)
|
||||
self.assertIn(f"recorded the run, but rank_todo.py cannot rank {self.checkout / 'todo.md'}: {self.checkout / 'README.md'}: missing or empty", ran.stderr)
|
||||
self.assertIn("not record-scoring again", ran.stderr)
|
||||
self.assertEqual(len(entries((self.checkout / "docs" / "comprehension-history.md").read_text())), 1)
|
||||
|
||||
|
||||
@@ -4,8 +4,9 @@ usage: loop-claude <task>
|
||||
|
||||
Run it anywhere inside a project checkout whose goals file has ## Goals and ## Audience, the
|
||||
premises. The goals file is the one the project's config, ~/.claude-projects/<key>/config.toml, sets
|
||||
as goals-and-audience; `project-config goals-and-audience` prints it. The task runs at the checkout
|
||||
root. Each cycle a worker runs the task. A chunk's first worker prompt also quotes the premises.
|
||||
as goals-and-audience: a file, or a Jira epic whose description holds it. `project-config
|
||||
goals-and-audience` prints where it is. The task runs at the checkout root.
|
||||
Each cycle a worker runs the task. A chunk's first worker prompt also quotes the premises.
|
||||
They, with code health (~/.claude/CLAUDE.md → "Shared goal") ranked first unless the goals file
|
||||
voids it, choose between ways to deliver the chunk's todo.md items, or else the task, and never
|
||||
widen them. A judge then reads the transcript's end, the premises, and the records: the project's
|
||||
|
||||
@@ -1,23 +1,26 @@
|
||||
import pathlib
|
||||
|
||||
from failure import Failure
|
||||
from project_config.main import goals_file
|
||||
from loop_claude.project.text_file import read_utf8
|
||||
from record_store.stores import goals_store
|
||||
from project_config.main import located
|
||||
from release_plan.goals_file import section
|
||||
|
||||
|
||||
def read_premises(root: str, home: pathlib.Path) -> str | Failure:
|
||||
"""The goals file's path, then its ## Goals and ## Audience; the goals file is the one that the config under home of root's project names. A Failure where no config names root's checkout, the file cannot be read, or the file lacks a section, holds one twice or leaves one empty."""
|
||||
path = goals_file(root, home)
|
||||
if isinstance(path, Failure):
|
||||
return Failure(f"{path.reason} - no premises.")
|
||||
text = read_utf8(str(path.parent), path.name, "no premises")
|
||||
"""Where the goals file is kept, then its ## Goals and ## Audience; the goals file is the one that the config under home of root's project names, a file or a Jira epic's description. A Failure where no config names root's checkout, the goals file cannot be read or is empty, or it lacks a section, holds one twice or leaves one empty."""
|
||||
config = located(root, home)
|
||||
if isinstance(config, Failure):
|
||||
return Failure(f"{config.reason} - no premises.")
|
||||
goals = goals_store(config)
|
||||
text = goals.read()
|
||||
if isinstance(text, Failure):
|
||||
return text
|
||||
return Failure(f"{text.reason} - no premises.")
|
||||
if not text:
|
||||
return Failure(f"{goals.label} is missing or empty - no premises.")
|
||||
bodies: list[str] = []
|
||||
for name in ("Goals", "Audience"):
|
||||
body = section(text, name)
|
||||
if isinstance(body, Failure):
|
||||
return Failure(f"{path} {body.reason} - no premises.")
|
||||
return Failure(f"{goals.label} {body.reason} - no premises.")
|
||||
bodies.append(body)
|
||||
return f"{path}:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}"
|
||||
return f"{goals.label}:\n## Goals\n{bodies[0]}\n\n## Audience\n{bodies[1]}"
|
||||
|
||||
@@ -335,8 +335,8 @@ class Premises(unittest.TestCase):
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertRegex(run.raw_stderr, rf"(?m)^{STAMP} .*not a git repository")
|
||||
readmes = {
|
||||
None: "README.md in {root}: No such file or directory - no premises.",
|
||||
b"# P\n## Goals\n1. g\xff\n## Audience\nme\n": "README.md in {root} is not UTF-8 on line 3 - no premises.",
|
||||
None: "{root}/README.md is missing or empty - no premises.",
|
||||
b"# P\n## Goals\n1. g\xff\n## Audience\nme\n": "cannot read {root}/README.md: not UTF-8 on line 3 - no premises.",
|
||||
b"# P\n## Audience\nme\n": "{root}/README.md has no ## Goals heading - no premises.",
|
||||
b"# P\n## Goals\n1. g\n": "{root}/README.md has no ## Audience heading - no premises.",
|
||||
b"# P\n## Goals\n\n## Audience\nme\n": "{root}/README.md has no text under ## Goals - no premises.",
|
||||
@@ -356,7 +356,7 @@ class Premises(unittest.TestCase):
|
||||
(checkout.root / "README.md").mkdir()
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
self.assertEqual(run.stderr.strip(), f"README.md in {checkout.root}: Is a directory - no premises.")
|
||||
self.assertEqual(run.stderr.strip(), f"cannot read {checkout.root}/README.md: Is a directory - no premises.")
|
||||
(checkout.home / ".claude-projects" / "proj" / "config.toml").unlink()
|
||||
run = checkout.run([worker()])
|
||||
self.assertEqual((run.code, run.calls), (1, []))
|
||||
|
||||
@@ -10,10 +10,10 @@ import typing
|
||||
from release_plan.todo_table import BLOCKED_BY, Item, item_details, items, MOVES, NoItemsTable, renames
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import file_at, git, Git
|
||||
from record_store.stores import goals_store, store as record_store, RecordStore
|
||||
from plan_store import markdown_edits
|
||||
from project_config.settings import ProjectConfig
|
||||
from release_plan import ranking
|
||||
from record_store.stores import store as record_store, RecordStore
|
||||
from release_plan.release import Release
|
||||
from text_files.file_writes import replace_file
|
||||
|
||||
@@ -22,8 +22,9 @@ TAGLINE = "Tagline"
|
||||
FIELDS = ("Release", BLOCKED_BY, "Exempt", TAGLINE, "L", "E", "I", "S", MOVES)
|
||||
|
||||
|
||||
# What a missing todo.md's reader is told.
|
||||
# What the reader of a missing todo.md, or of a missing or empty goals file, is told.
|
||||
MISSING = "every project keeps a todo.md, and rank_todo.py --help shows one"
|
||||
GOALS_HINT = "rank_todo.py weighs goals from the goals file the project's config names as goals-and-audience"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -69,10 +70,10 @@ class PlanStore(typing.Protocol):
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class FilePlan:
|
||||
"""A plan kept as a markdown file at path, in the shape `rank_todo.py --help` shows. Every write ranks the file, reading the goals file at goals, the decision log and the comprehension history."""
|
||||
"""A plan kept as a markdown file at path, in the shape `rank_todo.py --help` shows. Every write ranks the file, reading the goals file from goals, the decision log and the comprehension history."""
|
||||
path: pathlib.Path
|
||||
tracked: str | None
|
||||
goals: pathlib.Path
|
||||
goals: RecordStore
|
||||
decisions: RecordStore
|
||||
history: RecordStore
|
||||
|
||||
@@ -128,13 +129,15 @@ class FilePlan:
|
||||
return Written(id_, tuple(f"{self.path}: {line}" for line in ranked.notes + ranked.under_bar))
|
||||
|
||||
def texts(self) -> tuple[str, str, str, str] | Failure:
|
||||
"""What ranking reads: the file, the goals file, the decision log and the comprehension history. The last two are empty when missing; a missing plan or goals file is a Failure."""
|
||||
"""What ranking reads: the file, the goals file, the decision log and the comprehension history. The last two are empty when missing; a missing plan, or a goals file that is missing or empty, is a Failure."""
|
||||
plan = read_text(self.path, MISSING)
|
||||
if isinstance(plan, Failure):
|
||||
return plan
|
||||
goals = read_text(self.goals, "rank_todo.py weighs goals from the file the project's config names as goals-and-audience")
|
||||
goals = self.goals.read()
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
if not goals:
|
||||
return Failure(f"{self.goals.label}: missing or empty; {GOALS_HINT}")
|
||||
decisions = self.decisions.read()
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
@@ -155,7 +158,7 @@ def store(config: ProjectConfig) -> PlanStore:
|
||||
|
||||
def file_plan(config: ProjectConfig, path: pathlib.Path | None = None) -> FilePlan:
|
||||
"""The markdown file config names as its plan, for a tool that works on the file itself, as ranking does. path stands in for the configured one where given."""
|
||||
return FilePlan(path or config.paths["plan"], config.tracked("plan"), config.paths["goals-and-audience"], record_store(config, "decisions"), record_store(config, "comprehension-history"))
|
||||
return FilePlan(path or config.paths["plan"], config.tracked("plan"), goals_store(config), record_store(config, "decisions"), record_store(config, "comprehension-history"))
|
||||
|
||||
|
||||
def held_at(revision: str, plan: PlanStore, cwd: str, run: Git = git) -> Plan | Failure:
|
||||
|
||||
@@ -9,6 +9,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import Epic, ProjectConfig, SETTINGS
|
||||
from failure import Failure
|
||||
from record_store.stores import FileStore
|
||||
from plan_store.contract import FIRST, PlanStoreContract, SECOND
|
||||
from plan_store.jira_epic import JiraPlan
|
||||
from plan_store.fakes import MemoryPlan
|
||||
@@ -33,7 +34,7 @@ class FilePlanContract(PlanStoreContract, unittest.TestCase):
|
||||
def new_store(self) -> stores.FilePlan:
|
||||
(self.folder / "todo.md").write_text(EMPTY)
|
||||
(self.folder / "README.md").write_text(README)
|
||||
return stores.FilePlan(self.folder / "todo.md", "todo.md", self.folder / "README.md", MemoryStore(), MemoryStore())
|
||||
return stores.FilePlan(self.folder / "todo.md", "todo.md", FileStore(self.folder / "README.md", None), MemoryStore(), MemoryStore())
|
||||
|
||||
|
||||
class FilePlan(FilePlanContract):
|
||||
|
||||
@@ -26,6 +26,10 @@ starts with / or ~/. In a worktree, a "checkout:" path is the worktree's own fil
|
||||
Jira's backlog order, and `project-config plan` prints the setting as the config spells it. Such a
|
||||
config must set `env-file`, and that file must hold ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN.
|
||||
|
||||
`goals-and-audience` may name a Jira Cloud epic the same way. Its description is then the goals
|
||||
file, with ## Goals and ## Audience as headings, and the same `env-file` rule holds. It is only
|
||||
read: edit the description in Jira. Reviewers get a copy in the review folder.
|
||||
|
||||
`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
|
||||
@@ -129,8 +133,3 @@ def project() -> ProjectConfig | Failure:
|
||||
"""The config of the project whose checkout holds the current directory, under the user's home."""
|
||||
return located(None, pathlib.Path.home())
|
||||
|
||||
|
||||
def goals_file(directory: str, home: pathlib.Path) -> pathlib.Path | Failure:
|
||||
"""The file holding the premises, `## Goals` and `## Audience`, of the project whose checkout holds directory, as its config under home names it."""
|
||||
config = located(directory, home)
|
||||
return config if isinstance(config, Failure) else config.paths["goals-and-audience"]
|
||||
|
||||
@@ -25,9 +25,12 @@ 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)
|
||||
# What opens a `plan` setting that names a Jira Cloud epic in place of a path: `jira:`, then the epic's address as the browser shows it. `plan` is the one setting that may name something other than a path.
|
||||
# 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. Only `plan` and `goals-and-audience` may name something other than a path; the same spelling serves both, since the setting says what of the epic is meant.
|
||||
JIRA = "jira:"
|
||||
EPIC_SPELLING = '"jira:https://<site>/browse/<epic\'s key>" for a plan kept as a Jira Cloud epic\'s child issues'
|
||||
EPIC_SPELLINGS = {
|
||||
"plan": '"jira:https://<site>/browse/<epic\'s key>" for a plan kept as a Jira Cloud epic\'s child issues',
|
||||
"goals-and-audience": '"jira:https://<site>/browse/<epic\'s key>" for goals and audience kept in a Jira Cloud epic\'s description',
|
||||
}
|
||||
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"
|
||||
|
||||
|
||||
@@ -50,7 +53,7 @@ class Epic:
|
||||
|
||||
@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, except `plan` where the plan is kept in Jira."""
|
||||
"""folder is `~/.claude-projects/<key>`, top is the worktree that asked, and paths holds each of SETTINGS as an absolute path, except `plan` and `goals-and-audience` where they are kept in Jira."""
|
||||
key: str
|
||||
folder: pathlib.Path
|
||||
top: pathlib.Path
|
||||
@@ -64,6 +67,8 @@ class ProjectConfig:
|
||||
branch: str = templates.BRANCH
|
||||
# The epic whose child issues are the plan, where the config's `plan` names one.
|
||||
epic: Epic | None = None
|
||||
# The epic whose description holds the goals and audience, where the config's `goals-and-audience` names one.
|
||||
goals_epic: Epic | None = None
|
||||
|
||||
@property
|
||||
def plan_file(self) -> pathlib.Path | None:
|
||||
@@ -78,7 +83,8 @@ class ProjectConfig:
|
||||
@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}
|
||||
epics = {"plan": self.epic, "goals-and-audience": self.goals_epic}
|
||||
return {name: epic.spelling if (epic := epics.get(name)) else str(self.paths[name]) for name in SETTINGS if epics.get(name) or name in self.paths}
|
||||
|
||||
@property
|
||||
def texts(self) -> dict[str, str]:
|
||||
@@ -116,7 +122,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"))
|
||||
epics = {name: epic_of(values.get(name)) for name in EPIC_SPELLINGS}
|
||||
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)
|
||||
@@ -124,16 +130,16 @@ 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 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"`{name}` is {values[name]!r}, not {SPELLING}" for name, path in paths.items() if path is None and name not in EPIC_SPELLINGS),
|
||||
*(f"`{name}` is {values[name]!r}, not {SPELLING}, or {EPIC_SPELLINGS[name]}" for name in EPIC_SPELLINGS if name in values and paths[name] is None and epics[name] is None),
|
||||
*(f"`{name}` names a Jira epic, so `{ENV_FILE}` must name the file that holds its credentials" for name, epic in epics.items() if epic and ENV_FILE not in values),
|
||||
*([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}, epic=epic)
|
||||
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=epics["plan"], goals_epic=epics["goals-and-audience"])
|
||||
|
||||
|
||||
def epic_of(value: object) -> Epic | None:
|
||||
|
||||
@@ -116,6 +116,38 @@ class LoadTest(ConfigCase):
|
||||
for config in (self.home / ".claude-projects").glob("*/config.toml"):
|
||||
config.unlink()
|
||||
|
||||
def test_goals_and_audience_spelt_as_a_jira_epic_is_no_path(self) -> None:
|
||||
self.write("acme", CLIENT.replace("folder:goals.md", JIRA_PLAN) + 'env-file = "~/acme.env"\n')
|
||||
found = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(found, ProjectConfig), found
|
||||
self.assertEqual((found.goals_epic, found.epic), (Epic("https://acme.atlassian.net", "ABC-12"), None))
|
||||
self.assertEqual(found.places["goals-and-audience"], JIRA_PLAN)
|
||||
self.assertEqual(tuple(found.places), SETTINGS)
|
||||
self.assertNotIn("goals-and-audience", found.paths)
|
||||
|
||||
def test_goals_and_the_plan_may_name_the_same_epic(self) -> None:
|
||||
self.write("acme", JIRA_CLIENT.replace("folder:goals.md", JIRA_PLAN))
|
||||
found = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(found, ProjectConfig), found
|
||||
self.assertEqual(found.goals_epic, found.epic)
|
||||
|
||||
def test_goals_kept_as_a_file_have_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.goals_epic, found.places["goals-and-audience"]), (None, str(folder / "goals.md")))
|
||||
|
||||
def test_goals_in_jira_need_an_env_file(self) -> None:
|
||||
self.write("acme", CLIENT.replace("folder:goals.md", JIRA_PLAN))
|
||||
self.assertIn("`goals-and-audience` names a Jira epic, so `env-file` must name the file that holds its credentials", self.failure())
|
||||
|
||||
def test_goals_that_spell_no_path_and_no_epic_name_both_spellings(self) -> None:
|
||||
self.write("acme", CLIENT.replace("folder:goals.md", "jira:http://acme.atlassian.net/browse/ABC-12") + 'env-file = "~/acme.env"\n')
|
||||
reason = self.failure()
|
||||
self.assertIn("`goals-and-audience` is 'jira:http://acme.atlassian.net/browse/ABC-12', not ", reason)
|
||||
self.assertIn("jira:https://<site>/browse/<epic's key>", reason)
|
||||
self.assertIn("description", reason)
|
||||
|
||||
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"
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
"""A project's goals and audience kept as the description of one Jira Cloud epic, read over Jira's REST API with the plan store's credentials and the adf-codec shim.
|
||||
|
||||
The store only reads: a write is a Failure, so a tool that edits the goals file says to edit the epic in Jira."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
|
||||
from adf_codec.convert import adfs_to_markdown, Refused
|
||||
from plan_store.jira_epic import basic_auth, Http, http_json, ToMarkdown
|
||||
from project_config.settings import Epic
|
||||
from failure import Failure
|
||||
|
||||
READ_ONLY = "goals and audience kept in Jira are only read: edit the epic's description in Jira"
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class EpicDescription:
|
||||
"""The description of epic as markdown, read with the credentials env_file holds."""
|
||||
epic: Epic
|
||||
env_file: pathlib.Path
|
||||
http: Http = http_json
|
||||
to_markdown: ToMarkdown = adfs_to_markdown
|
||||
|
||||
@property
|
||||
def label(self) -> str:
|
||||
return self.epic.spelling
|
||||
|
||||
@property
|
||||
def tracked(self) -> str | None:
|
||||
return None
|
||||
|
||||
def read(self) -> str | Failure:
|
||||
"""The description as markdown; empty where the epic has none."""
|
||||
authorization = basic_auth(self.env_file)
|
||||
if isinstance(authorization, Failure):
|
||||
return authorization
|
||||
key = self.epic.key
|
||||
answer = self.http("GET", f"{self.epic.site}/rest/api/3/issue/{key}?fields=description", authorization, None)
|
||||
if isinstance(answer, Failure):
|
||||
return Failure(f"cannot read the epic {key}: {answer.reason}")
|
||||
fields = answer.get("fields") if isinstance(answer, dict) else None
|
||||
if not isinstance(fields, dict) or "description" not in fields or not isinstance(fields["description"], dict | None):
|
||||
return Failure(f"the epic {key} is not in the shape Jira Cloud's REST API version 3 documents: it holds no description field of a document or null")
|
||||
if fields["description"] is None:
|
||||
return ""
|
||||
texts = self.to_markdown([fields["description"]])
|
||||
if isinstance(texts, Refused):
|
||||
return Failure(f"{key}'s description: {texts.failure.reason}")
|
||||
if isinstance(texts, Failure):
|
||||
return Failure(f"cannot convert {key}'s description to markdown: {texts.reason}")
|
||||
return texts[0]
|
||||
|
||||
def write(self, text: str) -> Failure | None:
|
||||
return Failure(READ_ONLY)
|
||||
@@ -1,6 +1,6 @@
|
||||
"""The one way a tool reads or writes a project's records: through the store its config names for each.
|
||||
|
||||
Each record has its own setting in the config, so a project may keep one record in its wiki and another as a file. The setting's value names the backend. A path names a markdown file, the only backend so far."""
|
||||
Each record has its own setting in the config, so a project may keep one record in its wiki and another as a file. The setting's value names the backend. A path names a markdown file, the only backend of a record so far; the goals file may also be a Jira epic's description, which `goals_store` reads."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
import typing
|
||||
@@ -68,6 +68,17 @@ def store(config: ProjectConfig, record: str) -> RecordStore:
|
||||
return FileStore(config.paths[record], config.tracked(record))
|
||||
|
||||
|
||||
def goals_store(config: ProjectConfig) -> RecordStore:
|
||||
"""The store config names for the goals file, which holds ## Goals and ## Audience: a markdown file, or the description of a Jira epic, which only reads."""
|
||||
if config.goals_epic is None:
|
||||
return FileStore(config.paths["goals-and-audience"], config.tracked("goals-and-audience"))
|
||||
# Imported here, since the Jira store builds on plan_store, which builds on this module.
|
||||
from record_store.jira_description import EpicDescription
|
||||
# load refuses a config that names an epic and no env-file.
|
||||
assert config.env_file is not None
|
||||
return EpicDescription(config.goals_epic, config.env_file)
|
||||
|
||||
|
||||
def held_at(revision: str, record: RecordStore, cwd: str, run: Git = git) -> str | Failure:
|
||||
"""record's text at revision, read in the checkout at cwd, where its commits hold the record; else as it stands. Empty where there is no such record."""
|
||||
return record.read() if record.tracked is None else file_at(revision, record.tracked, cwd, run)
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
import base64
|
||||
import pathlib
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import Epic
|
||||
from record_store.jira_description import EpicDescription
|
||||
from failure import Failure
|
||||
from adf_codec.convert import Refused
|
||||
|
||||
EPIC = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
AUTHORIZATION = "Basic " + base64.b64encode(b"me@example.com:s3cret").decode()
|
||||
GOALS = {"type": "doc", "version": 1, "content": [{"type": "heading", "attrs": {"level": 2}, "content": [{"type": "text", "text": "Goals"}]}]}
|
||||
|
||||
|
||||
class EpicDescriptionTest(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.answer: object = {"key": "ABC-12", "fields": {"description": GOALS}}
|
||||
self.calls: list[tuple[str, str, str, object]] = []
|
||||
self.converted: list[list[dict[str, object]]] = []
|
||||
self.markdown: list[str] | Refused | Failure = ["## Goals\n1. **Achieve:** Ship.\n"]
|
||||
|
||||
def http(self, method: str, url: str, authorization: str, body: object) -> object:
|
||||
self.calls.append((method, url, authorization, body))
|
||||
return self.answer
|
||||
|
||||
def to_markdown(self, documents: list[dict[str, object]]) -> list[str] | Refused | Failure:
|
||||
self.converted.append(documents)
|
||||
return self.markdown
|
||||
|
||||
def store(self) -> EpicDescription:
|
||||
return EpicDescription(EPIC, self.env, self.http, self.to_markdown)
|
||||
|
||||
def test_reads_the_epics_description_as_markdown(self) -> None:
|
||||
self.assertEqual(self.store().read(), "## Goals\n1. **Achieve:** Ship.\n")
|
||||
self.assertEqual(self.calls, [("GET", "https://acme.atlassian.net/rest/api/3/issue/ABC-12?fields=description", AUTHORIZATION, None)])
|
||||
self.assertEqual(self.converted, [[GOALS]])
|
||||
|
||||
def test_is_named_as_the_config_spells_it_and_held_in_no_commit(self) -> None:
|
||||
self.assertEqual((self.store().label, self.store().tracked), ("jira:https://acme.atlassian.net/browse/ABC-12", None))
|
||||
|
||||
def test_an_epic_without_a_description_reads_empty(self) -> None:
|
||||
self.answer = {"key": "ABC-12", "fields": {"description": None}}
|
||||
self.assertEqual(self.store().read(), "")
|
||||
self.assertEqual(self.converted, [])
|
||||
|
||||
def test_an_unreadable_epic_fails_naming_it(self) -> None:
|
||||
self.answer = Failure("HTTP 404: Issue does not exist")
|
||||
found = self.store().read()
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
self.assertIn("HTTP 404", found.reason)
|
||||
|
||||
def test_an_answer_in_another_shape_fails(self) -> None:
|
||||
for answer in ({"key": "ABC-12"}, {"fields": {"description": "text"}}, ["ABC-12"]):
|
||||
with self.subTest(answer):
|
||||
self.answer = answer
|
||||
found = self.store().read()
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
|
||||
def test_a_description_the_shim_refuses_fails(self) -> None:
|
||||
for markdown in (Refused(0, Failure("an unsupported node")), Failure("docker is not running")):
|
||||
with self.subTest(markdown):
|
||||
self.markdown = markdown
|
||||
found = self.store().read()
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("ABC-12", found.reason)
|
||||
|
||||
def test_missing_credentials_fail(self) -> None:
|
||||
self.env.unlink()
|
||||
self.assertIsInstance(self.store().read(), Failure)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
def test_writing_fails_since_the_store_only_reads(self) -> None:
|
||||
found = self.store().write("## Goals\n")
|
||||
assert isinstance(found, Failure), found
|
||||
self.assertIn("Jira", found.reason)
|
||||
self.assertEqual(self.calls, [])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -6,9 +6,10 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from project_config.settings import Epic, ProjectConfig
|
||||
from record_store.jira_description import EpicDescription
|
||||
from failure import Failure
|
||||
from record_store.fakes import MemoryStore
|
||||
from project_config.settings import ProjectConfig
|
||||
from record_store.contract import RecordStoreContract
|
||||
from record_store import stores
|
||||
|
||||
@@ -171,5 +172,17 @@ class Store(unittest.TestCase):
|
||||
self.assertEqual(str(refused.exception), "plan is not a record; the records are decisions, score-anchors, comprehension-history, reading-cost, changelog")
|
||||
|
||||
|
||||
class GoalsStore(unittest.TestCase):
|
||||
def test_goals_kept_as_a_file_are_that_file(self):
|
||||
top = pathlib.Path("/code/acme")
|
||||
store = stores.goals_store(ProjectConfig("acme", pathlib.Path("/home/me/.claude-projects/acme"), top, {"goals-and-audience": top / "README.md"}))
|
||||
self.assertEqual((store.label, store.tracked), ("/code/acme/README.md", "README.md"))
|
||||
|
||||
def test_goals_kept_in_jira_are_the_epics_description(self):
|
||||
epic = Epic("https://acme.atlassian.net", "ABC-12")
|
||||
store = stores.goals_store(ProjectConfig("acme", pathlib.Path("/home/me/.claude-projects/acme"), pathlib.Path("/code/acme"), {}, pathlib.Path("/home/me/acme.env"), goals_epic=epic))
|
||||
self.assertEqual(store, EpicDescription(epic, pathlib.Path("/home/me/acme.env")))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
@@ -26,7 +26,7 @@ ROW = "| {id} | {release} | | | **Do {id}.** | 1 | 1 | 1 | 1 | 1 | 1 by 1 | 10
|
||||
|
||||
def plan_at(path: pathlib.Path, tracked: str | None) -> FilePlan:
|
||||
"""The markdown plan at path, which these tests only read."""
|
||||
return FilePlan(path, tracked, path.parent / "README.md", MemoryStore(), MemoryStore())
|
||||
return FilePlan(path, tracked, FileStore(path.parent / "README.md", None), MemoryStore(), MemoryStore())
|
||||
|
||||
|
||||
def plan_in(repo: str) -> FilePlan:
|
||||
|
||||
@@ -33,9 +33,9 @@ class Main(unittest.TestCase):
|
||||
self.assertEqual(self.run_main(str(todo)), (0, ""))
|
||||
self.assertEqual(self.run_main("--check", str(todo)), (0, ""))
|
||||
pathlib.Path(temp, "README.md").write_bytes(b"\xff")
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not UTF-8\n"))
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"cannot read {temp}/README.md: not UTF-8 on line 1\n"))
|
||||
pathlib.Path(temp, "README.md").unlink()
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: not found; rank_todo.py weighs goals from the file the project's config names as goals-and-audience\n"))
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{temp}/README.md: missing or empty; rank_todo.py weighs goals from the goals file the project's config names as goals-and-audience\n"))
|
||||
todo.unlink()
|
||||
self.assertEqual(self.run_main(str(todo)), (1, f"{todo}: not found; every project keeps a todo.md, and rank_todo.py --help shows one\n"))
|
||||
|
||||
|
||||
Reference in New Issue
Block a user