253 lines
13 KiB
Python
253 lines
13 KiB
Python
"""How the plan stands to the last release cut: the next release, whether work has landed towards it, and whether it is to be planned, reviewed or cut; and, from that standing, the item the next chunk takes first, with what the default branch holds for the pick."""
|
|
import dataclasses
|
|
import pathlib
|
|
|
|
from git_cli.git_repo import commits_since, file_at, git, Git
|
|
from release_plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
|
|
from failure import Failure
|
|
from release_plan.todo_table import Item, items, next_item, renames
|
|
from project_config.settings import Place
|
|
from text_files.markdown_text import sections
|
|
|
|
# The version a branch with no v* tag and no dated CHANGELOG.md heading counts as cut: below every release, 0.0.0 included, so that every release todo.md names comes after it.
|
|
BEFORE_FIRST_RELEASE = (-1, 0, 0)
|
|
# What chunk-preflight and loop-claude say where the plan is outside the checkout, since todos_since then holds only the plan as it stands: `docs/decisions.md` → "project config: a tool that reads a file's commits …".
|
|
UNSEEN_RELEASES = "The plan is outside the checkout, where no commit holds it, so a release whose last item has shipped is not seen: the plan no longer names it, and the release after it reads as next. Until the last release of all, no release review is called due and no release is called ready to cut: both are the human's to call."
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class LastCut:
|
|
"""What the default branch holds about its last release, which chunk_item weighs the plan against."""
|
|
# The newest v* tag, None where the branch has none.
|
|
tag: str | None | Failure
|
|
# CHANGELOG.md's text, empty where the branch holds none.
|
|
changelog: str | Failure
|
|
# How many commits follow the tag; on a branch with no tag, those after the commit that added the newest dated CHANGELOG.md heading, or all of them where it has none.
|
|
commits: int | Failure
|
|
# todo.md's text at the tag and at each later commit that changed it, oldest first, as named_releases reads them; where the branch has no tag, at each commit that changed it. Empty where the tags cannot be read.
|
|
todos_since: list[str] | Failure
|
|
# Whether a release review has landed since the tag, as release_reviewed reads it.
|
|
reviewed: bool | Failure = False
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Upcoming:
|
|
"""The next release, and whether work has landed towards it, as `~/.claude/CLAUDE.md` → "Working loop" uses both."""
|
|
# The earliest release after the last cut that todo.md has named since that cut or the plan holds; without a cut, the earliest todo.md has named or the plan holds. None where there is none.
|
|
release: Release | None
|
|
# Whether it is the plan's earliest release. Also True without a cut where todo.md has never named a release and the plan holds no item.
|
|
is_earliest: bool
|
|
# Whether work has landed towards it: one or more changes are unreleased, as unreleased_changes counts them.
|
|
unreleased: bool | Failure
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Next:
|
|
"""The plan's earliest release is the next release."""
|
|
# None where the plan holds no item.
|
|
release: Release | None
|
|
# The item the next chunk takes first, next_item's pick; None where every item waits or the plan holds none.
|
|
item: Item | None
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Cut:
|
|
"""The plan's earliest release is the last cut's version or earlier."""
|
|
release: Release
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class ReadyToCut:
|
|
"""The next release holds no item, and work has landed towards it."""
|
|
# The next release, None where todo.md has named none since the cut.
|
|
release: Release | None
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class ReviewDue:
|
|
"""The next release holds no item and work has landed towards it, but no release review has landed since the cut: `~/.claude/skills/larv-review/SKILL.md` → "Release review"."""
|
|
# The next release, None where todo.md has named none since the cut.
|
|
release: Release | None
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Unplanned:
|
|
"""The next release holds no item, and no work has landed towards it."""
|
|
# The next release, None where todo.md has named none since the cut.
|
|
release: Release | None
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Unknown:
|
|
"""The tags, todo.md's texts since the cut, or the changes since it, cannot be read."""
|
|
|
|
|
|
# How the plan stands to the last cut, with the item the next chunk takes first where there is one.
|
|
Pick = Next | Cut | ReadyToCut | ReviewDue | Unplanned | Unknown
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class DefaultPlan:
|
|
"""What the default branch, as last fetched, holds for chunk_item."""
|
|
# todo.md's text, empty where the branch holds none.
|
|
todo: str | Failure
|
|
cut: LastCut
|
|
|
|
|
|
def default_plan(root: str, ref: str, plan: Place, changelog: Place, run: Git = git) -> DefaultPlan:
|
|
"""What ref, the default branch as last fetched, holds for the pick, read in the checkout at root through run. plan and changelog are where the project's config puts todo.md and CHANGELOG.md."""
|
|
tag = newest_tag(root, merged_into=ref, run=run)
|
|
changes = held_at(ref, changelog, root, run)
|
|
after = dated_cut(tag, changes)
|
|
since = tag if after is None else heading_commit(after, ref, changelog, root, run)
|
|
commits = since if isinstance(since, Failure) else commits_since(since, ref, root, run)
|
|
reviewed = tag if isinstance(tag, Failure) else release_reviewed(tag, ref, root, after, run)
|
|
return DefaultPlan(held_at(ref, plan, root, run), LastCut(tag, changes, commits, todos_since(tag, ref, plan, root, run), reviewed))
|
|
|
|
|
|
def held_at(revision: str, place: Place, cwd: str, run: Git = git) -> str | Failure:
|
|
"""The text of the file at place: at revision where it is in the checkout, else as it stands. Empty where there is no such file."""
|
|
if isinstance(place, str):
|
|
return file_at(revision, place, cwd, run)
|
|
try:
|
|
return place.read_text(encoding="utf-8")
|
|
except FileNotFoundError:
|
|
return ""
|
|
except (OSError, UnicodeDecodeError) as failure:
|
|
return Failure(f"cannot read {place}: {failure}")
|
|
|
|
|
|
def heading_commit(release: Release, ref: str, changelog: Place, cwd: str, run: Git = git) -> str | None | Failure:
|
|
"""The oldest commit on ref that added release's dated heading to CHANGELOG.md, which a branch with no tag counts the unreleased commits from; None where git finds none, as for a changelog outside the checkout."""
|
|
if isinstance(changelog, pathlib.Path):
|
|
return None
|
|
# -G matches the heading line itself, so a changelog entry that quotes the heading doesn't count.
|
|
added = run("log", "--reverse", "--format=%H", "-G", dated_heading_pattern(release), ref, "--", changelog, cwd=cwd)
|
|
return added if isinstance(added, Failure) else next(iter(added.split()), None)
|
|
|
|
|
|
def release_reviewed(tag: str | None, ref: str, cwd: str, after: Release | None = None, run: Git = git) -> bool | Failure:
|
|
"""Whether ref holds a commit titled as a release review opens, `Release review of <release>`: after tag, or anywhere where tag is None.
|
|
|
|
after is the version a branch with no tag counts as cut, or None. Where it is given, a title counts only where its release is later than after.
|
|
"""
|
|
titles = run("log", "--format=%s", f"{tag}..{ref}" if tag else ref, cwd=cwd)
|
|
if isinstance(titles, Failure):
|
|
return titles
|
|
reviews = [title.removeprefix("Release review of ") for title in titles.splitlines() if title.startswith("Release review of ")]
|
|
return any(after is None or ((named := parsed(review)) is not None and named > after) for review in reviews)
|
|
|
|
|
|
def todos_since(tag: str | None | Failure, ref: str, plan: Place, cwd: str, run: Git = git) -> list[str] | Failure:
|
|
"""LastCut.todos_since, read from ref in cwd. A pull request's own commits do not count, only the merge that landed it: --first-parent.
|
|
|
|
A plan outside the checkout has no commits, so only its text as it stands counts, and its readers say UNSEEN_RELEASES."""
|
|
if isinstance(tag, Failure):
|
|
return []
|
|
if isinstance(plan, pathlib.Path):
|
|
text = held_at(ref, plan, cwd, run)
|
|
return text if isinstance(text, Failure) else [text]
|
|
changed = run("log", "--first-parent", "--reverse", "--format=%H", f"{tag}..{ref}" if tag else ref, "--", plan, cwd=cwd)
|
|
if isinstance(changed, Failure):
|
|
return changed
|
|
texts = []
|
|
for commit in [*([tag] if tag else []), *changed.split()]:
|
|
text = file_at(commit, plan, cwd, run)
|
|
if isinstance(text, Failure):
|
|
return text
|
|
texts.append(text)
|
|
return texts
|
|
|
|
|
|
def chunk_item(found: list[Item], cut: LastCut) -> Pick:
|
|
"""The pick from todo.md's items, weighed against the last cut. Routing and chunk-preflight both pick with it, so they name one item."""
|
|
upcoming = next_release(found, cut)
|
|
return standing(upcoming, next_item(found), cut.reviewed) if isinstance(upcoming, Upcoming) else upcoming
|
|
|
|
|
|
def next_release(found: list[Item], cut: LastCut) -> Upcoming | Cut | Unknown:
|
|
"""The next release after cut, and whether work has landed towards it. found holds the plan's items.
|
|
|
|
Cut where the plan files items under the last cut's version or earlier, and Unknown where the tags, or todo.md's texts since the cut, cannot be read.
|
|
Where the branch has no tag, todos_since holds every version of todo.md, so a release todo.md named whose items are all done still reads as the next release.
|
|
"""
|
|
if isinstance(cut.tag, Failure):
|
|
return Unknown()
|
|
earliest = min((item.release for item in found), default=None)
|
|
version = cut_version(cut)
|
|
if version is None:
|
|
return Upcoming(earliest, True, has_unreleased(cut))
|
|
if earliest is not None and earliest <= version:
|
|
return Cut(earliest)
|
|
named = named_releases(cut.todos_since)
|
|
if isinstance(named, Failure):
|
|
return Unknown()
|
|
after = {release for release in named if release > version}
|
|
if earliest is not None:
|
|
after.add(earliest)
|
|
release = min(after, default=None)
|
|
nothing_cut = version == BEFORE_FIRST_RELEASE
|
|
return Upcoming(release, earliest == release and (earliest is not None or nothing_cut), has_unreleased(cut))
|
|
|
|
|
|
def cut_version(cut: LastCut) -> Release | None:
|
|
"""Which version is cut. It is the tag's, or None where the tag names no version. On a branch with no tag, it is the newest version under a dated CHANGELOG.md heading, else BEFORE_FIRST_RELEASE."""
|
|
if cut.tag is None:
|
|
return dated_cut(cut.tag, cut.changelog) or BEFORE_FIRST_RELEASE
|
|
return tagged(cut.tag) if isinstance(cut.tag, str) else None
|
|
|
|
|
|
def dated_cut(tag: str | None | Failure, changelog: str | Failure) -> Release | None:
|
|
"""The version a branch with no tag counts as cut: the newest CHANGELOG.md heads `## X.Y.Z - YYYY-MM-DD`, the heading a cut release takes. None where the branch has a tag, or CHANGELOG.md has no such heading; an undated heading is not cut."""
|
|
if tag is not None or isinstance(changelog, Failure):
|
|
return None
|
|
return max((cut for heading in sections(changelog) if (cut := dated(heading))), default=None)
|
|
|
|
|
|
def has_unreleased(cut: LastCut) -> bool | Failure:
|
|
"""Whether work has landed since cut: one or more changes are unreleased."""
|
|
changes = unreleased_changes(cut)
|
|
return changes if isinstance(changes, Failure) else changes > 0
|
|
|
|
|
|
def standing(upcoming: Upcoming, first: Item | None, reviewed: bool | Failure) -> Next | ReadyToCut | ReviewDue | Unplanned | Unknown:
|
|
"""How the plan stands to upcoming, the next release. first is next_item's pick, which the pick holds where it is Next.
|
|
|
|
Unknown where the next release holds no item and the unreleased changes cannot be counted, or work has landed and git cannot say whether a release review has.
|
|
"""
|
|
if upcoming.is_earliest:
|
|
return Next(upcoming.release, first)
|
|
if isinstance(upcoming.unreleased, Failure):
|
|
return Unknown()
|
|
if not upcoming.unreleased:
|
|
return Unplanned(upcoming.release)
|
|
if isinstance(reviewed, Failure):
|
|
return Unknown()
|
|
return ReadyToCut(upcoming.release) if reviewed else ReviewDue(upcoming.release)
|
|
|
|
|
|
def unreleased_changes(cut: LastCut) -> int | Failure:
|
|
"""How many changes are unreleased, as `~/.claude/CLAUDE.md` → "Working loop" counts them: the entries under ## Unreleased, or the commits since the tag where CHANGELOG.md has no such section or cannot be read."""
|
|
entries = unreleased_entries(cut.changelog) if isinstance(cut.changelog, str) else None
|
|
return cut.commits if entries is None else entries
|
|
|
|
|
|
def unreleased_entries(changelog: str) -> int | None:
|
|
"""How many top-level `- ` entries CHANGELOG.md holds under ## Unreleased; None without that section."""
|
|
found = sections(changelog).get("Unreleased")
|
|
return None if found is None else sum(line.startswith("- ") for line in found[0].splitlines())
|
|
|
|
|
|
def named_releases(todos: list[str] | Failure) -> set[Release] | Failure:
|
|
"""Each release the todo.md texts, oldest first, file items under. A release leaves the set when a text marks it renamed, and returns when a later text files items under it again. A text whose items or marks do not parse names none, except the newest: where its marks do not parse, it returns that Failure, since the release they should have excluded would read as finished."""
|
|
if isinstance(todos, Failure):
|
|
return todos
|
|
if todos and isinstance(newest := renames(todos[-1]), Failure):
|
|
return newest
|
|
named: set[Release] = set()
|
|
for text in todos:
|
|
plan, marked = items(text), renames(text)
|
|
if isinstance(plan, list) and isinstance(marked, set):
|
|
named = (named - marked) | {item.release for item in plan}
|
|
return named
|