Add Git utilities, semantic version helpers, and unit tests

Ref: https://chatgpt.com/share/6936c64b-ae80-800f-ae7e-ed0a692ec3fc

pkgmgr/git_utils.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Lightweight helper functions around Git commands.
+
+These helpers are intentionally small wrappers so that higher-level
+logic (release, version, changelog) does not have to deal with the
+details of subprocess handling.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import List, Optional
+
+
+class GitError(RuntimeError):
+    """Raised when a Git command fails in an unexpected way."""
+
+
+def run_git(args: List[str], cwd: str = ".") -> str:
+    """
+    Run a Git command and return its stdout as a stripped string.
+
+    Raises GitError if the command fails.
+    """
+    cmd = ["git"] + args
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        raise GitError(
+            f"Git command failed in {cwd!r}: {' '.join(cmd)}\n"
+            f"Exit code: {exc.returncode}\n"
+            f"STDOUT:\n{exc.stdout}\n"
+            f"STDERR:\n{exc.stderr}"
+        ) from exc
+
+    return result.stdout.strip()
+
+
+def get_tags(cwd: str = ".") -> List[str]:
+    """
+    Return a list of all tags in the repository in `cwd`.
+
+    If there are no tags, an empty list is returned.
+    """
+    try:
+        output = run_git(["tag"], cwd=cwd)
+    except GitError as exc:
+        # If the repo has no tags or is not a git repo, surface a clear error.
+        # You can decide later if you want to treat this differently.
+        if "not a git repository" in str(exc):
+            raise
+        # No tags: stdout may just be empty; treat this as empty list.
+        return []
+
+    if not output:
+        return []
+
+    return [line.strip() for line in output.splitlines() if line.strip()]
+
+
+def get_head_commit(cwd: str = ".") -> Optional[str]:
+    """
+    Return the current HEAD commit hash, or None if it cannot be determined.
+    """
+    try:
+        output = run_git(["rev-parse", "HEAD"], cwd=cwd)
+    except GitError:
+        return None
+    return output or None
+
+
+def get_current_branch(cwd: str = ".") -> Optional[str]:
+    """
+    Return the current branch name, or None if it cannot be determined.
+
+    Note: In detached HEAD state this will return 'HEAD'.
+    """
+    try:
+        output = run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd)
+    except GitError:
+        return None
+    return output or None

pkgmgr/versioning.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Utilities for working with semantic versions (SemVer).
+
+This module is intentionally small and self-contained so it can be
+used by release/version/changelog commands without pulling in any
+heavy dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Tuple
+
+
+@dataclass(frozen=True, order=True)
+class SemVer:
+    """Simple semantic version representation (MAJOR.MINOR.PATCH)."""
+
+    major: int
+    minor: int
+    patch: int
+
+    @classmethod
+    def parse(cls, value: str) -> "SemVer":
+        """
+        Parse a version string like '1.2.3' or 'v1.2.3' into a SemVer.
+
+        Raises ValueError if the format is invalid.
+        """
+        text = value.strip()
+        if text.startswith("v"):
+            text = text[1:]
+
+        parts = text.split(".")
+        if len(parts) != 3:
+            raise ValueError(f"Not a valid semantic version: {value!r}")
+
+        try:
+            major = int(parts[0])
+            minor = int(parts[1])
+            patch = int(parts[2])
+        except ValueError as exc:
+            raise ValueError(f"Semantic version components must be integers: {value!r}") from exc
+
+        if major < 0 or minor < 0 or patch < 0:
+            raise ValueError(f"Semantic version components must be non-negative: {value!r}")
+
+        return cls(major=major, minor=minor, patch=patch)
+
+    def to_tag(self, with_prefix: bool = True) -> str:
+        """
+        Convert the version into a tag string: 'v1.2.3' (default) or '1.2.3'.
+        """
+        core = f"{self.major}.{self.minor}.{self.patch}"
+        return f"v{core}" if with_prefix else core
+
+    def __str__(self) -> str:
+        return self.to_tag(with_prefix=False)
+
+
+def is_semver_tag(tag: str) -> bool:
+    """
+    Return True if the given tag string looks like a SemVer tag.
+
+    Accepts both '1.2.3' and 'v1.2.3' formats.
+    """
+    try:
+        SemVer.parse(tag)
+        return True
+    except ValueError:
+        return False
+
+
+def extract_semver_from_tags(
+    tags: Iterable[str],
+    major: Optional[int] = None,
+    minor: Optional[int] = None,
+) -> List[Tuple[str, SemVer]]:
+    """
+    Filter and parse tags that match SemVer, optionally restricted
+    to a specific MAJOR or MAJOR.MINOR line.
+
+    Returns a list of (tag_string, SemVer) pairs.
+    """
+    result: List[Tuple[str, SemVer]] = []
+    for tag in tags:
+        try:
+            ver = SemVer.parse(tag)
+        except ValueError:
+            # Ignore non-SemVer tags
+            continue
+
+        if major is not None and ver.major != major:
+            continue
+        if minor is not None and ver.minor != minor:
+            continue
+
+        result.append((tag, ver))
+
+    return result
+
+
+def find_latest_version(
+    tags: Iterable[str],
+    major: Optional[int] = None,
+    minor: Optional[int] = None,
+) -> Optional[Tuple[str, SemVer]]:
+    """
+    Find the latest SemVer tag from the given tags.
+
+    If `major` is given, only consider that MAJOR line.
+    If `minor` is given as well, only consider that MAJOR.MINOR line.
+
+    Returns a tuple (tag_string, SemVer) or None if no SemVer tag matches.
+    """
+    candidates = extract_semver_from_tags(tags, major=major, minor=minor)
+    if not candidates:
+        return None
+
+    # SemVer is orderable thanks to dataclass(order=True)
+    tag, ver = max(candidates, key=lambda item: item[1])
+    return tag, ver
+
+
+def bump_major(version: SemVer) -> SemVer:
+    """
+    Bump MAJOR: MAJOR+1.0.0
+    """
+    return SemVer(major=version.major + 1, minor=0, patch=0)
+
+
+def bump_minor(version: SemVer) -> SemVer:
+    """
+    Bump MINOR: MAJOR.MINOR+1.0
+    """
+    return SemVer(major=version.major, minor=version.minor + 1, patch=0)
+
+
+def bump_patch(version: SemVer) -> SemVer:
+    """
+    Bump PATCH: MAJOR.MINOR.PATCH+1
+    """
+    return SemVer(major=version.major, minor=version.minor, patch=version.patch + 1)