releez 0.2.2__py3-none-any.whl

releez/github.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from releez.errors import InvalidGitHubRemoteError, MissingGitHubDependencyError
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    """A minimal representation of a created GitHub pull request.
+
+    Attributes:
+        url: The PR URL.
+        number: The PR number.
+    """
+
+    url: str
+    number: int
+
+
+@dataclass(frozen=True)
+class PullRequestCreateRequest:
+    """Parameters for creating a GitHub pull request.
+
+    Attributes:
+        remote_url: The git remote URL used to infer the GitHub repo.
+        token: GitHub token used for authentication.
+        base: The base branch for the PR.
+        head: The head branch for the PR.
+        title: The PR title.
+        body: The PR body.
+        labels: Labels to add to the PR.
+    """
+
+    remote_url: str
+    token: str
+    base: str
+    head: str
+    title: str
+    body: str
+    labels: list[str]
+
+
+_SCP_SSH_RE = re.compile(
+    r'^git@(?P<host>[^:]+):(?P<full>[^/]+/[^/]+?)(?:\\.git)?$',
+)
+_SSH_URL_RE = re.compile(
+    r'^ssh://git@(?P<host>[^/]+)/(?P<full>[^/]+/[^/]+?)(?:\\.git)?$',
+)
+_HTTPS_RE = re.compile(
+    r'^https?://(?P<host>[^/]+)/(?P<full>[^/]+/[^/]+?)(?:\\.git)?$',
+)
+
+
+def _github_api_base_url_from_env() -> str | None:
+    api_url = os.getenv('RELEEZ_GITHUB_API_URL') or os.getenv('GITHUB_API_URL')
+    if api_url:
+        return api_url.rstrip('/')
+
+    server_url = os.getenv('RELEEZ_GITHUB_SERVER_URL') or os.getenv(
+        'GITHUB_SERVER_URL',
+    )
+    if not server_url:
+        return None
+    return f'{server_url.rstrip("/")}/api/v3'
+
+
+def _allowed_github_hosts_from_env() -> set[str]:
+    hosts = {'github.com'}
+
+    for var in (
+        'RELEEZ_GITHUB_SERVER_URL',
+        'GITHUB_SERVER_URL',
+        'RELEEZ_GITHUB_API_URL',
+        'GITHUB_API_URL',
+    ):
+        raw = os.getenv(var)
+        if not raw:
+            continue
+        parsed = urlparse(raw)
+        if parsed.hostname:
+            hosts.add(parsed.hostname)
+            continue
+        # allow plain host values (not URLs)
+        hosts.add(raw.strip().rstrip('/'))
+
+    return hosts
+
+
+def _parse_github_full_name(remote_url: str) -> str:
+    remote_url = remote_url.strip()
+    for regex in (_SCP_SSH_RE, _SSH_URL_RE, _HTTPS_RE):
+        m = regex.match(remote_url)
+        if m:
+            host = m.group('host')
+            if host not in _allowed_github_hosts_from_env():
+                raise InvalidGitHubRemoteError(remote_url)
+            full_name = m.group('full')
+            if full_name.endswith('.git'):
+                full_name = full_name.removesuffix('.git')
+            return full_name
+    raise InvalidGitHubRemoteError(remote_url)
+
+
+def create_pull_request(request: PullRequestCreateRequest) -> PullRequest:
+    """Create a GitHub pull request.
+
+    Args:
+        request: The parameters needed to create the pull request.
+
+    Returns:
+        The created PR URL and number.
+
+    Raises:
+        MissingGitHubDependencyError: If PyGithub is not installed.
+        InvalidGitHubRemoteError: If the remote URL cannot be mapped to a GitHub repo.
+    """
+    try:
+        from github import Github  # noqa: PLC0415
+    except ImportError as exc:
+        raise MissingGitHubDependencyError from exc
+
+    full_name = _parse_github_full_name(request.remote_url)
+    base_url = _github_api_base_url_from_env()
+    gh = (
+        Github(
+            login_or_token=request.token,
+            base_url=base_url,
+        )
+        if base_url
+        else Github(request.token)
+    )
+    repo = gh.get_repo(full_name)
+    pr = repo.create_pull(
+        title=request.title,
+        body=request.body,
+        base=request.base,
+        head=request.head,
+    )
+    if request.labels:
+        pr.add_to_labels(*request.labels)
+    return PullRequest(url=pr.html_url, number=pr.number)

releez/process.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING
+
+from releez.errors import ExternalCommandError, MissingCliError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+def run_checked(
+    args: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    capture_stdout: bool = True,
+) -> str:
+    """Run a command and raise a ReleezError on failure.
+
+    Args:
+        args: The command and arguments to execute.
+        cwd: Optional working directory for the command.
+        capture_stdout: If false, stdout is not captured.
+
+    Returns:
+        The stripped stdout of the command.
+
+    Raises:
+        MissingCliError: If the executable is not found.
+        ExternalCommandError: If the command exits non-zero.
+    """
+    try:
+        res = subprocess.run(  # noqa: S603
+            list(args),
+            cwd=cwd,
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE if capture_stdout else None,
+            stderr=subprocess.PIPE,
+        )
+    except FileNotFoundError as exc:
+        raise MissingCliError(args[0]) from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or '').strip()
+        raise ExternalCommandError(
+            cmd_args=args,
+            returncode=exc.returncode,
+            stderr=stderr,
+        ) from exc
+
+    return (res.stdout or '').strip()

releez/release.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from git import Repo
+
+from releez.cliff import GitCliff, GitCliffBump
+from releez.errors import (
+    ChangelogFormatCommandRequiredError,
+    GitHubTokenRequiredError,
+    GitRemoteUrlRequiredError,
+)
+from releez.git_repo import (
+    checkout_remote_branch,
+    commit_file,
+    create_and_checkout_branch,
+    ensure_clean,
+    fetch,
+    open_repo,
+    push_set_upstream,
+)
+from releez.github import PullRequestCreateRequest, create_pull_request
+from releez.utils import resolve_changelog_path, run_changelog_formatter
+
+
+@dataclass(frozen=True)
+class StartReleaseResult:
+    """Result of starting a release.
+
+    Attributes:
+        version: The computed next version.
+        release_notes_markdown: The generated release notes markdown.
+        release_branch: The created release branch, or None in dry-run mode.
+        pr_url: The created PR URL, or None if not created.
+    """
+
+    version: str
+    release_notes_markdown: str
+    release_branch: str | None
+    pr_url: str | None
+
+
+@dataclass(frozen=True)
+class StartReleaseInput:
+    """Inputs for starting a release.
+
+    Attributes:
+        bump: Bump mode for git-cliff.
+        version_override: Override the computed next version.
+        base_branch: Base branch for the release PR.
+        remote_name: Remote name to use.
+        labels: Labels to add to the PR.
+        title_prefix: Prefix for PR title / commit message.
+        changelog_path: Changelog file to prepend to.
+        run_changelog_format: If true, run the configured changelog formatter before commit.
+        changelog_format_cmd: Optional argv list to run for formatting (overrides config).
+        create_pr: If true, create a GitHub pull request.
+        github_token: GitHub token for PR creation.
+        dry_run: If true, do not modify the repo; just output version and notes.
+    """
+
+    bump: GitCliffBump
+    version_override: str | None
+    base_branch: str
+    remote_name: str
+    labels: list[str]
+    title_prefix: str
+    changelog_path: str
+    run_changelog_format: bool
+    changelog_format_cmd: list[str] | None
+    create_pr: bool
+    github_token: str | None
+    dry_run: bool
+
+
+@dataclass(frozen=True)
+class _MaybeCreatePullRequestInput:
+    """Inputs for optionally creating a pull request.
+
+    Attributes:
+        create_pr: If true, create a GitHub pull request.
+        github_token: GitHub token for PR creation.
+        remote_name: Remote name used to infer the repo URL.
+        base_branch: The base branch for the PR.
+        head_branch: The head branch for the PR.
+        title: The PR title.
+        body: The PR body.
+        labels: Labels to add to the PR.
+    """
+
+    create_pr: bool
+    github_token: str | None
+    remote_name: str
+    base_branch: str
+    head_branch: str
+    title: str
+    body: str
+    labels: list[str]
+
+
+def _maybe_create_pull_request(
+    *,
+    repo: Repo,
+    pr_input: _MaybeCreatePullRequestInput,
+) -> str | None:
+    if not pr_input.create_pr:
+        return None
+    if not pr_input.github_token:
+        raise GitHubTokenRequiredError
+
+    remote_url = repo.remotes[pr_input.remote_name].url
+    if not remote_url:
+        raise GitRemoteUrlRequiredError(pr_input.remote_name)
+
+    request = PullRequestCreateRequest(
+        remote_url=remote_url,
+        token=pr_input.github_token,
+        base=pr_input.base_branch,
+        head=pr_input.head_branch,
+        title=pr_input.title,
+        body=pr_input.body,
+        labels=pr_input.labels,
+    )
+    pr = create_pull_request(request)
+    return pr.url
+
+
+def _resolve_release_version(
+    *,
+    cliff: GitCliff,
+    release_input: StartReleaseInput,
+) -> str:
+    if release_input.version_override is not None:
+        return release_input.version_override
+    return cliff.compute_next_version(bump=release_input.bump)
+
+
+def _format_changelog_if_requested(
+    *,
+    repo_root: Path,
+    changelog_path: Path,
+    release_input: StartReleaseInput,
+) -> None:
+    if not release_input.run_changelog_format:
+        return
+    if not release_input.changelog_format_cmd:
+        raise ChangelogFormatCommandRequiredError
+    run_changelog_formatter(
+        changelog_path=changelog_path,
+        repo_root=repo_root,
+        changelog_format_cmd=release_input.changelog_format_cmd,
+    )
+
+
+def start_release(
+    release_input: StartReleaseInput,
+) -> StartReleaseResult:
+    """Start a release.
+
+    Args:
+        release_input: The input parameters for starting the release.
+
+    Returns:
+        The version, release notes, and (if created) branch/PR details.
+
+    Raises:
+        ReleezError: If a release step fails (git, git-cliff, or GitHub).
+    """
+    repo, info = open_repo()
+    ensure_clean(repo)
+    fetch(repo, remote_name=release_input.remote_name)
+
+    cliff = GitCliff(repo_root=info.root)
+    if not release_input.dry_run:
+        checkout_remote_branch(
+            repo,
+            remote_name=release_input.remote_name,
+            branch=release_input.base_branch,
+        )
+
+    version = _resolve_release_version(cliff=cliff, release_input=release_input)
+    notes = cliff.generate_unreleased_notes(version=version)
+
+    if release_input.dry_run:
+        return StartReleaseResult(
+            version=version,
+            release_notes_markdown=notes,
+            release_branch=None,
+            pr_url=None,
+        )
+
+    release_branch = f'release/{version}'
+    create_and_checkout_branch(repo, name=release_branch)
+
+    changelog = resolve_changelog_path(
+        changelog_path=release_input.changelog_path,
+        repo_root=info.root,
+    )
+    cliff.prepend_to_changelog(version=version, changelog_path=changelog)
+    _format_changelog_if_requested(
+        repo_root=info.root,
+        changelog_path=changelog,
+        release_input=release_input,
+    )
+
+    commit_file(
+        repo,
+        path=changelog,
+        message=f'{release_input.title_prefix}{version}',
+    )
+
+    push_set_upstream(
+        repo,
+        remote_name=release_input.remote_name,
+        branch=release_branch,
+    )
+
+    pr_url = _maybe_create_pull_request(
+        repo=repo,
+        pr_input=_MaybeCreatePullRequestInput(
+            create_pr=release_input.create_pr,
+            github_token=release_input.github_token,
+            remote_name=release_input.remote_name,
+            base_branch=release_input.base_branch,
+            head_branch=release_branch,
+            title=f'{release_input.title_prefix}{version}',
+            body=notes,
+            labels=release_input.labels,
+        ),
+    )
+
+    return StartReleaseResult(
+        version=version,
+        release_notes_markdown=notes,
+        release_branch=release_branch,
+        pr_url=pr_url,
+    )

releez/settings.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pydantic import AliasChoices, AliasGenerator, BaseModel, ConfigDict, Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    PyprojectTomlConfigSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+from releez.version_tags import AliasVersions
+
+
+def _to_kebab(name: str) -> str:
+    """Convert snake_case to kebab-case."""
+    return name.replace('_', '-')
+
+
+def _validation_alias(name: str) -> AliasChoices:
+    """Accept both snake_case and kebab-case for settings keys.
+
+    `AliasChoices` order matters: we list the snake_case field name first so if both
+    variants are present (e.g. env var + pyproject), the env var wins.
+    """
+    return AliasChoices(name, _to_kebab(name))
+
+
+_ALIASES = AliasGenerator(
+    validation_alias=_validation_alias,
+    serialization_alias=_to_kebab,
+)
+
+
+class ReleezHooks(BaseModel):
+    """Hook-related configuration.
+
+    Attributes:
+        changelog_format: Optional argv list used to format the changelog (e.g.
+            ["dprint", "fmt", "{changelog}"]).
+    """
+
+    model_config = ConfigDict(
+        alias_generator=_ALIASES,
+        populate_by_name=True,
+    )
+
+    changelog_format: list[str] | None = None
+
+
+class ReleezSettings(BaseSettings):
+    """Settings loaded from CLI args, env vars, and config files.
+
+    Precedence (highest first):
+      1. Explicit init kwargs (CLI layer)
+      2. RELEEZ_* env vars
+      3. releez.toml
+      4. pyproject.toml ([tool.releez])
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix='RELEEZ_',
+        env_nested_delimiter='__',
+        extra='ignore',
+        pyproject_toml_table_header=('tool', 'releez'),
+        alias_generator=_ALIASES,
+        populate_by_name=True,
+    )
+
+    base_branch: str = 'master'
+    git_remote: str = 'origin'
+    pr_labels: str = 'release'
+    pr_title_prefix: str = 'chore(release): '
+    changelog_path: str = 'CHANGELOG.md'
+    create_pr: bool = False
+    run_changelog_format: bool = False
+    alias_versions: AliasVersions = AliasVersions.none
+    hooks: ReleezHooks = Field(default_factory=ReleezHooks)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Customize settings sources for Releez."""
+        _ = (dotenv_settings, file_secret_settings)
+        releez_toml = TomlConfigSettingsSource(
+            settings_cls,
+            toml_file='releez.toml',
+        )
+        pyproject_toml = PyprojectTomlConfigSettingsSource(settings_cls)
+        return (
+            init_settings,
+            env_settings,
+            releez_toml,
+            pyproject_toml,
+        )

releez/subapps/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from releez.subapps.changelog import changelog_app
+
+__all__ = ['changelog_app']

releez/subapps/changelog.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from releez.cliff import GitCliff
+from releez.errors import ChangelogFormatCommandRequiredError, ReleezError
+from releez.git_repo import open_repo
+from releez.utils import resolve_changelog_path, run_changelog_formatter
+
+changelog_app = typer.Typer(help='Changelog utilities.')
+
+
+def _run_changelog_formatter_with_message(
+    *,
+    changelog_path: Path,
+    repo_root: Path,
+    changelog_format_cmd: list[str],
+) -> None:
+    """Run the changelog formatter command and print success message."""
+    run_changelog_formatter(
+        changelog_path=changelog_path,
+        repo_root=repo_root,
+        changelog_format_cmd=changelog_format_cmd,
+    )
+    typer.secho(
+        '✓ Ran changelog format hook',
+        fg=typer.colors.GREEN,
+    )
+
+
+@changelog_app.command('regenerate')
+def changelog_regenerate(
+    *,
+    changelog_path: Annotated[
+        str,
+        typer.Option(
+            '--changelog-path',
+            help='Path to the changelog file.',
+            show_default=True,
+        ),
+    ] = 'CHANGELOG.md',
+    run_changelog_format: Annotated[
+        bool,
+        typer.Option(
+            '--run-changelog-format',
+            help='Run the configured changelog formatter after regeneration.',
+            show_default=True,
+        ),
+    ] = False,
+    changelog_format_cmd: Annotated[
+        list[str] | None,
+        typer.Option(
+            '--changelog-format-cmd',
+            help='Override changelog format command argv (repeatable).',
+            show_default=False,
+        ),
+    ] = None,
+) -> None:
+    """Regenerate the full changelog from git history."""
+    try:
+        if run_changelog_format and not changelog_format_cmd:
+            raise ChangelogFormatCommandRequiredError
+
+        _, info = open_repo()
+        changelog = resolve_changelog_path(changelog_path, info.root)
+
+        cliff = GitCliff(repo_root=info.root)
+        cliff.regenerate_changelog(changelog_path=changelog)
+        typer.secho(
+            f'✓ Regenerated changelog: {changelog}',
+            fg=typer.colors.GREEN,
+        )
+
+        if run_changelog_format and changelog_format_cmd:
+            _run_changelog_formatter_with_message(
+                changelog_path=changelog,
+                repo_root=info.root,
+                changelog_format_cmd=changelog_format_cmd,
+            )
+    except ReleezError as exc:
+        typer.secho(str(exc), err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc

releez/utils.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from releez.errors import ChangelogNotFoundError
+from releez.process import run_checked
+
+
+def resolve_changelog_path(changelog_path: str, repo_root: Path) -> Path:
+    """Resolve the changelog path relative to the repo root.
+
+    Args:
+        changelog_path: Path to the changelog file (absolute or relative).
+        repo_root: Root directory of the git repository.
+
+    Returns:
+        The resolved absolute path to the changelog.
+
+    Raises:
+        ChangelogNotFoundError: If the changelog file doesn't exist.
+    """
+    changelog = Path(changelog_path)
+    if not changelog.is_absolute():
+        changelog = repo_root / changelog
+    if not changelog.exists():
+        raise ChangelogNotFoundError(changelog)
+    return changelog
+
+
+def run_changelog_formatter(
+    *,
+    changelog_path: Path,
+    repo_root: Path,
+    changelog_format_cmd: list[str],
+) -> None:
+    """Run the changelog formatter command.
+
+    Args:
+        changelog_path: Path to the changelog file to format.
+        repo_root: Root directory to run the command from.
+        changelog_format_cmd: Command argv list with optional {changelog} placeholder.
+    """
+    cmd = [arg.replace('{changelog}', str(changelog_path)) for arg in changelog_format_cmd]
+    run_checked(cmd, cwd=repo_root, capture_stdout=False)