auto-semver-control 1.8.7.dev0__py3-none-any.whl

auto_semver/cli/promote.py

@@ -0,0 +1,211 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+CLI command for manually promoting versions between branches.
+
+This command allows users to promote versions manually, with validation
+against the configured promotion rules.
+"""
+
+import logging
+
+from auto_semver.adapters.git import GitOps
+from auto_semver.cli.utils import build_promotion_metadata_hook, promotion_prefer_source_paths
+from auto_semver.config import Config
+from auto_semver.core.semver import Version
+from runview import get_summary, log_group, status
+
+logger = logging.getLogger(__name__)
+
+
+def run(
+    *,
+    gitops: GitOps,
+    config: Config,
+    to_branch: str,
+    from_branch: str | None = None,
+    from_tag: str | None = None,
+    dry_run: bool = False,
+) -> None:
+    """
+    Promote a version from one branch to another directly (merge + tag).
+
+    Args:
+        gitops (GitOps): Git operations handler.
+        config (Config): Loaded configuration object.
+        to_branch (str): Target branch name.
+        from_branch (str | None): Source branch name. Optional if tag is provided.
+        from_tag (str | None): Specific tag to promote. If None, uses latest from branch.
+        dry_run (bool): If True, validate only without performing git operations.
+
+    Raises:
+        ValueError: If promotion is not allowed or fails.
+    """
+    logger.info(f"Initiating manual promotion to {to_branch}")
+    summary = get_summary()
+    summary.set("command", "promote")
+    summary.set("dry-run", "yes" if dry_run else "no")
+
+    with log_group("Validate"):
+        with status("Resolving source version..."):
+            try:
+                version, source_branch = _get_source_version(gitops, config, from_tag, from_branch)
+            except Exception as e:
+                raise ValueError(f"Failed to get version from source: {e}") from e
+
+        # Validate promotion is allowed
+        promotion_rule = config.data.validate_promotion(
+            from_branch=source_branch,
+            to_branch=to_branch,
+            require_auto_promote=False,
+        )
+
+        logger.info(
+            f"Promotion validated: {promotion_rule.from_branch} → {promotion_rule.to_branch}"
+        )
+        logger.info(f"Found version {version} to promote")
+        summary.set("branches", f"{source_branch} -> {to_branch}")
+
+        _validate_target_version(gitops, to_branch, version)
+
+        if dry_run:
+            logger.info("🧪 Dry run mode: Skipping promotion.")
+            summary.set("outcome", "dry-run")
+            return
+
+        # Calculate promoted version
+        target_suffix = config.data.suffixes.get(to_branch, "")
+        promoted_version = Version(
+            major=version.major,
+            minor=version.minor,
+            patch=version.patch,
+            suffix=target_suffix if target_suffix else None,
+        )
+        summary.set("version", f"{version} -> {promoted_version}")
+        logger.info(f"Promoting version {version} → {promoted_version}")
+
+    with log_group("Merge/tag"):
+        try:
+            # Use tag as source if available, otherwise use branch
+            merge_source = from_tag if from_tag else source_branch
+            use_source_tag = bool(from_tag)
+
+            metadata_hook = build_promotion_metadata_hook(
+                config=config,
+                source_branch=source_branch,
+                target_branch=to_branch,
+                gitops=gitops,
+            )
+
+            with status("Merging and tagging..."):
+                gitops.auto_promote(
+                    source_branch=merge_source,
+                    target_branch=to_branch,
+                    version=str(promoted_version),
+                    source_version=str(version),
+                    is_source_tag=use_source_tag,
+                    post_merge_hook=metadata_hook,
+                    prefer_source_paths=promotion_prefer_source_paths(config),
+                )
+
+            logger.info(f"✅ Promotion completed successfully: {source_branch} → {to_branch}")
+            logger.info(f"Tagged {to_branch} with {promoted_version}")
+
+        except Exception as e:
+            raise ValueError(f"Failed to promote: {e}") from e
+
+
+def _get_source_version(
+    gitops: GitOps,
+    config: Config,
+    from_tag: str | None,
+    from_branch: str | None,
+) -> tuple[Version, str]:
+    """
+    Retrieve the source version and branch.
+
+    Args:
+        gitops: Git operations handler.
+        config: Configuration object.
+        from_tag: Optional tag to promote from.
+        from_branch: Optional branch to promote from.
+
+    Returns:
+        tuple[Version, str]: The version and the source branch name.
+
+    Raises:
+        ValueError: If version cannot be determined or source branch cannot be inferred.
+    """
+    if from_tag:
+        logger.info(f"Using specified tag: {from_tag}")
+
+        version: Version | None
+        # Try to parse version from tag name first
+        try:
+            version = Version.parse(from_tag)
+            logger.info(f"Parsed version from tag name: {version}")
+        except ValueError:
+            logger.warning(
+                f"Could not parse version from tag name '{from_tag}'. Falling back to lockfile."
+            )
+            version = gitops.get_lock_version_from_tag(tag_name=from_tag)
+
+        if not version:
+            raise ValueError(f"No version found for tag '{from_tag}'.")
+
+        suffix = version.suffix or ""
+        # Find branch that matches the version's suffix
+        from_branch = None
+        for branch, s in config.data.suffixes.items():
+            if s == suffix:
+                from_branch = branch
+                break
+
+        if not from_branch:
+            raise ValueError(
+                f"Could not determine source branch from version suffix '{suffix}' "
+                f"in tag '{from_tag}'."
+            )
+        logger.info(f"Inferred source branch '{from_branch}' from tag '{from_tag}'")
+        return version, from_branch
+
+    if from_branch:
+        logger.info(f"Using latest version from branch: {from_branch}")
+        branch_version = gitops.get_lock_version_from_branch(branch_name=from_branch)
+        if not branch_version:
+            raise ValueError(
+                f"No version found for branch '{from_branch}'. Ensure the branch is tagged."
+            )
+        return branch_version, from_branch
+
+    raise ValueError("Either --from-branch or --from-tag must be provided.")
+
+
+def _validate_target_version(gitops: GitOps, to_branch: str, source_version: Version) -> None:
+    """
+    Ensure the source version is greater than the target branch version.
+
+    Args:
+        gitops: Git operations handler.
+        to_branch: Target branch name.
+        source_version: The version being promoted.
+
+    Raises:
+        ValueError: If source version is not greater than target version.
+    """
+    try:
+        target_version = gitops.get_lock_version_from_branch(branch_name=to_branch)
+        if target_version:
+            logger.info(f"Current version on {to_branch}: {target_version}")
+            if source_version <= target_version:
+                raise ValueError(
+                    f"Cannot promote version {source_version} to {to_branch} because it is not greater "
+                    f"than the current version {target_version}."
+                )
+        else:
+            logger.info(f"No existing version found on {to_branch}. Proceeding.")
+    except Exception as e:
+        if isinstance(e, ValueError) and "Cannot promote" in str(e):
+            raise
+        logger.warning(f"Could not verify target branch version: {e}. Proceeding with caution.")

auto_semver/cli/setup.py

@@ -0,0 +1,154 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""CLI command to onboard a repository onto Action-Semver-Control."""
+
+from __future__ import annotations
+
+import logging
+import webbrowser
+from pathlib import Path
+
+from auto_semver.setup.links import (
+    SETUP_DOC_URL,
+    app_registration_url,
+    workflow_bump_deep_link,
+    workflow_promote_deep_link,
+)
+from auto_semver.setup.scaffold import (
+    RepoRef,
+    detect_repo,
+    scaffold_files,
+    set_repo_secret,
+    set_repo_variable,
+    verify_gh_authenticated,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def run(
+    *,
+    owner: str | None = None,
+    repo: str | None = None,
+    default_branch: str | None = None,
+    app_id: str | None = None,
+    client_id: str | None = None,
+    private_key_path: Path | None = None,
+    dry_run: bool = False,
+    open_browser: bool = False,
+    skip_secrets: bool = False,
+    skip_scaffold: bool = False,
+) -> None:
+    """Guide setup of GitHub App credentials and consumer workflow files.
+
+    Args:
+        owner: GitHub repository owner (defaults to origin remote).
+        repo: GitHub repository name (defaults to origin remote).
+        default_branch: Base branch for deep links and scaffolding context.
+        app_id: Deprecated alias for client_id (kept for CLI compatibility).
+        client_id: GitHub App Client ID (preferred; from app settings).
+        private_key_path: Path to the App private key PEM file.
+        dry_run: Print actions without writing secrets or files.
+        open_browser: Open the prefilled App registration URL in a browser.
+        skip_secrets: Skip writing GH_APP_CLIENT_ID and GH_APP_PRIVATE_KEY.
+        skip_scaffold: Skip writing config and workflow files.
+    """
+    repo_ref = _resolve_repo(owner=owner, repo=repo, default_branch=default_branch)
+    reg_url = app_registration_url()
+
+    print("Action-Semver-Control setup")
+    print("===========================")
+    print()
+    print("1. Register a GitHub App (Contents + Pull requests: read/write, webhooks off):")
+    print(f"   {reg_url}")
+    print()
+    install_target = f"{repo_ref.owner}/{repo_ref.repo}"
+    print("2. Install the app on this repository:")
+    print(f"   https://github.com/settings/apps (Install App → {install_target})")
+    print()
+    print("3. Generate a private key and note the App **Client ID** (not the numeric App ID).")
+    print()
+
+    if open_browser and not dry_run:
+        webbrowser.open(reg_url)
+
+    if not skip_secrets:
+        verify_gh_authenticated()
+        resolved_client_id = (client_id or app_id or _prompt("GitHub App Client ID")).strip()
+        key_path = private_key_path or Path(_prompt("Path to private key .pem file"))
+        private_key = key_path.read_text(encoding="utf-8")
+        set_repo_variable(
+            owner=repo_ref.owner,
+            repo=repo_ref.repo,
+            name="GH_APP_CLIENT_ID",
+            value=resolved_client_id,
+            dry_run=dry_run,
+        )
+        set_repo_secret(
+            owner=repo_ref.owner,
+            repo=repo_ref.repo,
+            name="GH_APP_PRIVATE_KEY",
+            value=private_key,
+            dry_run=dry_run,
+        )
+        print("Repository variable GH_APP_CLIENT_ID and secret GH_APP_PRIVATE_KEY configured.")
+    else:
+        print("Skipped credential configuration (--skip-secrets).")
+
+    if not skip_scaffold:
+        written = scaffold_files(Path.cwd(), dry_run=dry_run)
+        if written:
+            print("Scaffolded files:")
+            for path in written:
+                print(f"  - {path}")
+        else:
+            print("No new files scaffolded (targets already exist).")
+    else:
+        print("Skipped file scaffolding (--skip-scaffold).")
+
+    bump_link = workflow_bump_deep_link(
+        owner=repo_ref.owner,
+        repo=repo_ref.repo,
+        branch=repo_ref.default_branch,
+    )
+    promote_link = workflow_promote_deep_link(
+        owner=repo_ref.owner,
+        repo=repo_ref.repo,
+        branch=repo_ref.default_branch,
+    )
+
+    print()
+    print("Optional: add workflows via the GitHub UI instead of local scaffold:")
+    print(f"  Bump:    {bump_link}")
+    print(f"  Promote: {promote_link}")
+    print()
+    print(f"Full guide: {SETUP_DOC_URL}")
+    print()
+    print("Next: merge a PR to dev/staging/master to trigger the first semver bump.")
+
+
+def _resolve_repo(
+    *,
+    owner: str | None,
+    repo: str | None,
+    default_branch: str | None,
+) -> RepoRef:
+    if owner and repo:
+        return RepoRef(owner=owner, repo=repo, default_branch=default_branch or "master")
+    detected = detect_repo()
+    if default_branch:
+        return RepoRef(
+            owner=detected.owner,
+            repo=detected.repo,
+            default_branch=default_branch,
+        )
+    return detected
+
+
+def _prompt(label: str) -> str:
+    value = input(f"{label}: ").strip()
+    if not value:
+        msg = f"{label} is required"
+        raise ValueError(msg)
+    return value

auto_semver/cli/utils.py

@@ -0,0 +1,161 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""CLI utility functions for auto_semver."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from auto_semver.adapters.github import GitHubEvent
+from auto_semver.config import Config
+from auto_semver.config.constants import PR_HIDDEN_MARKER
+from auto_semver.core.changelog.manager import ChangelogManager
+from auto_semver.core.semver import SemverLock, Version
+from auto_semver.core.semver.updater import VersionFileUpdater
+from auto_semver.lock_sync import sync_package_locks
+
+if TYPE_CHECKING:
+    from auto_semver.adapters.git import GitOps
+
+logger = logging.getLogger(__package__)
+
+
+def promotion_prefer_source_paths(config: Config) -> list[str]:
+    """Paths that diverge by design during promotion and may take the source side."""
+    paths: list[str] = [SemverLock.path]
+    if config.data.changelog and config.data.changelog.file:
+        paths.append(str(config.data.changelog.file))
+    paths.extend(str(path) for path in config.data.version_files)
+    return paths
+
+
+def apply_promotion_metadata(
+    *,
+    config: Config,
+    source_branch: str,
+    source_version: str,
+    target_version: str,
+    target_branch: str,
+    merge_sha: str,
+    repo_root: Path,
+    sync_locks: bool = True,
+) -> None:
+    """Rewrite changelog, version files, and lock for a promoted target branch."""
+    rule = config.data.find_promotion_rule(from_branch=source_branch, to_branch=target_branch)
+    if rule is None:
+        logger.warning(
+            "Promotion metadata for %s → %s does not match any promotions[] rule in config",
+            source_branch,
+            target_branch,
+        )
+
+    if config.data.changelog and config.data.changelog.file:
+        try:
+            manager = ChangelogManager.from_config(config)
+            manager.update_version_in_header(old_version=source_version, new_version=target_version)
+        except Exception as err:
+            logger.warning("Failed to update changelog header during promotion: %s", err)
+
+    promoted = Version.parse(target_version)
+    for file_path in config.data.version_files:
+        VersionFileUpdater(file_path=str(file_path), version=promoted).update()
+
+    if sync_locks:
+        sync_package_locks(repo_root=repo_root, config=config.data.lock_sync)
+
+    try:
+        lock = SemverLock.load_from_file()
+        lock.as_promotion_baseline(
+            source_branch=source_branch,
+            target_branch=target_branch,
+            version=promoted,
+            merge_sha=merge_sha,
+        )
+        lock.save_to_file()
+    except FileNotFoundError:
+        logger.warning("No lockfile found during promotion metadata update")
+
+
+def build_promotion_metadata_hook(
+    *,
+    config: Config,
+    source_branch: str,
+    target_branch: str,
+    gitops: GitOps,
+    sync_locks: bool = True,
+) -> Callable[[str, str], None]:
+    """Build a post-merge hook that applies dev/rc metadata on the target branch.
+
+    Args:
+        config: Loaded configuration.
+        source_branch: Branch the version is leaving.
+        target_branch: Branch receiving the promotion.
+        gitops: Git operations for the current repo.
+        sync_locks: When false, leave lockfiles for the runner CLI step.
+    """
+
+    def hook(source_version: str, target_version: str) -> None:
+        apply_promotion_metadata(
+            config=config,
+            source_branch=source_branch,
+            source_version=source_version,
+            target_version=target_version,
+            target_branch=target_branch,
+            merge_sha=gitops.repo.head.commit.hexsha,
+            repo_root=Path(gitops.repo.working_tree_dir or "."),
+            sync_locks=sync_locks,
+        )
+
+    return hook
+
+
+def is_finalized(*, config: Config, event: GitHubEvent) -> bool:
+    """
+    Check if the PR was generated by the script.
+
+    If the PR is auto generated by the script then we should start the finalization workflow
+    else its a bump workflow.
+
+    Args:
+        config (Config): Config object.
+        event (GitHubEvent): GitHubEvent object.
+
+    """
+    logger.debug("Checking if the merged PR matches the finalized state")
+
+    body: str = event.get_body()
+    labels: list[str] = event.get_labels_safe()
+
+    expected_labels: list[str] = config.data.pull_request.labels
+
+    reasons = []
+
+    # Labels
+    missing_labels = set(expected_labels) - set(labels)
+    if missing_labels:
+        reasons.append(f"Missing labels: {sorted(missing_labels)}")
+        reasons.append(f"   All PR labels: {sorted(labels)}")
+        reasons.append(f"   Expected labels: {sorted(expected_labels)}")
+
+    # Identity: marker + labels only. Title templates may include {{date}} and other
+    # runtime vars that cannot be re-rendered identically at finalize time.
+
+    # Body
+    if PR_HIDDEN_MARKER not in body:
+        reasons.append("Body mismatch:")
+        reasons.append("    Hidden marker is not found in the body content.")
+        reasons.append("    The body was not generated by semver auto.")
+
+    if reasons:
+        logger.info("Detected bump workflow (not a finalize release PR)")
+        for reason in reasons:
+            logger.debug(reason)
+        return False
+
+    logger.info("Detected finalize workflow")
+
+    return True

auto_semver/config/__init__.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Public config package entry point.
+
+Import ``Config`` and schema types from here — never from ``config._models``.
+``_models`` is a private implementation detail of this package.
+"""
+
+from auto_semver.config._models import (
+    BranchName,
+    BumpConfig,
+    ChangelogConfig,
+    Commit,
+    CommitGroup,
+    CommitGroupConfig,
+    CommitGroups,
+    CommitGroupsConfig,
+    ConfigData,
+    LockSyncConfig,
+    PromotionRule,
+    PullRequestConfig,
+    RegexPattern,
+    ReleaseConfig,
+)
+from auto_semver.config._models.changelog import ChangelogTemplateVars
+from auto_semver.config._models.pull_request import PullRequestTemplateVars
+from auto_semver.config.config import Config
+
+__all__ = [
+    "BranchName",
+    "BumpConfig",
+    "ChangelogConfig",
+    "ChangelogTemplateVars",
+    "Commit",
+    "CommitGroup",
+    "CommitGroupConfig",
+    "CommitGroups",
+    "CommitGroupsConfig",
+    "Config",
+    "ConfigData",
+    "LockSyncConfig",
+    "PromotionRule",
+    "PullRequestConfig",
+    "PullRequestTemplateVars",
+    "RegexPattern",
+    "ReleaseConfig",
+]

auto_semver/config/_models/__init__.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+from auto_semver.config._models.bump import BumpConfig
+from auto_semver.config._models.changelog import ChangelogConfig
+from auto_semver.config._models.commit_group import (
+    Commit,
+    CommitGroup,
+    CommitGroupConfig,
+    CommitGroups,
+    RegexPattern,
+)
+from auto_semver.config._models.commit_groups import CommitGroupsConfig
+from auto_semver.config._models.config import ConfigData
+from auto_semver.config._models.lock_sync import LockSyncConfig
+from auto_semver.config._models.promotion import BranchName, PromotionRule
+from auto_semver.config._models.pull_request import PullRequestConfig
+from auto_semver.config._models.release import ReleaseConfig
+
+__all__ = [
+    "BranchName",
+    "BumpConfig",
+    "ChangelogConfig",
+    "Commit",
+    "CommitGroup",
+    "CommitGroupConfig",
+    "CommitGroups",
+    "CommitGroupsConfig",
+    "ConfigData",
+    "LockSyncConfig",
+    "PromotionRule",
+    "PullRequestConfig",
+    "RegexPattern",
+    "ReleaseConfig",
+]

auto_semver/config/_models/bump.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Version bump mode configuration."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class BumpConfig(BaseModel):
+    """Controls how version numbers increment between releases."""
+
+    mode: Literal["classic", "cumulative"] = Field(
+        default="classic",
+        description=(
+            "classic: semver (minor resets patch). "
+            "cumulative: patch accumulates fixes, minor accumulates features without patch reset"
+        ),
+    )