releez 0.2.2__py3-none-any.whl

releez/cliff.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import os
+import shutil
+import sysconfig
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from releez.errors import GitCliffVersionComputeError, MissingCliError
+from releez.process import run_checked
+
+GIT_CLIFF_BIN = 'git-cliff'
+GIT_CLIFF_TAG_PATTERN = '^[0-9]+\\.[0-9]+\\.[0-9]+$'
+
+GitCliffBump = Literal['major', 'minor', 'patch', 'auto']
+
+
+@dataclass(frozen=True)
+class ReleaseNotes:
+    """Generated release notes from git-cliff."""
+
+    version: str
+    markdown: str
+
+
+def _git_cliff_base_cmd() -> list[str]:
+    scripts_dir = sysconfig.get_path('scripts')
+    if scripts_dir:
+        scripts_path = Path(scripts_dir)
+        candidates = [GIT_CLIFF_BIN]
+        if os.name == 'nt':  # pragma: no cover
+            candidates = [
+                f'{GIT_CLIFF_BIN}.exe',
+                f'{GIT_CLIFF_BIN}.cmd',
+                f'{GIT_CLIFF_BIN}.bat',
+                GIT_CLIFF_BIN,
+            ]
+        for name in candidates:
+            exe = scripts_path / name
+            if exe.is_file():
+                return [str(exe)]
+
+    if shutil.which(GIT_CLIFF_BIN):
+        return [GIT_CLIFF_BIN]
+    raise MissingCliError(GIT_CLIFF_BIN)
+
+
+def _bump_args(bump: GitCliffBump) -> list[str]:
+    if bump == 'auto':
+        return ['--bump']
+    return ['--bump', bump]
+
+
+class GitCliff:
+    """Typed wrapper around the git-cliff CLI."""
+
+    def __init__(self, *, repo_root: Path) -> None:
+        self._repo_root = repo_root
+        self._cmd = _git_cliff_base_cmd()
+
+    def compute_next_version(self, *, bump: GitCliffBump) -> str:
+        """Compute the next version using git-cliff.
+
+        Args:
+            bump: The bump mode for git-cliff.
+
+        Returns:
+            The computed next version.
+
+        Raises:
+            MissingCliError: If `git-cliff` is not available.
+            ExternalCommandError: If git-cliff fails.
+            GitCliffVersionComputeError: If git-cliff returns an empty version.
+        """
+        version = run_checked(
+            [
+                *self._cmd,
+                '--unreleased',
+                '--bumped-version',
+                '--tag-pattern',
+                GIT_CLIFF_TAG_PATTERN,
+                *_bump_args(bump),
+            ],
+            cwd=self._repo_root,
+        ).strip()
+        if not version:
+            raise GitCliffVersionComputeError
+        return version
+
+    def generate_unreleased_notes(
+        self,
+        *,
+        version: str,
+    ) -> str:
+        """Generate the unreleased section as markdown.
+
+        Args:
+            version: The version to tag the release notes.
+
+        Returns:
+            The generated markdown content.
+
+        Raises:
+            MissingCliError: If `git-cliff` is not available.
+            ExternalCommandError: If git-cliff fails.
+        """
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            out_path = Path(tmp_dir) / 'RELEASE_NOTES.md'
+            run_checked(
+                [
+                    *self._cmd,
+                    '--unreleased',
+                    '--strip',
+                    'all',
+                    '--tag',
+                    version,
+                    '--tag-pattern',
+                    GIT_CLIFF_TAG_PATTERN,
+                    '--output',
+                    str(out_path),
+                ],
+                cwd=self._repo_root,
+                capture_stdout=False,
+            )
+            return out_path.read_text(encoding='utf-8')
+
+    def prepend_to_changelog(
+        self,
+        *,
+        version: str,
+        changelog_path: Path,
+    ) -> None:
+        """Prepend the unreleased section to the changelog file.
+
+        Args:
+            version: The version to tag the release notes.
+            changelog_path: The path to the changelog file.
+
+        Raises:
+            MissingCliError: If `git-cliff` is not available.
+            ExternalCommandError: If git-cliff fails.
+        """
+        run_checked(
+            [
+                *self._cmd,
+                '-v',
+                '--unreleased',
+                '--tag',
+                version,
+                '--tag-pattern',
+                GIT_CLIFF_TAG_PATTERN,
+                '--prepend',
+                str(changelog_path),
+            ],
+            cwd=self._repo_root,
+            capture_stdout=False,
+        )
+
+    def regenerate_changelog(
+        self,
+        *,
+        changelog_path: Path,
+    ) -> None:
+        """Regenerate the full changelog file from git history.
+
+        Args:
+            changelog_path: The path to the changelog file.
+
+        Raises:
+            MissingCliError: If `git-cliff` is not available.
+            ExternalCommandError: If git-cliff fails.
+        """
+        run_checked(
+            [
+                *self._cmd,
+                '-v',
+                '--tag-pattern',
+                GIT_CLIFF_TAG_PATTERN,
+                '--output',
+                str(changelog_path),
+            ],
+            cwd=self._repo_root,
+            capture_stdout=False,
+        )

releez/errors.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+class ReleezError(RuntimeError):
+    """Base error for Releez."""
+
+
+class MissingCliError(ReleezError):
+    """Raised when a required CLI executable is missing."""
+
+    cli_names: list[str]
+
+    def __init__(self, cli_names: str | Sequence[str]) -> None:
+        self.cli_names = [cli_names] if isinstance(cli_names, str) else list(cli_names)
+        if len(self.cli_names) == 1:
+            message = f'Required CLI {self.cli_names[0]!r} is not installed or not on PATH.'
+        else:
+            joined = ', '.join(repr(name) for name in self.cli_names)
+            message = f'Required CLIs {joined} are not installed or not on PATH.'
+        super().__init__(message)
+
+
+class ExternalCommandError(ReleezError):
+    """Raised when an external command returns a non-zero status."""
+
+    cmd_args: list[str]
+    returncode: int
+    stderr: str
+
+    def __init__(
+        self,
+        *,
+        cmd_args: Sequence[str],
+        returncode: int,
+        stderr: str | None = None,
+    ) -> None:
+        self.cmd_args = list(cmd_args)
+        self.returncode = returncode
+        self.stderr = (stderr or '').strip()
+
+        cmd = ' '.join(self.cmd_args)
+        message = f'Command failed ({self.returncode}): {cmd}'
+        if self.stderr:
+            message = f'{message}\n{self.stderr}'
+        super().__init__(message)
+
+
+class GitRepoRootResolveError(ReleezError):
+    """Raised when the git repository root cannot be determined."""
+
+    def __init__(self) -> None:
+        super().__init__('Failed to resolve git repository root.')
+
+
+class DirtyWorkingTreeError(ReleezError):
+    """Raised when the working tree is not clean."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            'Working tree is not clean. Commit or stash changes before running.',
+        )
+
+
+class GitRemoteNotFoundError(ReleezError):
+    """Raised when a configured git remote does not exist."""
+
+    remote_name: str
+
+    def __init__(self, remote_name: str) -> None:
+        self.remote_name = remote_name
+        super().__init__(f'Remote {remote_name!r} does not exist.')
+
+
+class GitRemoteBranchNotFoundError(ReleezError):
+    """Raised when a remote branch does not exist."""
+
+    ref: str
+
+    def __init__(self, *, remote_name: str, branch: str) -> None:
+        self.ref = f'{remote_name}/{branch}'
+        super().__init__(f'Remote branch {self.ref!r} does not exist.')
+
+
+class GitBranchExistsError(ReleezError):
+    """Raised when attempting to create a branch that already exists."""
+
+    branch: str
+
+    def __init__(self, branch: str) -> None:
+        self.branch = branch
+        super().__init__(f'Local branch {branch!r} already exists.')
+
+
+class GitCliffVersionComputeError(ReleezError):
+    """Raised when git-cliff cannot compute the next version."""
+
+    def __init__(self) -> None:
+        super().__init__('Failed to compute next version via git-cliff.')
+
+
+class ChangelogNotFoundError(ReleezError):
+    """Raised when the changelog file is missing."""
+
+    changelog_path: Path
+
+    def __init__(self, changelog_path: Path) -> None:
+        self.changelog_path = changelog_path
+        super().__init__(f'Changelog file does not exist: {changelog_path}')
+
+
+class ChangelogFormatCommandRequiredError(ReleezError):
+    """Raised when changelog formatting is requested but not configured."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            'Changelog formatting was requested, but no format command is configured.\n'
+            'Configure it via `releez.toml`:\n'
+            '  [hooks]\n'
+            '  changelog_format = ["dprint", "fmt", "{changelog}"]\n'
+            'Or via `pyproject.toml`:\n'
+            '  [tool.releez.hooks]\n'
+            '  changelog_format = ["dprint", "fmt", "{changelog}"]\n'
+            'Or pass `--changelog-format-cmd` (repeatable) on the CLI.',
+        )
+
+
+class GitHubTokenRequiredError(ReleezError):
+    """Raised when a GitHub token is required but not provided."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            'GitHub token is required to create a PR; pass --github-token or set GITHUB_TOKEN.',
+        )
+
+
+class GitRemoteUrlRequiredError(ReleezError):
+    """Raised when a remote URL is needed but missing."""
+
+    remote_name: str
+
+    def __init__(self, remote_name: str) -> None:
+        self.remote_name = remote_name
+        super().__init__(
+            f'Remote URL is required to create a PR; ensure remote {remote_name!r} exists.',
+        )
+
+
+class InvalidGitHubRemoteError(ReleezError):
+    """Raised when a remote URL cannot be mapped to a GitHub repo."""
+
+    remote_url: str
+
+    def __init__(self, remote_url: str) -> None:
+        self.remote_url = remote_url
+        super().__init__(
+            f'Could not infer GitHub repo from remote URL: {remote_url}\n'
+            'Use an origin remote pointing at GitHub (SSH or HTTPS).\n'
+            'If using GitHub Enterprise Server, set GITHUB_SERVER_URL (and optionally GITHUB_API_URL).',
+        )
+
+
+class MissingGitHubDependencyError(ReleezError):
+    """Raised when PyGithub is not available but PR creation was requested."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            'PyGithub is required for PR creation but is not available.',
+        )
+
+
+class BuildNumberRequiredError(ReleezError):
+    """Raised when a prerelease build is missing a build number."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            'Build number is required for prerelease builds; pass --build-number or set RELEEZ_BUILD_NUMBER.',
+        )
+
+
+class PrereleaseNumberRequiredError(ReleezError):
+    """Raised when a prerelease build is missing a prerelease number."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            'Prerelease number is required for prerelease builds; '
+            'pass --prerelease-number or set RELEEZ_PRERELEASE_NUMBER.',
+        )
+
+
+class InvalidReleaseVersionError(ReleezError):
+    """Raised when a version is not a full release `x.y.z`."""
+
+    version: str
+
+    def __init__(self, version: str) -> None:
+        self.version = version
+        super().__init__(
+            f'Expected a full release version like `2.3.4`; got {version!r}.',
+        )
+
+
+class GitTagExistsError(ReleezError):
+    """Raised when attempting to create a tag that already exists."""
+
+    tag: str
+
+    def __init__(self, tag: str) -> None:
+        self.tag = tag
+        super().__init__(
+            f'Git tag already exists: {tag!r} (use --force to update).',
+        )
+
+
+class InvalidPrereleaseTypeError(ReleezError):
+    """Raised when a prerelease type is invalid for the chosen scheme."""
+
+    prerelease_type: str
+    scheme: str
+
+    def __init__(self, prerelease_type: str, *, scheme: str) -> None:
+        self.prerelease_type = prerelease_type
+        self.scheme = scheme
+        super().__init__(
+            f'Prerelease type {prerelease_type!r} is not supported for scheme {scheme!r}.',
+        )

releez/git_repo.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+
+from git import Repo
+from git.exc import GitCommandError, GitCommandNotFound
+
+from releez.errors import (
+    DirtyWorkingTreeError,
+    GitBranchExistsError,
+    GitRemoteBranchNotFoundError,
+    GitRemoteNotFoundError,
+    GitRepoRootResolveError,
+    GitTagExistsError,
+    MissingCliError,
+)
+
+GIT_BIN = 'git'
+
+
+@dataclass(frozen=True)
+class RepoInfo:
+    """Information about a Git repository.
+
+    Attributes:
+        root: The root path of the repository.
+        remote_url: The URL of the 'origin' remote.
+        active_branch: The name of the currently active branch, or None if in
+            detached HEAD state.
+    """
+
+    root: Path
+    remote_url: str
+    active_branch: str | None
+
+
+def open_repo(*, cwd: Path | None = None) -> tuple[Repo, RepoInfo]:
+    """Open a Git repository and gather information about it.
+
+    Args:
+        cwd: The working directory to start searching for the repository.
+
+    Returns:
+        A tuple of the Repo object and RepoInfo dataclass.
+
+    Raises:
+        MissingCliError: If the `git` CLI is not available.
+        GitRepoRootResolveError: If the repository root cannot be determined.
+    """
+    repo = Repo(cwd or Path.cwd(), search_parent_directories=True)
+    try:
+        root = Path(
+            repo.working_tree_dir or repo.git.rev_parse('--show-toplevel'),
+        )
+    except GitCommandNotFound as exc:  # pragma: no cover
+        raise MissingCliError(GIT_BIN) from exc
+    except GitCommandError as exc:  # pragma: no cover
+        raise GitRepoRootResolveError from exc
+
+    remote_url = ''
+    with suppress(AttributeError, IndexError):
+        remote_url = repo.remotes.origin.url
+
+    active_branch: str | None
+    try:
+        active_branch = repo.active_branch.name
+    except TypeError:
+        active_branch = None  # detached HEAD
+
+    return repo, RepoInfo(
+        root=root,
+        remote_url=remote_url,
+        active_branch=active_branch,
+    )
+
+
+def ensure_clean(repo: Repo) -> None:
+    """Ensure the repository working tree is clean.
+
+    Args:
+        repo: The Git repository.
+
+    Raises:
+        DirtyWorkingTreeError: If the repository has uncommitted changes.
+    """
+    if repo.is_dirty(untracked_files=True):
+        raise DirtyWorkingTreeError
+
+
+def fetch(repo: Repo, *, remote_name: str) -> None:
+    """Fetch updates from the remote (including tags).
+
+    Args:
+        repo: The Git repository.
+        remote_name: The remote name to fetch from.
+
+    Raises:
+        GitRemoteNotFoundError: If the remote does not exist.
+    """
+    try:
+        _ = repo.remotes[remote_name]
+    except IndexError as exc:
+        raise GitRemoteNotFoundError(remote_name) from exc
+    repo.git.fetch(remote_name, '--tags', '--prune')
+
+
+def checkout_remote_branch(
+    repo: Repo,
+    *,
+    remote_name: str,
+    branch: str,
+) -> None:
+    """Check out the given remote branch as a detached HEAD.
+
+    Args:
+        repo: The Git repository.
+        remote_name: The remote name.
+        branch: The branch name on the remote.
+
+    Raises:
+        MissingCliError: If the `git` CLI is not available.
+        GitRemoteBranchNotFoundError: If the remote branch does not exist.
+    """
+    ref = f'{remote_name}/{branch}'
+    try:
+        repo.git.rev_parse('--verify', ref)
+    except GitCommandNotFound as exc:  # pragma: no cover
+        raise MissingCliError(GIT_BIN) from exc
+    except GitCommandError as exc:
+        raise GitRemoteBranchNotFoundError(
+            remote_name=remote_name,
+            branch=branch,
+        ) from exc
+    repo.git.checkout(ref)
+
+
+def create_and_checkout_branch(repo: Repo, *, name: str) -> None:
+    """Create and check out a new local branch.
+
+    Args:
+        repo: The Git repository.
+        name: The new branch name.
+
+    Raises:
+        MissingCliError: If the `git` CLI is not available.
+        GitBranchExistsError: If the local branch already exists.
+    """
+    try:
+        repo.git.rev_parse('--verify', name)
+    except GitCommandNotFound as exc:  # pragma: no cover
+        raise MissingCliError(GIT_BIN) from exc
+    except GitCommandError:
+        repo.git.checkout('-b', name)
+        return
+
+    raise GitBranchExistsError(name)
+
+
+def commit_file(repo: Repo, *, path: Path, message: str) -> None:
+    """Stage and commit a file with the given message.
+
+    Args:
+        repo: The Git repository.
+        path: The path to the file to stage and commit.
+        message: The commit message.
+    """
+    root = Path(repo.working_tree_dir or '.').resolve()
+    abs_path = path.resolve()
+    try:
+        rel_path = abs_path.relative_to(root)
+        pathspec = str(rel_path)
+    except ValueError:
+        pathspec = str(abs_path)
+    repo.index.add([pathspec])
+    repo.index.commit(message)
+
+
+def push_set_upstream(repo: Repo, *, remote_name: str, branch: str) -> None:
+    """Push a branch and set upstream on the remote.
+
+    Args:
+        repo: The Git repository.
+        remote_name: The remote name to push to.
+        branch: The branch to push.
+    """
+    repo.git.push('-u', remote_name, branch)
+
+
+def create_tags(repo: Repo, *, tags: list[str], force: bool) -> None:
+    """Create git tags pointing at HEAD.
+
+    Args:
+        repo: The Git repository.
+        tags: The tag names to create.
+        force: If true, overwrite existing tags.
+
+    Raises:
+        GitTagExistsError: If a tag exists and force is false.
+    """
+    existing = {t.name for t in repo.tags}
+    for tag in tags:
+        if tag in existing and not force:
+            raise GitTagExistsError(tag)
+        if force:
+            repo.git.tag('-f', tag)
+        else:
+            repo.create_tag(tag)
+
+
+def push_tags(
+    repo: Repo,
+    *,
+    remote_name: str,
+    tags: list[str],
+    force: bool,
+) -> None:
+    """Push git tags to a remote.
+
+    Args:
+        repo: The Git repository.
+        remote_name: The remote to push to.
+        tags: The tag names to push.
+        force: If true, force-update tags on the remote.
+    """
+    if not tags:
+        return
+    if force:
+        repo.git.push('--force', remote_name, *tags)
+        return
+    repo.git.push(remote_name, *tags)