194 lines
11 KiB
Python
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)
|