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

Closes#129

Author: bearomorphism

commitizen/bump.py

@@ -2,61 +2,14 @@
 
 importos
 importre
-fromcollectionsimportOrderedDict
 fromcollections.abcimportIterable
 fromglobimportiglob
-fromloggingimportgetLogger
 fromstringimportTemplate
-fromtypingimportcast
 
-fromcommitizen.defaultsimportBUMP_MESSAGE, ENCODING, MAJOR, MINOR, PATCH
+fromcommitizen.defaultsimportBUMP_MESSAGE, ENCODING
 fromcommitizen.exceptionsimportCurrentVersionNotFoundError
-fromcommitizen.gitimportGitCommit, smart_open
-fromcommitizen.version_schemesimportIncrement, Version
-
-VERSION_TYPES= [None, PATCH, MINOR, MAJOR]
-
-logger=getLogger("commitizen")
-
-
-deffind_increment(
-commits: list[GitCommit], regex: str, increments_map: dict|OrderedDict
-) ->Increment|None:
-ifisinstance(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
-
-forcommitincommits:
-formessageincommit.message.split("\n"):
-result=select_pattern.search(message)
-
-ifresult:
-found_keyword=result.group(1)
-new_increment=None
-formatch_patterninincrements_map.keys():
-ifre.match(match_pattern, found_keyword):
-new_increment=increments_map[match_pattern]
-break
-
-ifnew_incrementisNone:
-logger.debug(
-f"no increment needed for '{found_keyword}' in '{message}'"
- )
-
-ifVERSION_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
-
-ifincrement==MAJOR:
-break
-
-returncast(Increment, increment)
+fromcommitizen.gitimportsmart_open
+fromcommitizen.version_schemesimportVersion
 
 
 defupdate_version_in_files(

commitizen/bump_rule.py

@@ -0,0 +1,253 @@
+from __future__ importannotations
+
+importre
+fromcollections.abcimportIterable, Mapping
+fromenumimportIntEnum, auto
+fromfunctoolsimportcached_property
+fromtypingimportCallable, Protocol
+
+fromcommitizen.exceptionsimportNoPatternMapError
+
+
+classVersionIncrement(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:
+returnself.name
+
+@classmethod
+defsafe_cast(cls, value: object) ->VersionIncrement|None:
+ifnotisinstance(value, str):
+returnNone
+try:
+returncls[value]
+exceptKeyError:
+returnNone
+
+@classmethod
+defsafe_cast_dict(cls, d: Mapping[str, object]) ->dict[str, VersionIncrement]:
+return{
+k: v
+fork, vin ((k, VersionIncrement.safe_cast(v)) fork, vind.items())
+ifvisnotNone
+ }
+
+@staticmethod
+defget_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'
+ """
+returnVersionIncrement.get_highest(
+get_increment(line)
+formessageincommit_messages
+forlineinmessage.split("\n")
+ )
+
+@staticmethod
+defget_highest(
+increments: Iterable[VersionIncrement|None],
+ ) ->VersionIncrement|None:
+returnmax(filter(None, increments), default=None)
+
+
+classBumpRule(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.
+ """
+
+defget_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.)
+ """
+
+
+classConventionalCommitBumpRule(BumpRule):
+_BREAKING_CHANGE_TYPES=set(["BREAKING CHANGE", "BREAKING-CHANGE"])
+_MINOR_CHANGE_TYPES=set(["feat"])
+_PATCH_CHANGE_TYPES=set(["fix", "perf", "refactor"])
+
+defget_increment(
+self, commit_message: str, major_version_zero: bool
+ ) ->VersionIncrement|None:
+ifnot (m:=self._head_pattern.match(commit_message)):
+returnNone
+
+change_type=m.group("change_type")
+ifm.group("bang") orchange_typeinself._BREAKING_CHANGE_TYPES:
+return (
+VersionIncrement.MINORifmajor_version_zeroelseVersionIncrement.MAJOR
+ )
+
+ifchange_typeinself._MINOR_CHANGE_TYPES:
+returnVersionIncrement.MINOR
+
+ifchange_typeinself._PATCH_CHANGE_TYPES:
+returnVersionIncrement.PATCH
+
+returnNone
+
+@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>!)?"
+returnre.compile(f"^{re_change_type}{re_scope}{re_bang}:")
+
+
+classCustomBumpRule(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
+ """
+ifnotbump_mapornotbump_patternornotbump_map_major_version_zero:
+raiseNoPatternMapError(
+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
+
+defget_increment(
+self, commit_message: str, major_version_zero: bool
+ ) ->VersionIncrement|None:
+ifnot (m:=self.bump_pattern.search(commit_message)):
+returnNone
+
+effective_bump_map= (
+self.bump_map_major_version_zeroifmajor_version_zeroelseself.bump_map
+ )
+
+try:
+ifret:=VersionIncrement.get_highest(
+ (
+increment
+forname, incrementineffective_bump_map.items()
+ifm.group(name)
+ ),
+ ):
+returnret
+exceptIndexError:
+pass
+
+# Fallback to legacy bump rule, for backward compatibility
+found_keyword=m.group(1)
+formatch_pattern, incrementineffective_bump_map.items():
+ifre.match(match_pattern, found_keyword):
+returnincrement
+returnNone