211 lines
13 KiB
Python
211 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, Ran, Worktree
|
|
from chunk_preflight.choices import forge_of, pulls_command, worktree_add, worktree_on
|
|
from chunk_preflight.facts import JOINING_DETAILS, render
|
|
from project_config.main import located
|
|
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
|
|
|
|
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.plan, 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: NextChunk, 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)
|