253 lines
16 KiB
Python
253 lines
16 KiB
Python
"""Find the mechanical facts a chunk starts from, so its worker starts from them; with --worktree, also make its worktree.
|
|
|
|
usage: chunk-preflight [--worktree] [--item <ID>]
|
|
|
|
Run it inside a project checkout. It fetches origin, when the checkout has that remote, and takes
|
|
origin's default branch, or else the local main or master. Without --worktree, it still fetches,
|
|
but it doesn't make a worktree or a branch, and doesn't run any tool in one. loop-claude runs it
|
|
with --worktree at the checkout root before each chunk's first worker, before it routes the chunk,
|
|
and quotes what it prints in the worker's prompt. It leaves the checkout as it is, and reads
|
|
todo.md as the default branch holds it, the plan loop-claude routes on. Where the project's config
|
|
puts todo.md or CHANGELOG.md outside the checkout, it reads that file as it stands. Such a plan
|
|
no longer names a release whose last item has shipped, so chunk-preflight doesn't see that release,
|
|
and prints that the release reviews and the cuts are the human's to call. It prints:
|
|
|
|
- the last version cut: the newest v* tag on the default branch, or on a branch with no tag the
|
|
newest version CHANGELOG.md heads `## X.Y.Z - YYYY-MM-DD`; an undated heading doesn't count.
|
|
Then how many entries the default branch's CHANGELOG.md holds under ## Unreleased, or else how
|
|
many commits followed the cut: the tag, or the commit that added that heading;
|
|
- under `merge = "human"` (`project-config --help`), each worktree beside the checkout whose pull
|
|
request has merged, for the worker to run `chunk-pr clean` in, and each item passed over: one
|
|
finished on the branch of an open pull request that is not a draft, where the checkout holds
|
|
the plan. Where no item of the release can start and one awaits such a merge, it names those
|
|
pull requests and says the working loop stops there;
|
|
- the next release and its first item that does not wait, the item loop-claude routes on, with its L
|
|
and E + I; with --item <ID>, the plan item of that ID instead, which loop-claude names in a window
|
|
named for an item. An item waits while it is marked question, while an item still in todo.md
|
|
blocks it, or while it awaits such a merge. Where the last cut is a version x.y.z, the next release is the earliest after x.y.z
|
|
that todo.md has named at that cut or since, less a release its ## Renamed section marks renamed.
|
|
Where nothing is cut, it is the earliest release todo.md has ever named, less those renamed, so a
|
|
release whose items are all done still reads as next.
|
|
Where the next release holds no item, it says so, naming it where todo.md named it since the cut:
|
|
its release review due where changes are unreleased (the ## Unreleased entries, or else the
|
|
commits since the cut) and no commit titled `Release review of <release>` followed the tag,
|
|
finished and ready to cut once one did, and else to be planned first. On a branch with no tag,
|
|
such a commit counts only where its <release> is after the version under the dated heading.
|
|
Where todo.md files items under x.y.z or earlier, someone cut a release that still held them:
|
|
they count as the next release, the earliest after x.y.z that todo.md names or has named
|
|
since the cut, and a line says to move them there. Where there is no such release, it says todo.md files items under a release
|
|
already cut;
|
|
- with --worktree, the item's worktree: a sibling of the checkout named <checkout>-<branch>,
|
|
each / of the branch a dash, on the branch the config's `branch` template names, which is
|
|
item-<ID> where the config names none. It continues a worktree already on that branch; else it adds one on the
|
|
local branch, else on a new branch tracking origin's, else on a new branch off the default
|
|
branch. Without --worktree, it prints that none was made. Where the config sets `epic-branch`
|
|
(`project-config --help`), it first makes the working branch of the plan's epic on origin, off
|
|
the default branch, or merges the default branch into it; a new branch is then made off that
|
|
branch, and the checkout records that the chunk's pull request goes into it, for `chunk-pr`.
|
|
Where the two don't merge cleanly, it makes no worktree and says how a person merges them;
|
|
- each path the project's config sets, as `project-config` prints them in that worktree, or else
|
|
in the checkout;
|
|
- the language the config names for the project's prose, and its templates for commit titles,
|
|
pull request titles and branches;
|
|
- the open pull requests whose head is the item's branch, each by its number and URL, as gh lists
|
|
them on a github.com origin, and else as tea does. No title reaches the output;
|
|
- the items of that release that a chunk taking the item may take too, each with its L, E + I,
|
|
S and tagline: those that are not questions, that have R 5 or less, and that no item outside
|
|
the chunk blocks; none where the item's own R is above 5;
|
|
- the other items of that release that may start chunks while the item's chunk runs, then why each
|
|
of the rest may not. An item's prediction is the bullets under a `Touches:` line in its detail,
|
|
which `touch-predictions --help` describes. Another item may start a chunk where it doesn't
|
|
wait and its prediction shares no part with the item's, or with that of an item picked before
|
|
it in the plan's order. A part either prediction marks (small) doesn't count. This line is left
|
|
out where no item of the release that doesn't wait holds a prediction. The plan and the records
|
|
belong in no prediction, since every chunk writes them;
|
|
- each file or folder git tracks that the item's tagline or detail names in backticks, with a
|
|
file's lines or a folder's files, then the item's tagline and detail, then the detail of each
|
|
of the first {JOINING_DETAILS} items that may join, or that one has none;
|
|
- where it made or continued the worktree, what `rank_todo.py --check`,
|
|
`larv-review needs-scoring-run <ID>`, `reading-cost` and `larv-review places` print in it, each
|
|
with its exit code. reading-cost appends to docs/reading-cost.md where the project's config puts
|
|
it: in the worktree, the chunk commits it.
|
|
|
|
A fact it cannot find it says it cannot, and why, and goes on. A fetch, forge CLI or tool still
|
|
running after {timeout} seconds, or after the seconds CHUNK_PREFLIGHT_TIMEOUT sets, is stopped; a
|
|
stopped fetch reads origin as last fetched. With no item, it makes no worktree and runs none of
|
|
those four tools, --worktree or not.
|
|
|
|
Exit 1, saying why, on any argument other than --worktree, --item with an ID, -h or --help, on a
|
|
CHUNK_PREFLIGHT_TIMEOUT that is no number of seconds above 0, when git cannot start or finds no
|
|
checkout or no default branch, or when no config names the checkout or its config cannot be read.
|
|
"""
|
|
import pathlib
|
|
import re
|
|
import subprocess
|
|
import sys
|
|
import typing
|
|
|
|
from git_cli.git_repo import commit_exists, default_branch, file_at, git, record_chunk_base, top
|
|
from git_cli import epic_branch
|
|
from failure import Failure
|
|
from forge.commands import Forge, forge_of, Run, runner
|
|
from chunk_preflight.gathered import Gathered, ItemFacts, LeftWorktree, NamedPath, Ran, Worktree
|
|
from chunk_preflight.facts import JOINING_DETAILS, render
|
|
from project_config.main import located
|
|
from forge.pulls import merged_pull
|
|
from plan.named_paths import named_paths
|
|
from release_plan.next_chunk import NextChunk, NoItem, plan_name, planned
|
|
from release_plan.release_standing import project_plan
|
|
from project_config.settings import ProjectConfig
|
|
from chunk_preflight.choices import pulls_command, worktree_add, worktree_on, worktrees
|
|
from project_config import templates
|
|
|
|
BIN = pathlib.Path(__file__).resolve().parents[1]
|
|
# Each tool run in the item's worktree, {item} standing for the item's ID.
|
|
TOOLS = (("rank_todo.py", "--check"), ("larv-review", "needs-scoring-run", "{item}"), ("reading-cost",), ("larv-review", "places"))
|
|
# Seconds before a fetch, forge CLI or tool is stopped, so a hung one cannot keep the rest from printing; TIMEOUT_SETTING overrides it.
|
|
TIMEOUT = 60
|
|
TIMEOUT_SETTING = "CHUNK_PREFLIGHT_TIMEOUT"
|
|
# The flag that makes the item's worktree and runs TOOLS in it. Three readers seated as the README's audience picked it 2-1 over --start.
|
|
WORKTREE = "--worktree"
|
|
# The flag that names the chunk's item. Three readers seated as the README's audience picked it 3-0 over --for, --start and a bare ID.
|
|
ITEM = "--item"
|
|
|
|
|
|
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
|
|
if argv in (["-h"], ["--help"]):
|
|
print(__doc__.strip().format(timeout=TIMEOUT, JOINING_DETAILS=JOINING_DETAILS))
|
|
return 0
|
|
rest = [arg for arg in argv if arg != WORKTREE]
|
|
if len(argv) - len(rest) > 1 or not (rest == [] or (len(rest) == 2 and rest[0] == ITEM and re.fullmatch(r"[0-9]+", rest[1], re.ASCII))):
|
|
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight [{WORKTREE}] [{ITEM} <ID>]", file=sys.stderr)
|
|
return 1
|
|
printed = run(env.get(TIMEOUT_SETTING), WORKTREE in argv, int(rest[1]) if rest else None)
|
|
if isinstance(printed, Failure):
|
|
print(printed.reason, file=sys.stderr)
|
|
return 1
|
|
print("\n".join(printed))
|
|
return 0
|
|
|
|
|
|
def run(setting: str | None, make: bool, item_id: int | None = None) -> list[str] | Failure:
|
|
"""The preflight's lines, given the setting TIMEOUT_SETTING holds, whether to make the item's worktree, and the ID --item names; a Failure where the setting is no number of seconds above 0, or git finds no checkout or no default branch."""
|
|
timeout = seconds(setting)
|
|
if isinstance(timeout, Failure):
|
|
return timeout
|
|
root = top()
|
|
return root if isinstance(root, Failure) else preflight(pathlib.Path(root), timeout, make, item_id)
|
|
|
|
|
|
def seconds(setting: str | None) -> float | Failure:
|
|
"""The timeout setting as seconds, TIMEOUT where unset; a Failure where it is no number above 0."""
|
|
if setting is None:
|
|
return TIMEOUT
|
|
if re.fullmatch(r"[0-9]+(\.[0-9]+)?", setting) and float(setting) > 0:
|
|
return float(setting)
|
|
return Failure(f"{TIMEOUT_SETTING}={setting!r} is no number of seconds above 0")
|
|
|
|
|
|
def preflight(root: pathlib.Path, timeout: float, make: bool, item_id: int | None) -> list[str] | Failure:
|
|
"""Gathers the facts step by step, each step taking what the ones before it found, and renders them; a Failure where the checkout has no default branch."""
|
|
default = default_branch(stale_ok=True, timeout=timeout)
|
|
if isinstance(default, Failure):
|
|
return default
|
|
ref, note = default
|
|
config = located(str(root), pathlib.Path.home())
|
|
if isinstance(config, Failure):
|
|
return config
|
|
outside = None if config.tracked("plan") else config.plan_label
|
|
forge_run = runner(str(root), timeout)
|
|
held = project_plan(config, ref, str(root), forge_run=forge_run)
|
|
plan = planned(held.plan, held.cut, ref, config.branch, outside, item_id)
|
|
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout, make, epic_branch_of(config))
|
|
# 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).places, outside is not None, config.texts, merges_unread=held.merges_unread, left=left_worktrees(root, forge_run) if config.merge == "human" else ()))
|
|
|
|
|
|
def epic_branch_of(config: ProjectConfig) -> str | None | Failure:
|
|
"""The working branch of the plan's epic, as the config's `epic-branch` names it; None where the config sets none."""
|
|
if config.epic_branch is None:
|
|
return None
|
|
if config.epic is None:
|
|
return Failure("none made: the config sets `epic-branch`, but its `plan` names no Jira epic to name the branch by; chunk-preflight makes an epic's chunks only from a plan kept in Jira")
|
|
return templates.epic_branch(config.epic_branch, config.epic.key)
|
|
|
|
|
|
def item_facts(root: pathlib.Path, default: str, plan: NextChunk, timeout: float, make: bool, epic: str | None | Failure = None) -> ItemFacts:
|
|
worktree = Failure(f"none made, since it ran without {WORKTREE}.") if not make else epic if isinstance(epic, Failure) else item_worktree(root, plan.branch, default, timeout, epic)
|
|
path = worktree.path if isinstance(worktree, Worktree) else None
|
|
return ItemFacts(plan, worktree, pull_listing(root, plan.branch, timeout), named_files(plan.text, path or root), tools_run(plan.first.id, path, timeout) if path else [])
|
|
|
|
|
|
def item_worktree(root: pathlib.Path, branch: str, default: str, timeout: float | None = None, epic: str | None = None) -> Worktree | Failure:
|
|
"""The worktree on branch, made where none is; a Failure where git cannot make it, or its path holds something else.
|
|
|
|
epic names the working branch of the chunk's epic, where the project keeps one. The worktree then branches off that branch, which is first made on origin or brought level with default (`epic_branch.levelled`), and the checkout records that the chunk merges into it."""
|
|
if epic is not None:
|
|
level = epic_branch.levelled(epic, default, timeout=timeout)
|
|
recorded = level if isinstance(level, Failure) else record_chunk_base(branch, epic)
|
|
if isinstance(recorded, Failure):
|
|
return Failure(f"none made: {recorded.reason}")
|
|
made = item_worktree(root, branch, f"origin/{epic}")
|
|
return made if isinstance(made, Failure) else Worktree(made.path, f"{made.how} {level} The chunk's pull request goes into {epic}.")
|
|
listing = git("worktree", "list", "--porcelain")
|
|
if isinstance(listing, Failure):
|
|
return listing
|
|
if (path := worktree_on(listing, branch)) is not None:
|
|
return Worktree(path, f"continued, on the branch {branch}.")
|
|
# A branch such as feature/7 would nest the worktree in a folder, so its slashes become dashes.
|
|
path = root.parent / f"{root.name}-{branch.replace('/', '-')}"
|
|
if path.exists():
|
|
return Failure(f"none made, since {path} exists and holds no worktree on the branch {branch}")
|
|
args, how = worktree_add(branch, path, default, commit_exists(f"refs/heads/{branch}"), commit_exists(f"refs/remotes/origin/{branch}"))
|
|
added = git(*args)
|
|
return Failure(f"none made: {added.reason}") if isinstance(added, Failure) else Worktree(path, how)
|
|
|
|
|
|
def left_worktrees(root: pathlib.Path, forge_run: Run) -> tuple[LeftWorktree, ...]:
|
|
"""Each worktree but root that is on a branch whose pull request merged with the worktree's head commit as its head: under `merge = "human"` a person merges after the chunk's run has ended, so its worker never ran `chunk-pr clean`. Where the forge can't be asked, no worktree counts as left."""
|
|
listing, url = git("worktree", "list", "--porcelain"), git("remote", "get-url", "origin")
|
|
if isinstance(listing, Failure) or isinstance(url, Failure):
|
|
return ()
|
|
merged = [(path, branch, merged_pull(forge_of(url), branch, head, forge_run)) for path, branch, head in worktrees(listing) if path != root]
|
|
return tuple(LeftWorktree(path, branch, pull) for path, branch, pull in merged if isinstance(pull, str))
|
|
|
|
|
|
def pull_listing(root: pathlib.Path, branch: str, timeout: float) -> tuple[Forge, Ran | Failure] | None:
|
|
url = git("remote", "get-url", "origin")
|
|
if isinstance(url, Failure):
|
|
return None
|
|
forge = forge_of(url)
|
|
return forge, ran(pulls_command(forge, branch), root, timeout)
|
|
|
|
|
|
def named_files(text: str, base: pathlib.Path) -> list[NamedPath] | Failure:
|
|
tracked = git("-C", str(base), "ls-files")
|
|
if isinstance(tracked, Failure):
|
|
return tracked
|
|
return [NamedPath(span, files, line_count(base / span)) for span, files in named_paths(text, tracked.splitlines())]
|
|
|
|
|
|
def line_count(path: pathlib.Path) -> int | Failure | None:
|
|
"""A file's lines, or why they cannot be read; None for a folder."""
|
|
if not path.is_file():
|
|
return None
|
|
try:
|
|
return len(path.read_text(encoding="utf-8").splitlines())
|
|
except (OSError, UnicodeDecodeError) as failure:
|
|
return Failure(str(failure))
|
|
|
|
|
|
def tools_run(item_id: int, worktree: pathlib.Path, timeout: float) -> list[tuple[str, Ran | Failure]]:
|
|
commands = [[part.format(item=item_id) for part in tool] for tool in TOOLS]
|
|
return [(" ".join(command), ran([sys.executable, str(BIN / command[0]), *command[1:]], worktree, timeout)) for command in commands]
|
|
|
|
|
|
def ran(command: list[str], cwd: pathlib.Path, timeout: float) -> Ran | Failure:
|
|
try:
|
|
done = subprocess.run(command, capture_output=True, cwd=cwd, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL, timeout=timeout)
|
|
except (OSError, subprocess.TimeoutExpired) as failure:
|
|
return Failure(f"could not finish: {failure}")
|
|
return Ran(done.returncode, done.stdout, done.stderr)
|