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

auto_semver/config/_models/changelog.py

@@ -0,0 +1,104 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Configuration models for changelog generation."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from textwrap import dedent
+
+from jinja2 import Template, TemplateSyntaxError
+from pydantic import BaseModel, Field, field_serializer, field_validator
+
+from auto_semver.config._models.commit_group import CommitGroups
+from auto_semver.config.constants import DEFAULT_CHANGELOG
+
+
+@dataclass
+class ChangelogTemplateVars:
+    """Template variables for changelog rendering.
+
+    This dataclass defines the exact structure of variables that can be passed
+    to changelog templates, providing type safety and clear documentation of available
+    template variables.
+
+    Attributes:
+        version (str): The semantic version being released (e.g., "1.2.3").
+        date (str): Formatted date string for the release date.
+        messages (list[str]): List of raw commit messages since last version.
+        commit_groups (CommitGroups | None): Pre-processed commit groups (optional).
+    """
+
+    version: str
+    date: str
+    messages: list[str]
+    commit_groups: CommitGroups | None = None
+
+
+class ChangelogConfig(BaseModel):
+    """
+    Defines how the changelog should be generated and formatted.
+
+    Includes file path, overwrite behavior, and Jinja2 templates for
+    formatting the changelog entries. The templates support variables such
+    as `version`, `date`, and `messages`.
+
+    Attributes:
+        file (Path): The relative path to the changelog file to update.
+        truncate (bool): If True, overwrites the changelog file instead of prepending.
+        template (str): A Jinja2 template for formatting the changelog entry.
+        header (str | None): Optional header text placed above the changelog entry.
+        footer (str | None): Optional footer text placed below the changelog entry.
+
+    """
+
+    file: Path = Field(
+        default_factory=lambda: Path(DEFAULT_CHANGELOG), description="Path to the changelog file."
+    )
+
+    truncate: bool = Field(
+        default=False, description="If true, overwrite the changelog instead of prepending."
+    )
+
+    template: str = Field(
+        default=dedent(
+            """
+        ## [{{version}}] - {{date}}
+        {% for msg in messages -%}
+        - {{ msg }}
+        {%- endfor %}
+        """
+        ),
+        description="Jinja template for changelog entries.",
+    )
+
+    header: str | None = Field(default=None, description="Optional header text for the changelog.")
+    footer: str | None = Field(default=None, description="Optional footer text for the changelog.")
+
+    @field_serializer("file")
+    def serialize_path(self, value: Path) -> str:
+        """Serialize Path objects to strings."""
+        return str(value)
+
+    @field_validator("template")
+    @classmethod
+    def validate_template(cls, value: str) -> str:
+        """
+        Validate that the provided string is a valid Jinja2 template.
+
+        Args:
+            value (str): The template string to validate.
+
+        Returns:
+            str: The original value if it's a valid Jinja2 template.
+
+        Raises:
+            ValueError: If the template contains syntax errors.
+
+        """
+        try:
+            # Basic syntax validation using Jinja2 Template
+            Template(value)
+            return value
+        except TemplateSyntaxError as err:
+            raise ValueError(f"Invalid Jinja2 template: {err}") from err

auto_semver/config/_models/commit_group.py

@@ -0,0 +1,160 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Commit group configuration models."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+# Constants
+CONVENTIONAL_COMMIT_PARTS = 2
+
+type RegexPattern = str
+
+
+@dataclass
+class Commit:
+    r"""
+    Parsed commit message data structure for template rendering.
+
+    This dataclass represents a parsed commit message with extracted components
+    that can be used in Jinja2 templates for changelog and PR generation.
+
+    Attributes:
+        title (str): The cleaned, display-friendly commit title/summary line.
+                    For conventional commits, this extracts just the description part.
+                    Used for concise commit listings in changelogs and PRs.
+                    Example: "add OAuth2 support" (from "feat(auth): add OAuth2 support")
+
+        body (str | None): The extended commit message body, if present.
+                          Contains everything after the first line, preserving internal structure.
+                          None if the commit only has a title line.
+                          Used for detailed commit information in templates.
+                          Example: "Implements OAuth2 authentication flow\n\nBREAKING CHANGE: ..."
+    """
+
+    title: str
+    body: str | None = None
+
+
+@dataclass
+class CommitGroup:
+    """
+    Runtime data structure representing a single commit group with its commits.
+
+    This dataclass represents a categorized group of commits that have been matched
+    against specific patterns. Used as template data for Jinja2 rendering in
+    changelogs and pull requests.
+
+    Attributes:
+        title (str): The display title for this group of commits.
+            This appears as the section header in generated changelogs and PRs.
+            Examples: "🚀 Features", "🐛 Bug Fixes", "📝 Documentation"
+
+        commits (list[Commit]): List of parsed commit objects belonging to this group.
+            Each commit contains title and optional body text.
+            Sorted in the order they were processed from git history.
+
+        priority (int): Numeric priority for sorting groups in output.
+            Lower numbers appear first in generated content.
+            Used to ensure consistent ordering (e.g., Features before Bug Fixes).
+
+    Note:
+        This is typically created by CommitGroupConfig.group_messages() and consumed
+        by Jinja2 templates. Templates can iterate over commits and access their
+        title/body for formatting.
+
+    Example:
+        Template usage:
+        ```jinja2
+        {% for group in commit_groups %}
+        ## {{ group.title }}
+        {% for commit in group.commits %}
+        - {{ commit.title }}
+        {% endfor %}
+        {% endfor %}
+        ```
+    """
+
+    title: str
+    commits: list[Commit]
+    priority: int
+
+
+type CommitGroups = list[CommitGroup]
+"""
+Collection of commit groups for template rendering.
+
+This type alias represents the complete data structure returned by commit grouping
+operations and consumed by changelog/PR templates. It contains all categorized
+commits organized by their matching patterns.
+
+Note:
+    This is the primary data structure passed to Jinja2 templates for rendering
+    changelogs and pull request descriptions. Templates iterate over this list
+    to generate formatted output with proper grouping and ordering.
+
+Example:
+    ```python
+    commit_groups = CommitGroupConfig.group_messages(messages, config_groups)
+    # Returns:
+    [
+        {"title": "🚀 Features", "commits": [...], "priority": 1},
+        {"title": "🐛 Bug Fixes", "commits": [...], "priority": 2}
+    ]
+    ```
+
+    Template usage:
+    ```jinja2
+    {% for group in commit_groups %}
+    ## {{ group.title }}
+    {% for commit in group.commits %}
+    - {{ commit.title }}
+    {% endfor %}
+    {% endfor %}
+    ```
+
+Note:
+    Processing details:
+    - Groups are sorted by priority (lower numbers first)
+    - Empty groups (no matching commits) are filtered out
+    - Unmatched commits are placed in a catch-all or "Other Changes" group
+    - Each group maintains the original git history order of its commits
+"""
+
+
+class CommitGroupConfig(BaseModel):
+    """
+    Defines a group for categorizing commit messages by regex patterns.
+
+    Attributes:
+        title (str): Display title for this group of commits.
+        patterns (list[str]): List of regex patterns to match commit messages.
+        priority (int): Sort priority (lower numbers appear first).
+    """
+
+    title: str = Field(..., description="Display title for this commit group")
+    patterns: list[RegexPattern] = Field(..., description="List of regex patterns to match commits")
+    match_groups: list[str] = Field(
+        default_factory=list,
+        description="List of exact commit section headers to match (e.g. 'Bug Fixes')",
+    )
+    priority: int = Field(..., description="Sort priority (lower numbers first)")
+
+    @field_validator("patterns")
+    @classmethod
+    def validate_patterns(cls, patterns: list[RegexPattern]) -> list[RegexPattern]:
+        """Validate that all patterns are valid regex."""
+        for pattern in patterns:
+            try:
+                re.compile(pattern)
+            except re.error as err:
+                raise ValueError(f"Invalid regex pattern '{pattern}': {err}") from err
+        return patterns

auto_semver/config/_models/commit_groups.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Commit grouping settings and group definitions."""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from auto_semver.config._models.commit_group import CommitGroupConfig
+
+DEFAULT_IGNORE_LINE_PATTERNS: list[str] = [
+    r"^\[[ xX]\]",
+    r"^Co-authored-by:",
+    r"^Made with \[Cursor\]",
+    r"^---------",
+]
+
+
+class CommitGroupsConfig(BaseModel):
+    """Commit message grouping settings plus pattern-defined groups."""
+
+    summary_mode: Literal["header_only", "expand_body"] = Field(
+        default="header_only",
+        description="header_only emits one entry per git commit; expand_body parses bullets/sections",
+    )
+    ignore_line_patterns: list[str] = Field(
+        default_factory=lambda: list(DEFAULT_IGNORE_LINE_PATTERNS),
+        description="Regex patterns for lines dropped before grouping (expand_body mode)",
+    )
+    groups: list[CommitGroupConfig] = Field(
+        default_factory=list,
+        description="Pattern-defined commit groups for changelog and release PR templates",
+    )
+
+    @field_validator("ignore_line_patterns")
+    @classmethod
+    def validate_ignore_patterns(cls, patterns: list[str]) -> list[str]:
+        """Validate ignore-line regex patterns."""
+        for pattern in patterns:
+            try:
+                re.compile(pattern)
+            except re.error as err:
+                msg = f"Invalid ignore_line_patterns regex '{pattern}': {err}"
+                raise ValueError(msg) from err
+        return patterns
+
+    @classmethod
+    def from_yaml(cls, value: object | None) -> CommitGroupsConfig:
+        """Parse commit_groups from legacy list or structured dict YAML."""
+        if value is None:
+            return cls()
+        if isinstance(value, list):
+            return cls(groups=value)
+        if isinstance(value, dict):
+            groups = value.get("groups", [])
+            settings = {k: v for k, v in value.items() if k != "groups"}
+            return cls(groups=groups, **settings)
+        msg = f"commit_groups must be a list or mapping, got {type(value).__name__}"
+        raise TypeError(msg)

auto_semver/config/_models/config.py

@@ -0,0 +1,247 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Main configuration data model."""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import BaseModel, Field, field_serializer, field_validator, model_validator
+
+from auto_semver.config._models.bump import BumpConfig
+from auto_semver.config._models.changelog import ChangelogConfig
+from auto_semver.config._models.commit_group import CommitGroups
+from auto_semver.config._models.commit_groups import CommitGroupsConfig
+from auto_semver.config._models.lock_sync import LockSyncConfig
+from auto_semver.config._models.promotion import PromotionRule
+from auto_semver.config._models.pull_request import PullRequestConfig
+from auto_semver.config._models.release import ReleaseConfig
+from auto_semver.core.semver import Version
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigData(BaseModel):
+    """
+    Holds all validated configuration values loaded from auto_semver_config.yml.
+
+    This model represents the user-defined configuration for the auto-semver
+    process, including versioning behavior, changelog generation, PR metadata, and
+    supported branch strategies. It ensures that required fields are present and typed.
+
+    Attributes:
+        start_version (Version): The default version to use if no version file is found.
+        suffixes (dict[str, str]): Mapping of target branches to version suffixes
+            (e.g., {"main": "", "dev": "-dev"}).
+        version_files (list[str]): List of files to update with the new version string.
+        pull_request (PullRequestConfig): Configuration for the pull request title, body, and labels.
+        changelog (_ChangelogConfig): Changelog file behavior and formatting templates.
+
+    """
+
+    start_version: Version = Field(
+        default_factory=lambda: Version.parse("0.1.0"), description="Optional start_version."
+    )
+    suffixes: dict[str, str] = Field(..., description="Required branch suffix mapping.")
+    promotions: list[PromotionRule] = Field(
+        ..., description="Allowed branch promotion rules (from → to)."
+    )
+    version_files: list[str] = Field(
+        default=["version.txt"], description="Optional files that hold version format to update."
+    )
+    commit_groups: CommitGroupsConfig = Field(
+        default_factory=CommitGroupsConfig,
+        description="Commit grouping settings and pattern-defined groups for templates",
+    )
+    release: ReleaseConfig = Field(
+        default_factory=ReleaseConfig,
+        description="Release branch lifecycle (single vs multi, prefix, cleanup)",
+    )
+    bump: BumpConfig = Field(
+        default_factory=BumpConfig,
+        description="Version bump mode (classic semver vs cumulative)",
+    )
+    lock_sync: LockSyncConfig = Field(
+        default_factory=LockSyncConfig,
+        description="Package-manager lockfile sync after version-file rewrites",
+    )
+    pull_request: PullRequestConfig
+    changelog: ChangelogConfig
+
+    @field_validator("commit_groups", mode="before")
+    @classmethod
+    def parse_commit_groups(cls, value: CommitGroupsConfig | object | None) -> CommitGroupsConfig:
+        """Accept legacy YAML list format or structured commit_groups mapping."""
+        if isinstance(value, CommitGroupsConfig):
+            return value
+        return CommitGroupsConfig.from_yaml(value)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @field_validator("start_version", mode="before")
+    @classmethod
+    def validate_version(cls, value: str | Version) -> Version:
+        """Validate and parse the start_version field."""
+        if isinstance(value, Version):
+            return value
+        try:
+            return Version.parse(value)
+        except ValueError:
+            raise
+
+    @field_serializer("start_version")
+    def serialize_version(self, value: Version) -> str:
+        """Serialize Version objects to strings."""
+        return str(value)
+
+    @model_validator(mode="after")
+    def validate_promotions_have_suffixes(self) -> ConfigData:
+        """Validate that all branches in promotion rules have suffix definitions."""
+        # Validate that all promotion targets have suffixes
+        missing_suffixes = {
+            rule.to_branch for rule in self.promotions if rule.to_branch not in self.suffixes
+        }
+
+        if missing_suffixes:
+            raise ValueError(
+                f"The following promotion targets are missing suffix definitions: {sorted(missing_suffixes)}"
+            )
+
+        # Validate no reverse rules exist
+        seen_pairs = set()
+        for rule in self.promotions:
+            reverse = (rule.to_branch, rule.from_branch)
+            if reverse in seen_pairs:
+                raise ValueError(
+                    f"Invalid promotion configuration: reverse rule found for "
+                    f"'{rule.from_branch} → {rule.to_branch}'"
+                )
+            seen_pairs.add((rule.from_branch, rule.to_branch))
+
+        return self
+
+    @model_validator(mode="after")
+    def validate_unique_patterns(self) -> ConfigData:
+        """
+        Validate that regex patterns are unique across all commit groups.
+
+        This ensures deterministic grouping of commits. If a pattern appears
+        in multiple groups, it creates ambiguity about which group a commit
+        should belong to.
+        """
+        seen_patterns: dict[str, str] = {}
+
+        for group in self.commit_groups.groups:
+            for pattern in group.patterns:
+                # We check for exact string matches.
+                # Semantically identical regexes (e.g. [a-z] vs [a-z]) are hard to detect,
+                # but catching exact duplicates prevents most configuration errors.
+                if pattern in seen_patterns:
+                    existing_group = seen_patterns[pattern]
+                    # Allow duplicate patterns only if they are the catch-all ".*"
+                    # strictly speaking catch-all should also be unique, but let's be strict for now.
+                    if pattern == ".*":
+                        logger.debug("Duplicate catch-all pattern '.*' detected, permitting.")
+                        continue
+
+                    raise ValueError(
+                        f"Duplicate pattern '{pattern}' found in groups: "
+                        f"'{existing_group}' and '{group.title}'. "
+                        "Patterns must be unique to ensure deterministic grouping."
+                    )
+                seen_patterns[pattern] = group.title
+
+        return self
+
+    def group_commit_messages(self, messages: list[str]) -> CommitGroups:
+        """
+        Group commit messages using the configured commit groups.
+
+        Args:
+            messages: List of commit messages to group
+
+        Returns:
+            CommitGroups: list of CommitGroup dataclasses for template rendering.
+        """
+        # Lazy import: config package init must not pull core.commits at module load.
+        from auto_semver.core.commits.grouper import CommitGrouper  # noqa: PLC0415
+
+        return CommitGrouper.group_messages(messages, self.commit_groups)
+
+    def find_promotion_rule(self, *, from_branch: str, to_branch: str) -> PromotionRule | None:
+        """
+        Find a promotion rule that allows promotion from source to target branch.
+
+        Args:
+            from_branch: Source branch name
+            to_branch: Target branch name
+
+        Returns:
+            PromotionRule if found, None otherwise
+        """
+        for rule in self.promotions:
+            if rule.from_branch == from_branch and rule.to_branch == to_branch:
+                return rule
+        return None
+
+    def validate_promotion(
+        self, *, from_branch: str, to_branch: str, require_auto_promote: bool = False
+    ) -> PromotionRule:
+        """
+        Validate that a promotion between branches is allowed by configuration.
+
+        Args:
+            from_branch: Source branch name
+            to_branch: Target branch name
+            require_auto_promote: If True, only allow promotions with auto_promote=True
+
+        Returns:
+            PromotionRule: The matching promotion rule
+
+        Raises:
+            ValueError: If promotion is not allowed
+        """
+        # Check if both branches are configured
+        if from_branch not in self.suffixes:
+            raise ValueError(f"Source branch '{from_branch}' is not configured in suffixes")
+
+        if to_branch not in self.suffixes:
+            raise ValueError(f"Target branch '{to_branch}' is not configured in suffixes")
+
+        # Find promotion rule
+        rule = self.find_promotion_rule(from_branch=from_branch, to_branch=to_branch)
+
+        if rule is None:
+            raise ValueError(
+                f"No promotion rule found from '{from_branch}' to '{to_branch}'. "
+                f"Available rules: {[(r.from_branch, r.to_branch) for r in self.promotions]}"
+            )
+
+        # Check auto_promote requirement if specified
+        if require_auto_promote and not rule.auto_promote:
+            raise ValueError(
+                f"Promotion from '{from_branch}' to '{to_branch}' is not configured for auto-promotion"
+            )
+
+        logger.info(
+            f"Promotion validated: {from_branch} → {to_branch} (auto_promote={rule.auto_promote})"
+        )
+        return rule
+
+    def get_auto_promotion_targets(self, *, from_branch: str) -> list[str]:
+        """
+        Get all target branches that can be auto-promoted from the given branch.
+
+        Args:
+            from_branch: Source branch name
+
+        Returns:
+            List of target branch names that have auto_promote=True
+        """
+        targets = []
+        for rule in self.promotions:
+            if rule.from_branch == from_branch and rule.auto_promote:
+                targets.append(rule.to_branch)
+
+        return targets

auto_semver/config/_models/lock_sync.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Package-manager lockfile sync configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from auto_semver.lock_sync.registry import default_registry, ensure_builtins_registered
+
+
+class LockSyncConfig(BaseModel):
+    """Controls post-bump sync of language package lockfiles.
+
+    A missing host ``uv`` or ``npm`` patches only the project version. There is
+    no skip/fail switch for that case. Older configs may still contain
+    ``on_missing``; that key is ignored.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    enabled: bool = Field(
+        default=True,
+        description="When true, sync known lockfiles after version-file rewrites",
+    )
+    ecosystems: list[str] | None = Field(
+        default=None,
+        description=(
+            "Allow-list of ecosystems to sync (registered strategy names). "
+            "Omit to auto-detect every known lockfile present at the repo root."
+        ),
+    )
+
+    @field_validator("ecosystems", mode="before")
+    @classmethod
+    def validate_ecosystems(cls, value: object) -> object:
+        """Reject unknown ecosystem names early with a clear message."""
+        if value is None:
+            return value
+        if not isinstance(value, list):
+            raise ValueError("ecosystems must be a list of ecosystem names")
+        ensure_builtins_registered()
+        known = default_registry.names()
+        unknown = [item for item in value if item not in known]
+        if unknown:
+            raise ValueError(f"Unknown lock_sync ecosystems: {unknown}. Supported: {sorted(known)}")
+        return value

auto_semver/config/_models/promotion.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2025-2026 Guy Erreich
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Promotion rule models."""
+
+import re
+
+from pydantic import BaseModel, Field, field_validator
+
+# Constants for branch name validation
+MIN_BRANCH_NAME_LENGTH = 1
+MAX_BRANCH_NAME_LENGTH = 250
+
+# Git branch name validation pattern
+BRANCH_NAME_PATTERN = re.compile(
+    r"^(?!.*(?:\.lock$|\.lock/|/\.|\.{2}|@{|\\))"  # Cannot end with .lock, contain /.., @{, or \
+    r"(?!.*(?://|^/|/$))"  # Cannot contain //, start/end with /
+    r"(?![~^:\s?*\[\]])"  # Cannot start with ~^: or contain space?*[]
+    r"[^\000-\037\177~^:\s?*\[\]]*"  # Cannot contain control chars, space, ~^:?*[]
+    r"(?<!\.lock)$"  # Cannot end with .lock
+)
+
+type BranchName = str
+
+
+class PromotionRule(BaseModel):
+    """Represents a rule for promoting versions between branches."""
+
+    from_branch: BranchName = Field(
+        ...,
+        min_length=MIN_BRANCH_NAME_LENGTH,
+        max_length=MAX_BRANCH_NAME_LENGTH,
+        description="Source branch name",
+    )
+
+    to_branch: BranchName = Field(
+        ...,
+        min_length=MIN_BRANCH_NAME_LENGTH,
+        max_length=MAX_BRANCH_NAME_LENGTH,
+        description="Target branch name",
+    )
+
+    auto_promote: bool = Field(
+        default=False,
+        description=(
+            "Whether to automatically promote (direct branch update + tag) after "
+            "tagging the source branch. Does not open a promotion PR."
+        ),
+    )
+
+    @field_validator("from_branch", "to_branch")
+    @classmethod
+    def validate_branch_name(cls, value: str) -> str:
+        """
+        Validate that the branch name follows Git branch naming rules.
+
+        Args:
+            value: The branch name to validate.
+
+        Returns:
+            str: The validated branch name.
+
+        Raises:
+            ValueError: If the branch name is invalid.
+        """
+        if not BRANCH_NAME_PATTERN.match(value):
+            raise ValueError(
+                f"Invalid branch name '{value}'. Branch names must follow Git naming rules: "
+                "cannot contain spaces, control characters, or special sequences like //, .., "
+                "cannot start with /, cannot end with .lock, etc."
+            )
+        return value