103 lines
5.4 KiB
Python
103 lines
5.4 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 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}"
|
|
branch = template.replace(ID, "1")
|
|
parts = branch.split("/")
|
|
if not BRANCH_TEXT.fullmatch(branch) or branch.startswith("-") or ".." in branch or any(not part or part.startswith(".") or part.endswith((".", ".lock")) for part in parts):
|
|
return f"not a branch name git accepts, of letters, digits and . _ / - around {ID}"
|
|
return None
|
|
|
|
|
|
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)
|