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

194 lines
11 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]
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. 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's earliest release is x.y.z or earlier, it says todo.md files items under a release
already cut;
- with --worktree, the item's worktree: a sibling of the checkout named <checkout>-item-<ID>, on
the branch item-<ID>. 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 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;
- 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, -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 release_plan.release_standing import default_plan
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 record_store.stores import store
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"
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
if argv not in ([], [WORKTREE]):
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight [{WORKTREE}]", file=sys.stderr)
return 1
printed = run(env.get(TIMEOUT_SETTING), argv == [WORKTREE])
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) -> list[str] | Failure:
"""The preflight's lines, given the setting TIMEOUT_SETTING holds and whether to make the item's worktree; 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)
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) -> 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.paths["plan"]
held = default_plan(str(root), ref, config.place("plan"), store(config, "changelog"))
plan = planned(held.todo, held.cut, ref, 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))
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}.")
path = root.parent / f"{root.name}-{branch}"
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)