Files
claude-config/bin/chunk_preflight/main.py
T

210 lines
13 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;
- 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, or while an item still in todo.md
blocks it. 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;
- 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, top
from failure import Failure
from chunk_preflight.gathered import Forge, Gathered, ItemFacts, NamedPath, NoItem, Plan, Ran, Worktree
from chunk_preflight.choices import forge_of, plan_name, planned, pulls_command, worktree_add, worktree_on
from chunk_preflight.facts import JOINING_DETAILS, render
from project_config.main import located
from release_plan.named_code import named_paths
from release_plan.release_standing import project_plan
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
held = project_plan(config, ref, str(root))
plan = planned(held.todo, held.cut, ref, config.branch, outside, item_id)
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).places, outside is not None, config.texts))
def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float, make: bool) -> ItemFacts:
worktree = item_worktree(root, plan.branch, default) if make else Failure(f"none made, since it ran without {WORKTREE}.")
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) -> Worktree | Failure:
"""The worktree on branch, made where none is; a Failure where git cannot make it, or its path holds something else."""
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 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)