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

168 lines
8.5 KiB
Python

"""Find the mechanical facts a chunk starts from, and make its worktree, so its worker reads them rather than finding them.
usage: chunk-preflight
Run it inside a project checkout. loop-claude runs it 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
fetches origin, when the checkout has that remote, and takes origin's default branch, or else the
local main or master, as larv-review does. It leaves the checkout as it is: it reads todo.md as
that branch holds it, the plan loop-claude routes on, and prints:
- the newest v* tag on the default branch, and how many entries the default branch's CHANGELOG.md
holds under ## Unreleased, or else how many commits followed the tag;
- the earliest release in todo.md, and that release's first item that does not wait, the item
loop-claude routes on, with its L and E + I. It names that item only where the tag names no
version x.y.z, or the release is x.y.z+1, x.y+1.0 or x+1.0.0. For a later release, or a todo.md
that holds no item, it says the release after the tag holds none: finished and ready to cut where
commits followed the tag, and else to be planned first. For x.y.z or an earlier release, it says
todo.md files items under a release already cut;
- 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;
- 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: on a public forge,
anyone may open a pull request, and its title would reach the worker's prompt;
- the items of that release that a chunk taking the item may take too: none is a question, and no
item outside them and the item blocks one;
- 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, and the item's tagline and detail;
- what `rank_todo.py --check todo.md`, `larv-review needs-scoring-run <ID>`, `reading-cost` and
`larv-review places` print in the worktree, each with its exit code. reading-cost appends to the
worktree's docs/reading-cost.md, for the chunk to commit.
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.
Exit 1, saying why, on any argument, on a CHUNK_PREFLIGHT_TIMEOUT that is no number of seconds
above 0, or when git cannot start or finds no checkout or no default branch.
"""
import pathlib
import re
import subprocess
import sys
import typing
from git_repo import commit_exists, commits_since, default_branch, default_branch_todo, file_at, git, newest_release_tag, top
from failure import Failure
from chunk_preflight.gathered import Forge, forge_of, Gathered, ItemFacts, named_paths, NamedPath, NoItem, Plan, planned, pulls_command, Ran, Release, Worktree, worktree_add, worktree_on
from chunk_preflight.facts import render
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", "todo.md"), ("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 leaves the facts the others find; TIMEOUT_SETTING sets others.
TIMEOUT = 60
TIMEOUT_SETTING = "CHUNK_PREFLIGHT_TIMEOUT"
def main(argv: list[str], env: typing.Mapping[str, str]) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip().format(timeout=TIMEOUT))
return 0
if argv:
print(f"unknown arguments {' '.join(argv)}; usage: chunk-preflight", file=sys.stderr)
return 1
printed = run(env.get(TIMEOUT_SETTING))
if isinstance(printed, Failure):
print(printed.reason, file=sys.stderr)
return 1
print("\n".join(printed))
return 0
def run(setting: str | None) -> list[str] | Failure:
"""The preflight's lines, given what TIMEOUT_SETTING holds; a Failure where that is no number of seconds, 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)
def seconds(setting: str | None) -> float | Failure:
"""The seconds a TIMEOUT_SETTING of setting gives, TIMEOUT where it is 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) -> 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
cut = release(ref, root)
plan = planned(default_branch_todo(str(root), timeout), cut, ref)
item = plan if isinstance(plan, NoItem) else item_facts(root, ref, plan, timeout)
return render(Gathered(ref, note, cut, item))
def release(default: str, root: pathlib.Path) -> Release:
tag = newest_release_tag(default)
commits = tag if isinstance(tag, Failure) else commits_since(tag, default)
return Release(tag, file_at(default, "CHANGELOG.md", str(root)), commits)
def item_facts(root: pathlib.Path, default: str, plan: Plan, timeout: float) -> ItemFacts:
worktree = item_worktree(root, plan.branch, default)
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)