Files
2026-11-20 19:32:59 +01:00

121 lines
6.1 KiB
Python

"""The templates a project's config names for its commit titles, pull request titles and branches.
A template is literal text around two placeholders: `{id}`, the ID of the chunk's first plan item, and `{summary}`, the one line that says what the commit or pull request does. A template has no escape for a literal brace: one is a fault, which keeps a misspelt placeholder such as `{ID}` out of every title."""
import dataclasses
import re
ID = "{id}"
SUMMARY = "{summary}"
# What an `epic-branch` template holds in place of the epic's key.
EPIC = "{epic}"
# What each setting holds where the config leaves it out: a bare summary, and the branch `CLAUDE.md` → "Git, commits, and PRs" names.
TITLE = SUMMARY
BRANCH = "item-{id}"
PLACEHOLDER = re.compile(r"(\{id\}|\{summary\})")
# The characters a branch template may hold around `{id}`: a subset of what `git check-ref-format` accepts, and nothing a shell or a forge's URL reads specially.
BRANCH_TEXT = re.compile(r"[A-Za-z0-9._/-]+")
def title_fault(template: object) -> str | None:
"""Why template is no title template; None where it is one."""
if not isinstance(template, str):
return f"not text such as \"[{ID}] {SUMMARY}\""
if "\n" in template:
return "not one line"
if re.search(r"[\x00-\x1f\x7f-\x9f]", template):
return "with a control character"
# The tools match a title with the space around it stripped, so no title would fit.
if template != template.strip():
return "with a space at its start or end"
if template.count(SUMMARY) != 1:
return f"without exactly one {SUMMARY}"
if template.count(ID) > 1:
return f"with more than one {ID}"
if ID + SUMMARY in template or SUMMARY + ID in template:
return f"with {ID} right beside {SUMMARY}, so no text says where one ends and the other starts"
return stray_brace(template)
def branch_fault(template: object) -> str | None:
"""Why template is no branch template; None where it is one. A branch needs the ID, or two chunks would share one."""
if not isinstance(template, str):
return f"not text such as \"feature/{ID}\""
if template.count(ID) != 1 or SUMMARY in template:
return f"without exactly one {ID}, or with a {SUMMARY}"
if not git_accepts(template.replace(ID, "1")):
return f"not a branch name git accepts, of letters, digits and . _ / - around {ID}"
return None
def git_accepts(branch: str) -> bool:
return bool(BRANCH_TEXT.fullmatch(branch)) and not branch.startswith("-") and ".." not in branch and not any(not part or part.startswith(".") or part.endswith((".", ".lock")) for part in branch.split("/"))
def epic_branch_fault(template: object) -> str | None:
"""Why template is no `epic-branch` template; None where it is one. It needs the epic's key, or two epics would share a branch."""
if not isinstance(template, str) or template.count(EPIC) != 1:
return f"not text with exactly one {EPIC}, such as \"{EPIC}\" or \"epic/{EPIC}\""
if not git_accepts(template.replace(EPIC, "ABC-1")):
return f"not a branch name git accepts, of letters, digits and . _ / - around {EPIC}"
return None
def epic_branch(template: str, key: str) -> str:
"""The branch template names for the epic with the key key."""
return template.replace(EPIC, key)
def stray_brace(template: str) -> str | None:
stray = re.search(r"\{[^{}]*\}?|\}", PLACEHOLDER.sub("", template))
return f"with {stray[0]}, which is neither {ID} nor {SUMMARY}" if stray else None
def branch_of(template: str, id_: int) -> str:
return template.replace(ID, str(id_))
def branch_fits(template: str, branch: str) -> bool:
"""Whether branch is one branch_of makes from template: a chunk's branch whose first plan item gave it its ID. A chunk without a plan item, such as a release review, is on a branch that doesn't fit."""
return re.fullmatch(re.escape(template).replace(re.escape(ID), "[0-9]+"), branch) is not None
def pattern(template: str) -> re.Pattern[str]:
"""What a title made from template looks like: its literal text, digits for the ID, and a summary that opens and ends with something other than a space."""
shapes = {ID: "[0-9]+", SUMMARY: r"(?P<summary>\S(?:.*\S)?)"}
return re.compile("".join(shapes.get(part) or re.escape(part) for part in PLACEHOLDER.split(template)))
def fits(template: str, title: str) -> bool:
return pattern(template).fullmatch(title) is not None
def misfits(template: str, branch_template: str, branch: str | None, title: str) -> bool:
"""Whether title breaks template on branch, the checkout's branch or None where HEAD is detached. On a branch that fits branch_template, a plan item's, a title must fit template. Any other branch, such as a release review's, has no ID for {id}, so every title fits there (CLAUDE.md → "Git, commits, and PRs")."""
return branch is not None and branch_fits(branch_template, branch) and not fits(template, title.strip())
def title_of(template: str, branch_template: str, branch: str, id_: str, summary: str) -> str:
"""The title template makes of summary on branch, with id_ for {id}; summary alone on a branch that doesn't fit branch_template, as misfits allows."""
return template.replace(ID, id_).replace(SUMMARY, summary) if branch_fits(branch_template, branch) else summary
def summary_of(template: str, title: str) -> str:
"""title's summary. A title that doesn't fit template is its own summary, so a commit from before the config named the template reads as it always did."""
found = pattern(template).fullmatch(title)
return found["summary"] if found else title
@dataclasses.dataclass(frozen=True)
class Titles:
"""A project's two title templates, `commit-title` and `pull-request-title`, for a tool that reads a commit's title as its summary."""
commit: str
pull_request: str
def summary(self, title: str) -> str:
"""title's summary: read through commit, and where that leaves the title whole, through pull_request, since a squash merge titles the default branch's commit as its pull request. A title that fits neither is its own summary."""
return next((summary for template in (self.commit, self.pull_request) if (summary := summary_of(template, title)) != title), title)
# The templates of a project whose config names none, and of a checkout no config names: every title is its own summary.
BARE = Titles(TITLE, TITLE)