semver_cli.py

#!/usr/bin/env python3
"""
semver-cli: A comprehensive semantic versioning tool.

Supports parsing, comparing, bumping, range checking, sorting,
validating, diffing, and suggesting next versions. Full support
for prerelease tags and build metadata per the SemVer 2.0.0 spec.
"""

import argparse
import re
import sys
from functools import total_ordering

SEMVER_PATTERN = re.compile(
    r"^v?(?P<major>0|[1-9]\d*)"
    r"\.(?P<minor>0|[1-9]\d*)"
    r"\.(?P<patch>0|[1-9]\d*)"
    r"(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)"
    r"(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
    r"(?:\+(?P<build>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
)

RANGE_PATTERN = re.compile(
    r"^(?P<op>[><=!]+)?\s*(?P<version>.+)$"
)


def _compare_prerelease_identifiers(a_ids, b_ids):
    """Compare prerelease identifier lists per SemVer 2.0.0 spec."""
    if not a_ids and not b_ids:
        return 0
    if not a_ids:
        return 1  # no prerelease > has prerelease
    if not b_ids:
        return -1  # has prerelease < no prerelease

    for a_id, b_id in zip(a_ids, b_ids):
        a_is_num = a_id.isdigit()
        b_is_num = b_id.isdigit()

        if a_is_num and b_is_num:
            a_val, b_val = int(a_id), int(b_id)
            if a_val != b_val:
                return -1 if a_val < b_val else 1
        elif a_is_num:
            return -1  # numeric < alphanumeric
        elif b_is_num:
            return 1   # alphanumeric > numeric
        else:
            if a_id != b_id:
                return -1 if a_id < b_id else 1

    if len(a_ids) != len(b_ids):
        return -1 if len(a_ids) < len(b_ids) else 1
    return 0


@total_ordering
class SemVer:
    """Represents a semantic version."""

    __slots__ = ("major", "minor", "patch", "prerelease", "build")

    def __init__(self, major, minor, patch, prerelease=None, build=None):
        self.major = int(major)
        self.minor = int(minor)
        self.patch = int(patch)
        self.prerelease = prerelease or ""
        self.build = build or ""

    @classmethod
    def parse(cls, version_str):
        """Parse a version string into a SemVer object."""
        version_str = version_str.strip()
        match = SEMVER_PATTERN.match(version_str)
        if not match:
            raise ValueError(f"Invalid semantic version: {version_str!r}")
        return cls(
            major=match.group("major"),
            minor=match.group("minor"),
            patch=match.group("patch"),
            prerelease=match.group("prerelease") or "",
            build=match.group("build") or "",
        )

    @property
    def prerelease_ids(self):
        """Split prerelease into identifiers."""
        if not self.prerelease:
            return []
        return self.prerelease.split(".")

    @property
    def is_stable(self):
        return not self.prerelease and self.major > 0

    @property
    def is_prerelease(self):
        return bool(self.prerelease)

    def _cmp_tuple(self):
        return (self.major, self.minor, self.patch)

    def __eq__(self, other):
        if not isinstance(other, SemVer):
            return NotImplemented
        return (self._cmp_tuple() == other._cmp_tuple()
                and self.prerelease == other.prerelease)

    def __lt__(self, other):
        if not isinstance(other, SemVer):
            return NotImplemented
        if self._cmp_tuple() != other._cmp_tuple():
            return self._cmp_tuple() < other._cmp_tuple()
        cmp = _compare_prerelease_identifiers(self.prerelease_ids, other.prerelease_ids)
        return cmp < 0

    def __hash__(self):
        return hash((self.major, self.minor, self.patch, self.prerelease))

    def __str__(self):
        s = f"{self.major}.{self.minor}.{self.patch}"
        if self.prerelease:
            s += f"-{self.prerelease}"
        if self.build:
            s += f"+{self.build}"
        return s

    def __repr__(self):
        return f"SemVer({self})"

    def bump_major(self):
        return SemVer(self.major + 1, 0, 0)

    def bump_minor(self):
        return SemVer(self.major, self.minor + 1, 0)

    def bump_patch(self):
        return SemVer(self.major, self.minor, self.patch + 1)

    def bump_prerelease(self, tag="alpha"):
        """Bump prerelease. If already has same tag, increment number."""
        if self.prerelease:
            parts = self.prerelease.split(".")
            if len(parts) >= 2 and parts[-1].isdigit():
                if parts[0] == tag:
                    parts[-1] = str(int(parts[-1]) + 1)
                    return SemVer(self.major, self.minor, self.patch,
                                  prerelease=".".join(parts))
            # Different tag or no number, start new
            return SemVer(self.major, self.minor, self.patch,
                          prerelease=f"{tag}.1")
        # No prerelease, bump patch and add tag
        return SemVer(self.major, self.minor, self.patch + 1,
                      prerelease=f"{tag}.1")

    def diff(self, other):
        """Return what changed between self and other."""
        if self.major != other.major:
            return "major"
        if self.minor != other.minor:
            return "minor"
        if self.patch != other.patch:
            return "patch"
        if self.prerelease != other.prerelease:
            return "prerelease"
        if self.build != other.build:
            return "build"
        return "none"

    def satisfies(self, range_str):
        """Check if version satisfies a range expression."""
        range_str = range_str.strip()

        # Handle caret ranges: ^1.2.3
        if range_str.startswith("^"):
            base = SemVer.parse(range_str[1:])
            if base.major > 0:
                return (self.major == base.major and self >= base)
            elif base.minor > 0:
                return (self.major == base.major
                        and self.minor == base.minor and self >= base)
            else:
                return self == base

        # Handle tilde ranges: ~1.2.3
        if range_str.startswith("~"):
            base = SemVer.parse(range_str[1:])
            return (self.major == base.major
                    and self.minor == base.minor and self >= base)

        # Handle wildcard: 1.2.x or 1.2.*
        if "x" in range_str or "*" in range_str:
            parts = range_str.replace("*", "x").split(".")
            if len(parts) >= 1 and parts[0] != "x":
                if self.major != int(parts[0]):
                    return False
            if len(parts) >= 2 and parts[1] != "x":
                if self.minor != int(parts[1]):
                    return False
            if len(parts) >= 3 and parts[2] != "x":
                if self.patch != int(parts[2]):
                    return False
            return True

        # Handle compound ranges with spaces (AND) and || (OR)
        if "||" in range_str:
            return any(self.satisfies(r.strip())
                       for r in range_str.split("||"))

        if " " in range_str.strip():
            parts = range_str.strip().split()
            # Group operator + version pairs
            constraints = []
            i = 0
            while i < len(parts):
                token = parts[i]
                range_match = RANGE_PATTERN.match(token)
                if range_match and range_match.group("op"):
                    constraints.append(token)
                else:
                    constraints.append(token)
                i += 1
            return all(self.satisfies(c) for c in constraints)

        # Handle comparison operators
        range_match = RANGE_PATTERN.match(range_str)
        if not range_match:
            raise ValueError(f"Invalid range: {range_str!r}")

        op = range_match.group("op") or "="
        target = SemVer.parse(range_match.group("version"))

        ops = {
            "=": lambda: self == target,
            "==": lambda: self == target,
            "!=": lambda: self != target,
            ">": lambda: self > target,
            ">=": lambda: self >= target,
            "<": lambda: self < target,
            "<=": lambda: self <= target,
        }

        if op not in ops:
            raise ValueError(f"Unknown operator: {op!r}")
        return ops[op]()


def cmd_parse(args):
    """Parse a version string and show its components."""
    v = SemVer.parse(args.version)
    print(f"Major:      {v.major}")
    print(f"Minor:      {v.minor}")
    print(f"Patch:      {v.patch}")
    print(f"Prerelease: {v.prerelease or '(none)'}")
    print(f"Build:      {v.build or '(none)'}")
    print(f"Stable:     {v.is_stable}")


def cmd_compare(args):
    """Compare two versions."""
    a = SemVer.parse(args.version1)
    b = SemVer.parse(args.version2)
    if a < b:
        print(f"{a} < {b}")
        sys.exit(2)
    elif a > b:
        print(f"{a} > {b}")
        sys.exit(0)
    else:
        print(f"{a} == {b}")
        sys.exit(1)


def cmd_bump(args):
    """Bump a version component."""
    v = SemVer.parse(args.version)
    bumpers = {
        "major": v.bump_major,
        "minor": v.bump_minor,
        "patch": v.bump_patch,
        "prerelease": lambda: v.bump_prerelease(args.tag),
    }
    result = bumpers[args.component]()
    print(result)


def cmd_range(args):
    """Check if a version satisfies a range."""
    v = SemVer.parse(args.version)
    if v.satisfies(args.range):
        print(f"{v} satisfies {args.range!r}")
        sys.exit(0)
    else:
        print(f"{v} does NOT satisfy {args.range!r}")
        sys.exit(1)


def cmd_sort(args):
    """Sort a list of versions."""
    versions_str = args.versions
    if not versions_str or (len(versions_str) == 1 and versions_str[0] == "-"):
        versions_str = [line.strip() for line in sys.stdin if line.strip()]

    versions = []
    for vs in versions_str:
        for v in vs.split(","):
            v = v.strip()
            if v:
                versions.append(SemVer.parse(v))

    versions.sort(reverse=args.reverse)
    for v in versions:
        print(v)


def cmd_validate(args):
    """Validate a version string."""
    try:
        v = SemVer.parse(args.version)
        print(f"Valid: {v}")
        sys.exit(0)
    except ValueError as e:
        print(f"Invalid: {e}")
        sys.exit(1)


def cmd_diff(args):
    """Show what changed between two versions."""
    a = SemVer.parse(args.version1)
    b = SemVer.parse(args.version2)
    change = a.diff(b)
    print(f"Changed: {change}")
    if change != "none":
        print(f"  {a} -> {b}")


def cmd_next(args):
    """Suggest next versions from current."""
    v = SemVer.parse(args.version)
    print(f"Current:          {v}")
    print(f"Next patch:       {v.bump_patch()}")
    print(f"Next minor:       {v.bump_minor()}")
    print(f"Next major:       {v.bump_major()}")
    print(f"Next alpha:       {v.bump_prerelease('alpha')}")
    print(f"Next beta:        {v.bump_prerelease('beta')}")
    print(f"Next rc:          {v.bump_prerelease('rc')}")


def cmd_filter(args):
    """Filter versions by range from stdin or arguments."""
    versions_str = args.versions
    if not versions_str or (len(versions_str) == 1 and versions_str[0] == "-"):
        versions_str = [line.strip() for line in sys.stdin if line.strip()]

    for vs in versions_str:
        for v_str in vs.split(","):
            v_str = v_str.strip()
            if not v_str:
                continue
            try:
                v = SemVer.parse(v_str)
                if v.satisfies(args.range):
                    print(v)
            except ValueError:
                pass


def cmd_latest(args):
    """Find the latest version from a list."""
    versions_str = args.versions
    if not versions_str or (len(versions_str) == 1 and versions_str[0] == "-"):
        versions_str = [line.strip() for line in sys.stdin if line.strip()]

    versions = []
    for vs in versions_str:
        for v in vs.split(","):
            v = v.strip()
            if v:
                try:
                    versions.append(SemVer.parse(v))
                except ValueError:
                    pass

    if not versions:
        print("No valid versions found", file=sys.stderr)
        sys.exit(1)

    if args.stable:
        stable = [v for v in versions if v.is_stable]
        if stable:
            print(max(stable))
        else:
            print("No stable versions found", file=sys.stderr)
            sys.exit(1)
    else:
        print(max(versions))


def main():
    parser = argparse.ArgumentParser(
        prog="semver-cli",
        description="Semantic Versioning CLI tool (SemVer 2.0.0)",
        epilog="Examples:\n"
               "  semver-cli parse 1.2.3-beta.1+build.42\n"
               "  semver-cli bump 1.2.3 minor\n"
               "  semver-cli compare 1.0.0 2.0.0\n"
               "  semver-cli range 1.5.0 '>=1.0.0 <2.0.0'\n"
               "  semver-cli sort 3.0.0 1.0.0 2.0.0\n"
               "  echo -e '1.0.0\\n2.0.0' | semver-cli sort -\n",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )

    subparsers = parser.add_subparsers(dest="command", help="Available commands")

    # parse
    p = subparsers.add_parser("parse", help="Parse and display version components")
    p.add_argument("version", help="Version string to parse")
    p.set_defaults(func=cmd_parse)

    # compare
    p = subparsers.add_parser("compare", help="Compare two versions")
    p.add_argument("version1", help="First version")
    p.add_argument("version2", help="Second version")
    p.set_defaults(func=cmd_compare)

    # bump
    p = subparsers.add_parser("bump", help="Bump a version component")
    p.add_argument("version", help="Version to bump")
    p.add_argument("component", choices=["major", "minor", "patch", "prerelease"],
                   help="Component to bump")
    p.add_argument("--tag", default="alpha",
                   help="Prerelease tag (default: alpha)")
    p.set_defaults(func=cmd_bump)

    # range
    p = subparsers.add_parser("range", help="Check version against range")
    p.add_argument("version", help="Version to check")
    p.add_argument("range", help="Range expression (e.g., '>=1.0.0 <2.0.0')")
    p.set_defaults(func=cmd_range)

    # sort
    p = subparsers.add_parser("sort", help="Sort versions")
    p.add_argument("versions", nargs="*", help="Versions to sort (or - for stdin)")
    p.add_argument("-r", "--reverse", action="store_true",
                   help="Sort in descending order")
    p.set_defaults(func=cmd_sort)

    # validate
    p = subparsers.add_parser("validate", help="Validate a version string")
    p.add_argument("version", help="Version string to validate")
    p.set_defaults(func=cmd_validate)

    # diff
    p = subparsers.add_parser("diff", help="Show difference between two versions")
    p.add_argument("version1", help="First version")
    p.add_argument("version2", help="Second version")
    p.set_defaults(func=cmd_diff)

    # next
    p = subparsers.add_parser("next", help="Suggest next versions")
    p.add_argument("version", help="Current version")
    p.set_defaults(func=cmd_next)

    # filter
    p = subparsers.add_parser("filter", help="Filter versions by range")
    p.add_argument("--range", "-r", required=True,
                   help="Range to filter by")
    p.add_argument("versions", nargs="*",
                   help="Versions to filter (or - for stdin)")
    p.set_defaults(func=cmd_filter)

    # latest
    p = subparsers.add_parser("latest", help="Find latest version")
    p.add_argument("versions", nargs="*",
                   help="Versions (or - for stdin)")
    p.add_argument("--stable", action="store_true",
                   help="Only consider stable versions")
    p.set_defaults(func=cmd_latest)

    args = parser.parse_args()
    if not args.command:
        parser.print_help()
        sys.exit(1)

    try:
        args.func(args)
    except ValueError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    except BrokenPipeError:
        sys.exit(0)


if __name__ == "__main__":
    main()