git-acta 1.0.0__py3-none-any.whl

acta/git/branch.py

@@ -0,0 +1,77 @@
+import re
+
+from acta.git import git
+
+TYPES = frozenset(
+    [
+        "build",
+        "chore",
+        "ci",
+        "docs",
+        "feat",
+        "fix",
+        "perf",
+        "refactor",
+        "revert",
+        "style",
+        "test",
+    ]
+)
+
+# type/scope, with an optional third descriptive segment (e.g. an issue topic);
+# the conventional-commit type and scope are derived from the first two.
+_BRANCH_RE = re.compile(r"([^/]+)/([^/]+)(?:/.+)?")
+_SCOPE_RE = re.compile(r"[a-z0-9][a-z0-9_-]*", re.IGNORECASE)
+
+
+def parse(branch: str) -> tuple[str, str]:
+    branch_match = _BRANCH_RE.fullmatch(branch)
+    if not branch_match:
+        raise ValueError(f"Branch '{branch}' does not follow type/scope convention")
+    type_ = branch_match.group(1)
+    if type_ not in TYPES:
+        raise ValueError(
+            f"'{type_}' is not a conventional commit type. Use one of: {', '.join(sorted(TYPES))}"
+        )
+    scope = branch_match.group(2)
+    if not _SCOPE_RE.fullmatch(scope):
+        raise ValueError(
+            f"'{scope}' is not a valid scope. Use letters, digits, hyphens, and underscores."
+        )
+    return type_, scope
+
+
+def get_current_branch() -> str:
+    return git("branch", "--show-current", capture=True)
+
+
+def fetch_origin() -> None:
+    git("fetch", "origin", quiet=True)
+
+
+def switch_new_branch(name: str) -> None:
+    git("switch", "-c", name, "origin/main", quiet=True)
+
+
+def switch_main() -> None:
+    git("switch", "main", quiet=True)
+
+
+def pull_origin_main() -> None:
+    git("pull", "origin", "main", quiet=True)
+
+
+def branch_exists(name: str) -> bool:
+    return bool(git("branch", "--list", name, capture=True))
+
+
+def delete_branch(name: str) -> None:
+    git("branch", "-D", name, quiet=True)
+
+
+def switch_branch(name: str) -> None:
+    git("switch", name, quiet=True)
+
+
+def merge_origin_main() -> None:
+    git("merge", "origin/main", quiet=True)

acta/git/commit.py

@@ -0,0 +1,20 @@
+from acta.git import git
+
+
+def add_all() -> None:
+    git("add", "-A")
+
+
+def commit(header: str, body: str | None = None) -> None:
+    commit_args = ["commit", "-m", header]
+    if body:
+        commit_args += ["-m", body]
+    git(*commit_args)
+
+
+def push_head() -> None:
+    git("push", "--set-upstream", "origin", "HEAD", quiet=True)
+
+
+def commit_subjects(rev_range: str) -> list[str]:
+    return git("log", rev_range, "--format=%s", capture=True).splitlines()

acta/git/config.py

@@ -0,0 +1,22 @@
+import subprocess
+
+from acta.git import git
+
+
+def get_active_issue() -> int | None:
+    try:
+        config_value = git("config", "--get", "clerk.active-issue", capture=True)
+        return int(config_value) if config_value else None
+    except subprocess.CalledProcessError:
+        return None
+
+
+def set_active_issue(number: int) -> None:
+    git("config", "clerk.active-issue", str(number))
+
+
+def clear_active_issue() -> None:
+    try:
+        git("config", "--unset", "clerk.active-issue")
+    except subprocess.CalledProcessError:
+        pass

acta/git/tag.py

@@ -0,0 +1,117 @@
+import re
+from datetime import date
+from typing import Final, Literal, TypeAlias
+
+from acta.git import git
+from acta.git.commit import commit_subjects
+
+CALVER: Final = "CalVer"
+SEMVER: Final = "SemVer"
+Scheme: TypeAlias = Literal["CalVer", "SemVer"]
+
+_CALVER_RE = re.compile(r"v\d{4}\.\d{2}\.\d+")
+_SEMVER_RE = re.compile(r"v\d+\.\d+\.\d+")
+_CONVENTIONAL_HEADER_RE = re.compile(r"(?P<type>\w+)(\([^)]*\))?(?P<breaking>!)?:")
+
+
+def detect_scheme(existing_tags: list[str]) -> Scheme | None:
+    found_schemes: set[Scheme] = set()
+    for tag in existing_tags:
+        if _CALVER_RE.fullmatch(tag):
+            found_schemes.add(CALVER)
+        elif _SEMVER_RE.fullmatch(tag):
+            found_schemes.add(SEMVER)
+    if not found_schemes:
+        return None
+    if len(found_schemes) > 1:
+        raise ValueError(f"mixed {CALVER} and {SEMVER} tags found — pass --scheme to proceed")
+    return next(iter(found_schemes))
+
+
+def compute_next_calver(existing_tags: list[str], today: date) -> str:
+    prefix = f"v{today.year}.{today.month:02d}."
+    month_tags = [tag for tag in existing_tags if re.fullmatch(rf"{re.escape(prefix)}\d+", tag)]
+    last_counter = max((int(tag[len(prefix) :]) for tag in month_tags), default=0)
+    return f"{prefix}{last_counter + 1}"
+
+
+def latest_semver_tag(existing_tags: list[str]) -> str | None:
+    semver_tags = sorted(
+        (
+            tag
+            for tag in existing_tags
+            if _SEMVER_RE.fullmatch(tag) and not _CALVER_RE.fullmatch(tag)
+        ),
+        key=lambda tag: tuple(int(part) for part in tag[1:].split(".")),
+    )
+    return semver_tags[-1] if semver_tags else None
+
+
+def semver_major(tag: str) -> int:
+    return int(tag[1:].split(".")[0])
+
+
+def derive_bump(commit_subjects: list[str], current_major: int) -> str:
+    """Derive the SemVer bump from the conventional-commit subjects since the last release.
+
+    A `!` breaking marker bumps major once stable (1.0+); while still 0.x it is capped at
+    minor, since a pre-1.0 breaking change must not force 1.0.0 — that is the deliberate
+    `--stable` decision. A `feat` bumps minor; anything else, patch.
+    """
+    has_breaking = False
+    has_feat = False
+    for subject in commit_subjects:
+        header = _CONVENTIONAL_HEADER_RE.match(subject)
+        if header is None:
+            continue
+        has_breaking = has_breaking or header.group("breaking") is not None
+        has_feat = has_feat or header.group("type") == "feat"
+    if has_breaking and current_major >= 1:
+        return "major"
+    if has_breaking or has_feat:
+        return "minor"
+    return "patch"
+
+
+def compute_next_semver(existing_tags: list[str], bump: str) -> str:
+    latest = latest_semver_tag(existing_tags)
+    if latest is None:
+        return "v0.1.0"
+    major, minor, patch = (int(part) for part in latest[1:].split("."))
+    if bump == "major":
+        return f"v{major + 1}.0.0"
+    if bump == "minor":
+        return f"v{major}.{minor + 1}.0"
+    return f"v{major}.{minor}.{patch + 1}"
+
+
+def next_release_tag(existing_tags: list[str], stable: bool) -> str:
+    """The next SemVer tag: a deliberate v1.0.0 with `stable`, else derived from commits.
+
+    Raises ValueError if `stable` is requested on an already-stable (1.0+) project.
+    """
+    latest = latest_semver_tag(existing_tags)
+    if stable:
+        if latest is not None and semver_major(latest) >= 1:
+            raise ValueError("--stable only promotes 0.x to v1.0.0; this project is already stable")
+        return "v1.0.0"
+    current_major = semver_major(latest) if latest is not None else 0
+    subjects = commit_subjects(f"{latest}..origin/main") if latest is not None else []
+    return compute_next_semver(existing_tags, derive_bump(subjects, current_major))
+
+
+def fetch_tags() -> None:
+    git("fetch", "--tags", "origin", quiet=True)
+
+
+def list_tags(pattern: str = "v*") -> list[str]:
+    return [tag for tag in git("tag", "--list", pattern, capture=True).splitlines() if tag]
+
+
+def create_tag(tag: str, ref: str = "origin/main") -> None:
+    if tag in list_tags():
+        raise RuntimeError(
+            f"tag '{tag}' already exists — re-run 'acta release' to get the next version"
+        )
+    git("tag", tag, ref, quiet=True)
+    git("push", "origin", tag, quiet=True)

acta/github/__init__.py

@@ -0,0 +1,43 @@
+import functools
+import subprocess
+from urllib.parse import urlparse
+
+from acta.git import get_remote_url
+
+
+def parse_repo_from_url(url: str) -> str:
+    if "://" in url:
+        path = urlparse(url).path.lstrip("/")
+    else:
+        _, _, path = url.partition(":")
+    repo_slug = path.removesuffix(".git")
+    repo_parts = repo_slug.split("/")
+    if len(repo_parts) != 2 or not all(repo_parts):
+        raise ValueError(f"cannot parse GitHub repo from remote URL: {url}")
+    return repo_slug
+
+
+def gh(*args: str, capture: bool = False) -> str:
+    try:
+        completed_process = subprocess.run(
+            ["gh", *args],
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE if capture else None,
+        )
+        return completed_process.stdout.strip() if completed_process.stdout else ""
+    except FileNotFoundError:
+        raise RuntimeError(
+            "'gh' not found in PATH — install the GitHub CLI: https://cli.github.com"
+        )
+    except subprocess.CalledProcessError:
+        raise
+
+
+@functools.cache
+def get_repo() -> str:
+    origin_url = get_remote_url("origin")
+    try:
+        return parse_repo_from_url(origin_url)
+    except ValueError as error:
+        raise RuntimeError(str(error)) from error

acta/github/issue.py

@@ -0,0 +1,126 @@
+import json
+import subprocess
+from dataclasses import dataclass
+
+from acta.github import get_repo, gh
+from acta.github.label import ensure_type_labels
+from acta.github.milestone import milestone_view
+
+
+@dataclass
+class MilestoneRef:
+    number: int
+    title: str
+
+
+@dataclass
+class IssueInfo:
+    number: int
+    title: str
+    type: str
+    milestone: MilestoneRef | None
+    body: str = ""
+
+
+def issue_create(
+    title: str,
+    type_label: str,
+    body: str = "",
+    milestone: int | None = None,
+) -> int:
+    milestone_title = milestone_view(milestone).title if milestone is not None else None
+    command_args = [
+        "issue",
+        "create",
+        "--title",
+        title,
+        "--body",
+        body,
+        "--repo",
+        get_repo(),
+        "--label",
+        f"type: {type_label}",
+    ]
+    if milestone_title is not None:
+        command_args += ["--milestone", milestone_title]
+    try:
+        issue_url = gh(*command_args, capture=True)
+    except subprocess.CalledProcessError:
+        ensure_type_labels()
+        issue_url = gh(*command_args, capture=True)
+    return int(issue_url.rstrip("/").split("/")[-1])
+
+
+def issue_list(milestone: int | None = None) -> list[IssueInfo]:
+    command_args = [
+        "issue",
+        "list",
+        "--repo",
+        get_repo(),
+        "--json",
+        "number,title,labels,milestone",
+        "--state",
+        "open",
+    ]
+    if milestone is not None:
+        command_args += ["--milestone", str(milestone)]
+    response_json = gh(*command_args, capture=True)
+    issues: list[IssueInfo] = []
+    for issue_data in json.loads(response_json):
+        milestone_data = issue_data["milestone"]
+        issues.append(
+            IssueInfo(
+                number=int(issue_data["number"]),
+                title=str(issue_data["title"]),
+                type=_extract_type(issue_data["labels"]) or "",
+                milestone=MilestoneRef(
+                    number=int(milestone_data["number"]), title=str(milestone_data["title"])
+                )
+                if milestone_data
+                else None,
+            )
+        )
+    return issues
+
+
+def issue_view(number: int) -> IssueInfo:
+    response_json = gh(
+        "issue",
+        "view",
+        str(number),
+        "--repo",
+        get_repo(),
+        "--json",
+        "number,title,labels,milestone,body",
+        capture=True,
+    )
+    issue_data = json.loads(response_json)
+    milestone_data = issue_data["milestone"]
+    issue_type = _extract_type(issue_data["labels"])
+    if not issue_type:
+        raise RuntimeError(
+            f"Issue #{number} has no type label — assign a 'type: TYPE' label on GitHub"
+        )
+    return IssueInfo(
+        number=int(issue_data["number"]),
+        title=str(issue_data["title"]),
+        type=issue_type,
+        milestone=MilestoneRef(
+            number=int(milestone_data["number"]), title=str(milestone_data["title"])
+        )
+        if milestone_data
+        else None,
+        body=str(issue_data.get("body") or ""),
+    )
+
+
+def issue_close_not_planned(number: int) -> None:
+    gh("issue", "close", str(number), "--reason", "not planned", "--repo", get_repo())
+
+
+def _extract_type(labels: list[dict[str, str]]) -> str | None:
+    for label in labels:
+        name = label.get("name", "")
+        if name.startswith("type: "):
+            return name[6:]
+    return None

acta/github/label.py

@@ -0,0 +1,22 @@
+from acta.git.branch import TYPES
+from acta.github import get_repo, gh
+
+TYPE_COLORS: dict[str, str] = {
+    "build": "0075ca",
+    "chore": "cfd3d7",
+    "ci": "e4e669",
+    "docs": "0052cc",
+    "feat": "a2eeef",
+    "fix": "d73a4a",
+    "perf": "5319e7",
+    "refactor": "e99695",
+    "revert": "f9d0c4",
+    "style": "fef2c0",
+    "test": "bfd4f2",
+}
+
+
+def ensure_type_labels() -> None:
+    for type_ in TYPES:
+        color = TYPE_COLORS.get(type_, "ededed")
+        gh("label", "create", f"type: {type_}", "--color", color, "--force", "--repo", get_repo())

acta/github/milestone.py

@@ -0,0 +1,107 @@
+import json
+from dataclasses import dataclass
+
+from acta.github import get_repo, gh
+
+_SCOPE_PREFIX = "scope: "
+
+
+@dataclass
+class MilestoneListItem:
+    number: int
+    title: str
+    scope: str
+    description: str
+    open_issues: int
+    closed_issues: int
+
+
+@dataclass
+class MilestoneDetail:
+    number: int
+    title: str
+    scope: str
+    description: str
+    open_issues: int
+    state: str
+
+
+def milestone_create(
+    title: str,
+    scope: str,
+    description: str = "",
+) -> int:
+    gh_description = _build_description(scope, description)
+    response_json = gh(
+        "api",
+        f"repos/{get_repo()}/milestones",
+        "--method",
+        "POST",
+        "-f",
+        f"title={title}",
+        "-f",
+        f"description={gh_description}",
+        capture=True,
+    )
+    return int(json.loads(response_json)["number"])
+
+
+def milestone_list() -> list[MilestoneListItem]:
+    response_json = gh(
+        "api", f"repos/{get_repo()}/milestones", "-X", "GET", "-f", "state=open", capture=True
+    )
+    milestone_items: list[MilestoneListItem] = []
+    for milestone_data in json.loads(response_json):
+        scope, description = parse_description(str(milestone_data.get("description") or ""))
+        milestone_items.append(
+            MilestoneListItem(
+                number=int(milestone_data["number"]),
+                title=str(milestone_data["title"]),
+                scope=scope,
+                description=description,
+                open_issues=int(milestone_data["open_issues"]),
+                closed_issues=int(milestone_data["closed_issues"]),
+            )
+        )
+    return milestone_items
+
+
+def milestone_view(number: int) -> MilestoneDetail:
+    response_json = gh("api", f"repos/{get_repo()}/milestones/{number}", capture=True)
+    milestone_data = json.loads(response_json)
+    scope, description = parse_description(str(milestone_data.get("description") or ""))
+    return MilestoneDetail(
+        number=int(milestone_data["number"]),
+        title=str(milestone_data["title"]),
+        scope=scope,
+        description=description,
+        open_issues=int(milestone_data["open_issues"]),
+        state=str(milestone_data["state"]),
+    )
+
+
+def milestone_reopen(number: int) -> None:
+    gh("api", f"repos/{get_repo()}/milestones/{number}", "--method", "PATCH", "-f", "state=open")
+
+
+def milestone_close(number: int) -> None:
+    gh("api", f"repos/{get_repo()}/milestones/{number}", "--method", "PATCH", "-f", "state=closed")
+
+
+def _build_description(scope: str, description: str) -> str:
+    description_parts = [f"scope: {scope}"]
+    if description:
+        description_parts.append(description)
+    return "\n\n".join(description_parts)
+
+
+def parse_description(raw_description: str) -> tuple[str, str]:
+    """Returns (scope, description) from a GitHub milestone description."""
+    lines = raw_description.split("\n")
+    scope = ""
+    if lines and lines[0].startswith(_SCOPE_PREFIX):
+        scope = lines[0][len(_SCOPE_PREFIX) :]
+        remaining_description = "\n".join(lines[1:]).strip()
+    else:
+        remaining_description = raw_description.strip()
+    return scope, remaining_description

acta/github/pr.py

@@ -0,0 +1,111 @@
+import json
+import time
+from enum import Enum
+
+from acta.git.branch import get_current_branch
+from acta.github import get_repo, gh
+
+_CHECKS_POLL_INTERVAL = 5  # seconds
+_CHECKS_QUEUE_TIMEOUT = 90  # seconds to wait for checks to appear
+
+_PASSING_CONCLUSIONS = {"SUCCESS", "NEUTRAL", "SKIPPED"}
+_PASSING_STATUS_STATES = {"SUCCESS"}
+_PENDING_STATUS_STATES = {"PENDING", "EXPECTED"}
+
+
+class ChecksState(Enum):
+    NONE = "none"
+    PENDING = "pending"
+    PASSED = "passed"
+    FAILED = "failed"
+
+
+def classify_rollup(nodes: list[dict[str, object]]) -> ChecksState:
+    """Reduce a `statusCheckRollup` to one state.
+
+    Each node is a `CheckRun` (GitHub Actions) or a legacy `StatusContext`. A check is
+    pending until it reaches a terminal state, passing only on an explicitly successful
+    one. Fail-safe: any terminal check that is not recognised as passing counts as
+    FAILED, so an unexpected state never reads as green on a ship gate.
+    """
+    if not nodes:
+        return ChecksState.NONE
+    any_pending = False
+    for node in nodes:
+        if node.get("__typename") == "StatusContext":
+            state = node.get("state")
+            if state in _PENDING_STATUS_STATES:
+                any_pending = True
+            elif state not in _PASSING_STATUS_STATES:
+                return ChecksState.FAILED
+        elif node.get("status") != "COMPLETED":
+            any_pending = True
+        elif node.get("conclusion") not in _PASSING_CONCLUSIONS:
+            return ChecksState.FAILED
+    return ChecksState.PENDING if any_pending else ChecksState.PASSED
+
+
+def fetch_checks_state(pr_number: int) -> ChecksState:
+    response_json = gh(
+        "pr",
+        "view",
+        str(pr_number),
+        "--repo",
+        get_repo(),
+        "--json",
+        "statusCheckRollup",
+        capture=True,
+    )
+    parsed: dict[str, list[dict[str, object]]] = json.loads(response_json)
+    return classify_rollup(parsed.get("statusCheckRollup") or [])
+
+
+def pr_create(title: str, body: str, base: str = "main") -> tuple[int, str]:
+    command_args = [
+        "pr",
+        "create",
+        "--base",
+        base,
+        "--title",
+        title,
+        "--body",
+        body,
+        "--repo",
+        get_repo(),
+    ]
+    pr_url = gh(*command_args, capture=True)
+    pr_number = int(pr_url.rstrip("/").split("/")[-1])
+    return pr_number, pr_url
+
+
+def pr_view() -> tuple[int, str]:
+    response_json = gh(
+        "pr",
+        "view",
+        get_current_branch(),
+        "--repo",
+        get_repo(),
+        "--json",
+        "number,title",
+        capture=True,
+    )
+    pr_data = json.loads(response_json)
+    return int(pr_data["number"]), str(pr_data["title"])
+
+
+def pr_checks_pass(pr_number: int) -> bool:
+    return fetch_checks_state(pr_number) in {ChecksState.PASSED, ChecksState.NONE}
+
+
+def pr_merge(pr_number: int) -> None:
+    gh("pr", "merge", str(pr_number), "--squash", "--delete-branch", "--repo", get_repo())
+
+
+def pr_checks_watch(pr_number: int) -> None:
+    for _ in range(_CHECKS_QUEUE_TIMEOUT // _CHECKS_POLL_INTERVAL):
+        if fetch_checks_state(pr_number) is not ChecksState.NONE:
+            break
+        time.sleep(_CHECKS_POLL_INTERVAL)
+    else:
+        return  # no checks ever appeared — nothing to watch
+    gh("pr", "checks", str(pr_number), "--repo", get_repo(), "--watch")