comver 0.2.0__py3-none-any.whl

comver/__init__.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""comver internal API reference.
+
+This section of documentation should be mainly considered by people who:
+
+- are curious how the project works under the hood
+- want to provide integration of `comver` with third part tooling.
+
+Important:
+    Check out guidelines and tutorials for information about CLI/plugin
+    as this is a more common starting point.
+
+"""
+
+from __future__ import annotations
+
+from comver import error, plugin, type_definitions
+from comver._version import Version, _version
+
+__version__ = _version
+"""Current comver version."""
+
+__all__: list[str] = [
+    "Version",
+    "__version__",
+    "error",
+    "plugin",
+    "type_definitions",
+]

comver/__main__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The `python -m comver` entrypoint."""
+
+from __future__ import annotations  # pragma: no cover
+
+if __name__ == "__main__":  # pragma: no cover
+    from comver._cli import main
+
+    main()

comver/_cli.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""CLI entrypoint of comver."""
+
+from __future__ import annotations
+
+import sys
+
+from comver import _parser, _subcommand
+
+
+def main(args: list[str] | None = None) -> None:
+    """Command-line entry point of the `comver`.
+
+    Parses arguments and dispatches execution to the appropriate subcommand
+    based on user input. If no arguments are provided explicitly, the arguments
+    from `sys.argv[1:]` are used instead.
+
+    Args:
+        args:
+            CLI arguments passed, if any (used mainly during testing).
+
+    """
+    parsed_args = _parser.root().parse_args(args)
+    subcommand = getattr(_subcommand, parsed_args.subcommand, None)
+
+    # Cannot be `None`, but left to make pyright feel at peace
+    if subcommand is None:  # pragma: no cover
+        print(  # noqa: T201
+            "Unknown command chosen",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    subcommand(parsed_args)

comver/_parser.py

@@ -0,0 +1,132 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Parser of the `comver` CLI."""
+
+from __future__ import annotations
+
+import argparse
+import textwrap
+
+from comver._version import _version
+
+
+def root() -> argparse.ArgumentParser:
+    """Create and return the top-level CLI parser.
+
+    This parser defines all available subcommands and any global flags.
+    Each subcommand is parsed with its corresponding arguments and stored
+    in the `subcommand` attribute for later dispatching.
+
+    Returns:
+        The argument parser configured with all CLI subcommands.
+
+    """
+    parser = argparse.ArgumentParser(
+        description="Tool CLI with support for subcommands.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    _ = parser.add_argument(
+        "--version",
+        action="version",
+        version=_version,
+        help="Show the tool version and exit.",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="subcommand",
+        required=True,
+    )
+    _calculate(subparsers)
+    _verify(subparsers)
+
+    return parser
+
+
+def _calculate(subparsers) -> None:  # noqa: ANN001  # pyright: ignore [reportUnknownParameterType, reportMissingParameterType]
+    """Create `calculate` subcommand subparser.
+
+    Args:
+        subparsers:
+            Object where this subparser is registered.
+
+    """
+    parser = subparsers.add_parser(
+        "calculate",
+        description=textwrap.dedent("""\
+        Calculate semantic version based on commits.
+
+        NOTE:
+
+            - This command runs on the git-tree found in current
+            working directory.
+            - Each value (e.g. version and sha) is space separated
+        """),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--format",
+        choices=["line", "json"],
+        default="line",
+        help="Format of the output (default: line, each output space separated)",
+    )
+
+    parser.add_argument(
+        "--sha",
+        action="store_true",
+        required=False,
+        help=(
+            "Return sha of the commit related to the version (usable for verification)"
+        ),
+    )
+
+    parser.add_argument(
+        "--checksum",
+        action="store_true",
+        required=False,
+        help="Return checksum of the configuration (usable for verification)",
+    )
+
+
+def _verify(subparsers) -> None:  # noqa: ANN001  # pyright: ignore [reportUnknownParameterType, reportMissingParameterType]
+    """Create `verify` subcommand subparser.
+
+    Args:
+        subparsers:
+            Object where this subparser is registered.
+
+    """
+    parser = subparsers.add_parser(
+        "verify",
+        description=textwrap.dedent("""
+        Verify version consistency.
+
+        NOTE:
+
+            - This command runs on the git-tree found in current
+            working directory.
+            - You can feed the output of the `calculate` command here
+        """),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "version",
+        help="Version to check (e.g. `1.37.21`).",
+    )
+
+    parser.add_argument(
+        "sha",
+        help="Sha of the commit to compare against.",
+    )
+
+    parser.add_argument(
+        "checksum",
+        help="Checksum of the configuration to check against.",
+    )
+
+    return parser

comver/_regex/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Regex related internal functionalities."""
+
+from __future__ import annotations
+
+from comver._regex import match, semantic
+from comver._regex._process import process
+
+__all__ = [
+    "match",
+    "process",
+    "semantic",
+]

comver/_regex/_process.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Compilation/performance related regex functionalities."""
+
+from __future__ import annotations
+
+import re
+import typing
+
+if typing.TYPE_CHECKING:
+    from comver.type_definitions import OptionalStringsOrPatterns
+
+
+def process(
+    regexes: OptionalStringsOrPatterns, default: str | None = None
+) -> re.Pattern[str] | None:
+    """Cached compilation of multiple regexes.
+
+    > [!IMPORTANT]
+    > `compile` should use internal cache, see
+    > here: https://github.com/python/cpython/blob/v3.12.0/Lib/re/__init__.py#L271-L329
+
+    `None` is used, as the regex matching might be slow
+    and is avoided whenever possible throughout
+    the whole `comver`.
+
+    Arguments:
+        regexes:
+            Regexes which should be compiled together
+            (if provided).
+        default:
+            Default regex, if provided.
+    """
+    if not regexes:
+        if default is None:
+            return None
+        return re.compile(default)
+    return re.compile(r"(" + r"|".join(rf"({r})" for r in regexes) + r")")

comver/_regex/match.py

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: © 2025 nosludge <https://github.com/nosludge>
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Regex matching functions."""
+
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    import re
+
+    import git
+
+
+def item(
+    what: str, include: re.Pattern[str] | None, exclude: re.Pattern[str] | None
+) -> bool:
+    """Check if the `what` is included based on the `include` and `exclude`.
+
+    Note:
+        Empty `include` are treated as include-everything.
+
+    Note:
+        Empty `exclude` are treated as include-everything.
+
+    Warning:
+        Exclude regexes take precedence over include regexes.
+
+    Args:
+        what:
+            The string to check.
+        include:
+            The regex to include the string.
+        exclude:
+            The regex to exclude.
+
+    Returns:
+        True if the `what` is included, False otherwise.
+
+    """
+    return (include is None or include.search(what) is not None) and (
+        exclude is None or exclude.search(what) is None
+    )
+
+
+def path(
+    commit: git.Commit,
+    include: re.Pattern[str] | None,
+    exclude: re.Pattern[str] | None,
+) -> bool:
+    """Check if the commit touched the file based regexes.
+
+    Note:
+        Empty `include` are treated as include-everything.
+
+    Note:
+        Empty `exclude` are treated as include-everything.
+
+    Warning:
+        Exclude regexes take precedence over include regexes.
+
+    Args:
+        commit:
+            The commit to check.
+        include:
+            The regex to include the file.
+        exclude:
+            The regex to exclude the file.
+
+    Returns:
+        True if the commit touched the file, False otherwise.
+    """
+    if include is None and exclude is None:
+        return True
+
+    return not commit.diff() or any(
+        item(diff.a_path, include, exclude) if diff.a_path else True
+        for diff in commit.diff()
+    )

comver/_regex/semantic.py

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: © 2025 nosludge <https://github.com/nosludge>
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Semantic versioning related regexes."""
+
+from __future__ import annotations
+
+import re
+import typing
+
+from comver._regex._process import process
+
+if typing.TYPE_CHECKING:
+    from comver.type_definitions import OptionalStringsOrPatterns
+
+Key = typing.TypeVar("Key")
+
+Semantic = tuple[Key, re.Pattern[str] | None]
+Major = Semantic[typing.Literal["major"]]
+Minor = Semantic[typing.Literal["minor"]]
+Patch = Semantic[typing.Literal["patch"]]
+
+StringOrPattern = str | re.Pattern[str]
+
+
+def components(
+    major_regexes: OptionalStringsOrPatterns,
+    minor_regexes: OptionalStringsOrPatterns,
+    patch_regexes: OptionalStringsOrPatterns,
+) -> tuple[Major, Minor, Patch]:
+    """Grouped semantic versioning regexes.
+
+    This allows iteration over all necessary components
+    with one function.
+
+    Args:
+        major_regexes:
+            The regexes finding the `major` version.
+        minor_regexes:
+            The regexes finding the `minor` version.
+        patch_regexes:
+            The regexes finding the `patch` version.
+
+    Returns:
+        Dictionary mapping element of semantic versioning to the regex.
+
+    """
+    return (
+        ("major", major(major_regexes)),
+        ("minor", minor(minor_regexes)),
+        ("patch", patch(patch_regexes)),
+    )
+
+
+def major(regexes: OptionalStringsOrPatterns) -> re.Pattern[str] | None:
+    """Return compiled `major` regex.
+
+    Args:
+        regexes:
+            Specified `major` version element regexes.
+
+    Returns:
+        Compiled regular expression (either default or provided).
+
+    """
+    return process(regexes, r".*BREAKING CHANGE.*|^(feat|fix)(\(.*?\))?!: .*")
+
+
+def minor(regexes: OptionalStringsOrPatterns) -> re.Pattern[str] | None:
+    """Return compiled `mior` regex.
+
+    Args:
+        regexes:
+            Specified `minor` version element regexes.
+
+    Returns:
+        Compiled regular expression (either default or provided).
+
+    """
+    return process(regexes, "^feat(\\(.*?\\))?: .*")
+
+
+def patch(regexes: OptionalStringsOrPatterns) -> re.Pattern[str] | None:
+    """Return compiled `patch` regex.
+
+    Args:
+        regexes:
+            Specified `patch` version element regexes.
+
+    Returns:
+        Compiled regular expression (either default or provided).
+
+    """
+    return process(regexes, "^fix(\\(.*?\\))?: .*")

comver/_subcommand.py

@@ -0,0 +1,174 @@
+# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
+# SPDX-FileContributor: szymonmaszke <github@maszke.co>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Subcommands of the CLI `comver`."""
+
+from __future__ import annotations
+
+import collections
+import hashlib
+import json
+import sys
+import typing
+
+import loadfig
+
+from comver._version import Version, VersionCommit
+
+if typing.TYPE_CHECKING:
+    import argparse
+
+
+def calculate(args: argparse.Namespace) -> typing.NoReturn:
+    """Calculate semantic versioning based on commit messages.
+
+    Outputs version and (optionally) sha of a commit
+    related to this version (the last one in commit chain).
+
+    This output allows to later compare git trees and inferred
+    versions if necessary.
+
+    Args:
+        args:
+            Arguments from the CLI.
+
+    """
+    print(_calculate(args))  # noqa: T201
+    sys.exit(0)
+
+
+def verify(args: argparse.Namespace) -> typing.NoReturn:
+    """Verify commit sha and inferred version match.
+
+    Given `version` (as string, e.g. `1.2.3`) and
+    commit sha verify whether this version was created
+    from this commit chain.
+
+    Args:
+        args:
+            Arguments from the CLI.
+
+    """
+    sys.exit(_verify(args))
+
+
+def _calculate(args: argparse.Namespace) -> str:  # noqa: C901
+    """Implementation of calculate cli command.
+
+    Args:
+        args:
+            Arguments from the CLI.
+
+    Returns:
+        Either formatted dictionary (if `args.json`) string
+        or space separated "version sha". `sha` component
+        is optional based on `args.sha` flag.
+
+    """
+    version = VersionCommit()
+    for version in Version.from_git_configured():  # noqa: B007
+        pass
+
+    sha = version.commit.hexsha if version.commit is not None else None
+    checksum = _checksum_config()
+
+    version = str(version.version)
+
+    if args.format == "line":
+        if args.sha:
+            version = f"{version} {sha}"
+        if args.checksum:
+            version = f"{version} {checksum}"
+        return version
+
+    output = {"version": str(version)}
+    if args.sha and isinstance(sha, str):
+        output["sha"] = sha
+    if args.checksum:
+        output["checksum"] = checksum
+
+    return json.dumps(output, indent=4)
+
+
+def _verify(args: argparse.Namespace) -> bool:
+    """Verify commit sha and inferred version match.
+
+    Warning:
+        This subcommand also outputs messages for the end user
+
+    Args:
+        args:
+            Arguments from the CLI.
+
+    Returns:
+        Code status of the command (`True` for error, `False`
+        on successful verification).
+
+    """
+    checksum = _checksum_config()
+
+    if args.checksum != checksum:
+        print(  # noqa: T201
+            "Provided checksum and the checksum of configuration do not match.",
+            file=sys.stderr,
+        )
+        return True
+
+    for output in Version.from_git_configured():
+        version, commit = output.version, output.commit
+
+        sha = commit.hexsha if commit is not None else None
+
+        if args.version == version:
+            if sha is not None and sha == args.sha:
+                return False
+
+            print(  # noqa: T201
+                f"Specified version: `{args.version}` has sha: `{sha}`, while expected sha is: `{args.sha}`",
+                file=sys.stderr,
+            ) # pragma: no cover
+            return True # pragma: no cover
+
+        if args.sha == sha:
+            print(  # noqa: T201
+                f"Specified sha: `{args.sha}` corresponds to version: `{version}`, while expected version is: `{args.version}`",  # noqa: E501
+                file=sys.stderr,
+            )
+            return True
+
+    print(  # noqa: T201
+        f"Neither specified sha: `{args.sha}` nor its corresponding version: `{args.version}` was found in the git tree",  # noqa: E501
+        file=sys.stderr,
+    )
+    return True
+
+
+def _checksum_config() -> str:
+    """Get checksum of config.
+
+    Returns:
+        Checksum of subconfig.
+
+    """
+    config = collections.defaultdict(lambda: None, loadfig.config("comver"))
+    keys = [
+        "message_includes",
+        "message_excludes",
+        "path_includes",
+        "path_excludes",
+        "author_name_includes",
+        "author_name_excludes",
+        "author_email_includes",
+        "author_email_excludes",
+        "major_regexes",
+        "minor_regexes",
+        "patch_regexes",
+        "unrecognized_message",
+    ]
+
+    # Get only relevant sections of the dict
+    subconfig = {k: config[k] for k in keys}
+    stringified = json.dumps(subconfig, sort_keys=True)
+    return hashlib.sha256(stringified.encode()).hexdigest()