278 lines
15 KiB
Python
278 lines
15 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
|
|
|
|
from git_cli.git_repo import commits_since, file_at, git, Git
|
|
from plan.release import dated, dated_heading_pattern, newest_tag, parsed, Release, tagged
|
|
from failure import Failure
|
|
from plan.todo_table import Item, items, next_item, renames
|
|
from plan_store.plans import Plan
|
|
from plan_store import stores as plan_stores, plans
|
|
from project_config.settings import ProjectConfig
|
|
from text_files.markdown_text import sections
|
|
from record_store import stores
|
|
from project_config import templates
|
|
|
|
# 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 no commit holds an earlier plan: `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, and where no commit holds the plan.
|
|
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 the plan is current: the next release is the plan's earliest, so the plan holds its items. Also True without a cut where todo.md has never named a release and the plan holds no item, since there is no release to plan, review or cut yet.
|
|
plan_is_current: 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."""
|
|
# The plan, a NoItemsTable where the branch holds none.
|
|
plan: Plan | Failure
|
|
cut: LastCut
|
|
|
|
|
|
def project_plan(config: ProjectConfig, ref: str, root: str, run: Git = git) -> DefaultPlan:
|
|
"""default_plan for the project config describes: its plan, its changelog and its title templates."""
|
|
return default_plan(root, ref, plan_stores.store(config), stores.store(config, "changelog"), config.titles, run)
|
|
|
|
|
|
def default_plan(root: str, ref: str, plan: plans.PlanStore, changelog: stores.RecordStore, titles: templates.Titles, 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 is the store the project's config names for its plan, changelog the store it names for the changelog, and titles its title templates."""
|
|
tag = newest_tag(root, merged_into=ref, run=run)
|
|
changes = stores.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, titles, after, run)
|
|
return DefaultPlan(plan_stores.held_at(ref, plan, root, run), LastCut(tag, changes, commits, todos_since(tag, ref, plan.tracked, root, run), reviewed))
|
|
|
|
|
|
def heading_commit(release: Release, ref: str, changelog: stores.RecordStore, cwd: str, run: Git = git) -> str | None | Failure:
|
|
"""The oldest commit on ref that added release's dated heading to the changelog, which a branch with no tag counts the unreleased commits from; None where git finds none, as for a changelog no commit holds."""
|
|
if changelog.tracked is None:
|
|
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.tracked, cwd=cwd)
|
|
return added if isinstance(added, Failure) else next(iter(added.split()), None)
|
|
|
|
|
|
def release_reviewed(tag: str | None, ref: str, cwd: str, titles: templates.Titles, 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.
|
|
|
|
titles holds the project's title templates, and each commit title is read as the summary they give. 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.
|
|
"""
|
|
log = run("log", "--format=%s", f"{tag}..{ref}" if tag else ref, cwd=cwd)
|
|
if isinstance(log, Failure):
|
|
return log
|
|
summaries = [titles.summary(line) for line in log.splitlines()]
|
|
reviews = [summary.removeprefix("Release review of ") for summary in summaries if summary.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: str | None, cwd: str, run: Git = git) -> list[str] | Failure:
|
|
"""LastCut.todos_since, read from ref in cwd, where plan is todo.md's path as the plan's store tracks it. A pull request's own commits do not count, only the merge that landed it: --first-parent.
|
|
|
|
A plan no commit holds has no earlier text, so only the plan as it stands names releases, and its readers say UNSEEN_RELEASES."""
|
|
if isinstance(tag, Failure) or plan is None:
|
|
return []
|
|
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
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Standing:
|
|
"""The plan's items weighed once against the last cut, which next_release, picked and chunk-preflight all read."""
|
|
# Which version is cut, as cut_version says.
|
|
version: Release | None
|
|
# The releases todo.md has named since the cut, as named_releases reads them.
|
|
named: set[Release] | Failure
|
|
# The plan's items, each that the plan files under the last cut's version, or an earlier one, filed under the next release: the earliest after the cut that the plan holds or todo.md has named since it. Someone cut a release while it held those items, and the loop works on: lilleman's call, 2026-11-16. The plan's items as they are where nothing is cut, and where no release after the cut is known, since naming one is the human's.
|
|
carried: list[Item]
|
|
# The IDs of the items carried files under another release than the plan does, in the plan's order.
|
|
moved: tuple[int, ...]
|
|
|
|
|
|
def standing_of(found: list[Item], cut: LastCut) -> Standing:
|
|
"""found, the plan's items, weighed against cut."""
|
|
version = cut_version(cut)
|
|
named = named_releases(cut.todos_since)
|
|
known = {item.release for item in found} | (set() if isinstance(named, Failure) else named)
|
|
after = set() if version is None else {release for release in known if release > version}
|
|
if not after or all(item.release >= min(after) for item in found):
|
|
return Standing(version, named, found, ())
|
|
held = [dataclasses.replace(item, release=max(item.release, min(after))) for item in found]
|
|
return Standing(version, named, held, tuple(was.id for was, now in zip(found, held) if was.release != now.release))
|
|
|
|
|
|
def chunk_item(found: list[Item], cut: LastCut) -> Pick:
|
|
"""The pick from the plan's items, weighed against the last cut. Routing and chunk-preflight both pick with it, so they name one item."""
|
|
return picked(standing_of(found, cut), cut)
|
|
|
|
|
|
def picked(weighed: Standing, cut: LastCut) -> Pick:
|
|
"""chunk_item's pick, from the plan's items already weighed against cut."""
|
|
upcoming = next_release(weighed, cut)
|
|
return pick_from(upcoming, next_item(weighed.carried), cut.reviewed) if isinstance(upcoming, Upcoming) else upcoming
|
|
|
|
|
|
def next_release(weighed: Standing, cut: LastCut) -> Upcoming | Cut | Unknown:
|
|
"""The next release after cut, and whether work has landed towards it. weighed holds the plan's items, weighed against cut.
|
|
|
|
Cut where the plan files items under the last cut's version or earlier and no later release is known to carry them to, 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 weighed.carried), default=None)
|
|
version = weighed.version
|
|
if version is None:
|
|
return Upcoming(earliest, True, has_unreleased(cut))
|
|
if earliest is not None and earliest <= version:
|
|
return Cut(earliest)
|
|
named = weighed.named
|
|
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."""
|
|
# The loop reads no other mark of a cut, such as another tag spelling or a Jira Fix Version marked released, until lilleman says to add one: his call, 2026-11-16.
|
|
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 pick_from(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.plan_is_current:
|
|
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
|