feat(bump_rule): add BumpRule, VersionIncrement, Prerelease Enum

Closes #129

Author: bearomorphism

commitizen/bump.py

@@ -2,61 +2,14 @@
 
 import os
 import re
-from collections import OrderedDict
 from collections.abc import Iterable
 from glob import iglob
-from logging import getLogger
 from string import Template
-from typing import cast
 
-from commitizen.defaults import BUMP_MESSAGE, ENCODING, MAJOR, MINOR, PATCH
+from commitizen.defaults import BUMP_MESSAGE, ENCODING
 from commitizen.exceptions import CurrentVersionNotFoundError
-from commitizen.git import GitCommit, smart_open
-from commitizen.version_schemes import Increment, Version
-
-VERSION_TYPES = [None, PATCH, MINOR, MAJOR]
-
-logger = getLogger("commitizen")
-
-
-def find_increment(
-    commits: list[GitCommit], regex: str, increments_map: dict | OrderedDict
-) -> Increment | None:
-    if isinstance(increments_map, dict):
-        increments_map = OrderedDict(increments_map)
-
-    # Most important cases are major and minor.
-    # Everything else will be considered patch.
-    select_pattern = re.compile(regex)
-    increment: str | None = None
-
-    for commit in commits:
-        for message in commit.message.split("\n"):
-            result = select_pattern.search(message)
-
-            if result:
-                found_keyword = result.group(1)
-                new_increment = None
-                for match_pattern in increments_map.keys():
-                    if re.match(match_pattern, found_keyword):
-                        new_increment = increments_map[match_pattern]
-                        break
-
-                if new_increment is None:
-                    logger.debug(
-                        f"no increment needed for '{found_keyword}' in '{message}'"
-                    )
-
-                if VERSION_TYPES.index(increment) < VERSION_TYPES.index(new_increment):
-                    logger.debug(
-                        f"increment detected is '{new_increment}' due to '{found_keyword}' in '{message}'"
-                    )
-                    increment = new_increment
-
-                if increment == MAJOR:
-                    break
-
-    return cast(Increment, increment)
+from commitizen.git import smart_open
+from commitizen.version_schemes import Version
 
 
 def update_version_in_files(

commitizen/bump_rule.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from enum import IntEnum, auto
+from functools import cached_property
+from typing import Callable, Protocol
+
+from commitizen.exceptions import NoPatternMapError
+
+
+class VersionIncrement(IntEnum):
+    """An enumeration representing semantic versioning increments.
+
+    This class defines the three types of version increments according to semantic versioning:
+    - PATCH: For backwards-compatible bug fixes
+    - MINOR: For backwards-compatible functionality additions
+    - MAJOR: For incompatible API changes
+    """
+
+    PATCH = auto()
+    MINOR = auto()
+    MAJOR = auto()
+
+    def __str__(self) -> str:
+        return self.name
+
+    @classmethod
+    def safe_cast(cls, value: object) -> VersionIncrement | None:
+        if not isinstance(value, str):
+            return None
+        try:
+            return cls[value]
+        except KeyError:
+            return None
+
+    @classmethod
+    def safe_cast_dict(cls, d: Mapping[str, object]) -> dict[str, VersionIncrement]:
+        return {
+            k: v
+            for k, v in ((k, VersionIncrement.safe_cast(v)) for k, v in d.items())
+            if v is not None
+        }
+
+    @staticmethod
+    def get_highest_by_messages(
+        commit_messages: Iterable[str],
+        get_increment: Callable[[str], VersionIncrement | None],
+    ) -> VersionIncrement | None:
+        """Find the highest version increment from a list of messages.
+
+        This function processes a list of messages and determines the highest version
+        increment needed based on the commit messages. It splits multi-line commit messages
+        and evaluates each line using the provided get_increment callable.
+
+        Args:
+            commit_messages: A list of messages to analyze.
+            get_increment: A callable that takes a commit message string and returns an
+                VersionIncrement value (MAJOR, MINOR, PATCH) or None if no increment is needed.
+
+        Returns:
+            The highest version increment needed (MAJOR, MINOR, PATCH) or None if no
+            increment is needed. The order of precedence is MAJOR > MINOR > PATCH.
+
+        Example:
+            >>> commit_messages = ["feat: new feature", "fix: bug fix"]
+            >>> rule = ConventionalCommitBumpRule()
+            >>> VersionIncrement.get_highest_by_messages(commit_messages, lambda x: rule.get_increment(x, False))
+            'MINOR'
+        """
+        return VersionIncrement.get_highest(
+            get_increment(line)
+            for message in commit_messages
+            for line in message.split("\n")
+        )
+
+    @staticmethod
+    def get_highest(
+        increments: Iterable[VersionIncrement | None],
+    ) -> VersionIncrement | None:
+        return max(filter(None, increments), default=None)
+
+
+class BumpRule(Protocol):
+    """A protocol defining the interface for version bump rules.
+
+    This protocol specifies the contract that all version bump rule implementations must follow.
+    It defines how commit messages should be analyzed to determine the appropriate semantic
+    version increment.
+
+    The protocol is used to ensure consistent behavior across different bump rule implementations,
+    such as conventional commits or custom rules.
+    """
+
+    def get_increment(
+        self, commit_message: str, major_version_zero: bool
+    ) -> VersionIncrement | None:
+        """Determine the version increment based on a commit message.
+
+        This method analyzes a commit message to determine what kind of version increment
+        is needed according to the Conventional Commits specification. It handles special
+        cases for breaking changes and respects the major_version_zero flag.
+
+        Args:
+            commit_message: The commit message to analyze. Should follow conventional commit format.
+            major_version_zero: If True, breaking changes will result in a MINOR version bump
+                              instead of MAJOR. This is useful for projects in 0.x.x versions.
+
+        Returns:
+            VersionIncrement | None: The type of version increment needed:
+                - MAJOR: For breaking changes when major_version_zero is False
+                - MINOR: For breaking changes when major_version_zero is True, or for new features
+                - PATCH: For bug fixes, performance improvements, or refactors
+                - None: For commits that don't require a version bump (docs, style, etc.)
+        """
+
+
+class ConventionalCommitBumpRule(BumpRule):
+    _BREAKING_CHANGE_TYPES = set(["BREAKING CHANGE", "BREAKING-CHANGE"])
+    _MINOR_CHANGE_TYPES = set(["feat"])
+    _PATCH_CHANGE_TYPES = set(["fix", "perf", "refactor"])
+
+    def get_increment(
+        self, commit_message: str, major_version_zero: bool
+    ) -> VersionIncrement | None:
+        if not (m := self._head_pattern.match(commit_message)):
+            return None
+
+        change_type = m.group("change_type")
+        if m.group("bang") or change_type in self._BREAKING_CHANGE_TYPES:
+            return (
+                VersionIncrement.MINOR if major_version_zero else VersionIncrement.MAJOR
+            )
+
+        if change_type in self._MINOR_CHANGE_TYPES:
+            return VersionIncrement.MINOR
+
+        if change_type in self._PATCH_CHANGE_TYPES:
+            return VersionIncrement.PATCH
+
+        return None
+
+    @cached_property
+    def _head_pattern(self) -> re.Pattern:
+        change_types = [
+            *self._BREAKING_CHANGE_TYPES,
+            *self._PATCH_CHANGE_TYPES,
+            *self._MINOR_CHANGE_TYPES,
+            "docs",
+            "style",
+            "test",
+            "build",
+            "ci",
+        ]
+        re_change_type = r"(?P<change_type>" + "|".join(change_types) + r")"
+        re_scope = r"(?P<scope>\(.+\))?"
+        re_bang = r"(?P<bang>!)?"
+        return re.compile(f"^{re_change_type}{re_scope}{re_bang}:")
+
+
+class CustomBumpRule(BumpRule):
+    def __init__(
+        self,
+        bump_pattern: str,
+        bump_map: Mapping[str, VersionIncrement],
+        bump_map_major_version_zero: Mapping[str, VersionIncrement],
+    ) -> None:
+        """Initialize a custom bump rule for version incrementing.
+
+        This constructor creates a rule that determines how version numbers should be
+        incremented based on commit messages. It validates and compiles the provided
+        pattern and maps for use in version bumping.
+
+        The fallback logic is used for backward compatibility.
+
+        Args:
+            bump_pattern: A regex pattern string used to match commit messages.
+                Example: r"^((?P<major>major)|(?P<minor>minor)|(?P<patch>patch))(?P<scope>\(.+\))?(?P<bang>!)?:"
+                Or with fallback regex: r"^((BREAKING[\-\ ]CHANGE|\w+)(\(.+\))?!?):"  # First group is type
+            bump_map: A mapping of commit types to their corresponding version increments.
+                Example: {
+                    "major": VersionIncrement.MAJOR,
+                    "bang": VersionIncrement.MAJOR,
+                    "minor": VersionIncrement.MINOR,
+                    "patch": VersionIncrement.PATCH
+                }
+                Or with fallback: {
+                    (r"^.+!$", VersionIncrement.MAJOR),
+                    (r"^BREAKING[\-\ ]CHANGE", VersionIncrement.MAJOR),
+                    (r"^feat", VersionIncrement.MINOR),
+                    (r"^fix", VersionIncrement.PATCH),
+                    (r"^refactor", VersionIncrement.PATCH),
+                    (r"^perf", VersionIncrement.PATCH),
+                }
+            bump_map_major_version_zero: A mapping of commit types to version increments
+                specifically for when the major version is 0. This allows for different
+                versioning behavior during initial development.
+                The format is the same as bump_map.
+                Example: {
+                    "major": VersionIncrement.MINOR,  # MAJOR becomes MINOR in version zero
+                    "bang": VersionIncrement.MINOR,   # Breaking changes become MINOR in version zero
+                    "minor": VersionIncrement.MINOR,
+                    "patch": VersionIncrement.PATCH
+                }
+                Or with fallback: {
+                    (r"^.+!$", VersionIncrement.MINOR),
+                    (r"^BREAKING[\-\ ]CHANGE", VersionIncrement.MINOR),
+                    (r"^feat", VersionIncrement.MINOR),
+                    (r"^fix", VersionIncrement.PATCH),
+                    (r"^refactor", VersionIncrement.PATCH),
+                    (r"^perf", VersionIncrement.PATCH),
+                }
+
+        Raises:
+            NoPatternMapError: If any of the required parameters are empty or None
+        """
+        if not bump_map or not bump_pattern or not bump_map_major_version_zero:
+            raise NoPatternMapError(
+                f"Invalid bump rule: {bump_pattern=} and {bump_map=} and {bump_map_major_version_zero=}"
+            )
+
+        self.bump_pattern = re.compile(bump_pattern)
+        self.bump_map = bump_map
+        self.bump_map_major_version_zero = bump_map_major_version_zero
+
+    def get_increment(
+        self, commit_message: str, major_version_zero: bool
+    ) -> VersionIncrement | None:
+        if not (m := self.bump_pattern.search(commit_message)):
+            return None
+
+        effective_bump_map = (
+            self.bump_map_major_version_zero if major_version_zero else self.bump_map
+        )
+
+        try:
+            if ret := VersionIncrement.get_highest(
+                (
+                    increment
+                    for name, increment in effective_bump_map.items()
+                    if m.group(name)
+                ),
+            ):
+                return ret
+        except IndexError:
+            pass
+
+        # Fallback to legacy bump rule, for backward compatibility
+        found_keyword = m.group(1)
+        for match_pattern, increment in effective_bump_map.items():
+            if re.match(match_pattern, found_keyword):
+                return increment
+        return None