semvertag 0.1.0__tar.gz

semvertag-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: semvertag
+Version: 0.1.0
+Summary: Auto-tag GitLab repos with semantic version tags — one tool, two strategies.
+Keywords: semver,gitlab,ci,auto-tag,conventional-commits
+Author: Artur Shiriev
+Author-email: Artur Shiriev <me@shiriev.ru>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: semver
+Requires-Dist: pydantic-settings
+Requires-Dist: modern-di-typer
+Requires-Dist: httpx2
+Requires-Python: >=3.10, <4
+Project-URL: repository, https://github.com/modern-python/semvertag
+Project-URL: docs, https://semvertag.readthedocs.io
+Description-Content-Type: text/markdown
+
+# semvertag
+
+[![CI](https://github.com/modern-python/semvertag/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/semvertag/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/modern-python/semvertag/branch/main/graph/badge.svg)](https://codecov.io/gh/modern-python/semvertag)
+
+Auto-tag your GitLab repository with semantic version tags from CI — one tool, two strategies.
+
+## Install
+
+```sh
+uvx semvertag tag
+```
+
+## Use it in GitLab CI
+
+Include the Catalog component in your `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - component: gitlab.com/modern-python/semvertag/semvertag@v0.1.0
+    inputs:
+      strategy: branch-prefix  # or: conventional-commits
+```
+
+The component runs `uvx semvertag tag` against your repo on the
+default branch. semvertag inspects the latest commit + tag history,
+decides the appropriate semver bump, and creates the new tag via the
+GitLab API.
+
+## Strategies
+
+- **branch-prefix** (default): the latest commit on the default branch
+  must be a merge commit whose source branch starts with `feature/`
+  (minor), `bugfix/`, or `hotfix/` (patch).
+- **conventional-commits**: parses the latest commit's
+  [Conventional Commits](https://www.conventionalcommits.org/)
+  header (`feat:` minor, `fix:`/`perf:` patch, `!` or `BREAKING
+  CHANGE:` major).
+
+Both are configurable via env vars. See [docs](https://semvertag.readthedocs.io)
+for the full configuration surface.
+
+## License
+
+MIT

semvertag-0.1.0/README.md

@@ -0,0 +1,45 @@
+# semvertag
+
+[![CI](https://github.com/modern-python/semvertag/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/semvertag/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/modern-python/semvertag/branch/main/graph/badge.svg)](https://codecov.io/gh/modern-python/semvertag)
+
+Auto-tag your GitLab repository with semantic version tags from CI — one tool, two strategies.
+
+## Install
+
+```sh
+uvx semvertag tag
+```
+
+## Use it in GitLab CI
+
+Include the Catalog component in your `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - component: gitlab.com/modern-python/semvertag/semvertag@v0.1.0
+    inputs:
+      strategy: branch-prefix  # or: conventional-commits
+```
+
+The component runs `uvx semvertag tag` against your repo on the
+default branch. semvertag inspects the latest commit + tag history,
+decides the appropriate semver bump, and creates the new tag via the
+GitLab API.
+
+## Strategies
+
+- **branch-prefix** (default): the latest commit on the default branch
+  must be a merge commit whose source branch starts with `feature/`
+  (minor), `bugfix/`, or `hotfix/` (patch).
+- **conventional-commits**: parses the latest commit's
+  [Conventional Commits](https://www.conventionalcommits.org/)
+  header (`feat:` minor, `fix:`/`perf:` patch, `!` or `BREAKING
+  CHANGE:` major).
+
+Both are configurable via env vars. See [docs](https://semvertag.readthedocs.io)
+for the full configuration surface.
+
+## License
+
+MIT

semvertag-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "semvertag"
+description = "Auto-tag GitLab repos with semantic version tags — one tool, two strategies."
+authors = [{ name = "Artur Shiriev", email = "me@shiriev.ru" }]
+requires-python = ">=3.10,<4"
+license = "MIT"
+readme = "README.md"
+keywords = ["semver", "gitlab", "ci", "auto-tag", "conventional-commits"]
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries",
+]
+version = "0.1.0"
+dependencies = [
+    "typer",
+    "rich",
+    "semver",
+    "pydantic-settings",
+    "modern-di-typer",
+    "httpx2",
+]
+
+[project.scripts]
+semvertag = "semvertag.__main__:main"
+
+[project.urls]
+repository = "https://github.com/modern-python/semvertag"
+docs = "https://semvertag.readthedocs.io"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "semvertag"
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pytest-xdist",
+    "pytest-randomly",
+]
+lint = [
+    "ruff",
+    "ty",
+    "eof-fixer",
+]
+
+[tool.ruff]
+fix = true
+unsafe-fixes = true
+line-length = 120
+target-version = "py310"
+extend-exclude = ["docs", "_autosemver_reference", "_archive/bmad"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D1",
+    "FBT",
+    "TRY003",
+    "EM102",
+    "D203",
+    "D212",
+    "COM812",
+    "ISC001",
+    "S105",
+]
+isort.lines-after-imports = 2
+isort.no-lines-before = ["standard-library", "local-folder"]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/**/*.py" = ["S101", "SLF001"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=. --cov-report term-missing"
+testpaths = ["tests"]
+
+[tool.coverage.report]
+exclude_also = ["if typing.TYPE_CHECKING:", "if TYPE_CHECKING:"]
+
+[tool.coverage.run]
+omit = ["_autosemver_reference/*", "_archive/bmad/*", "tests/*"]
+
+[tool.ty.src]
+exclude = ["_autosemver_reference", "_archive/bmad", "docs"]

semvertag-0.1.0/semvertag/__main__.py

@@ -0,0 +1,178 @@
+import errno
+import importlib.metadata
+import typing
+
+import modern_di_typer
+import pydantic
+import typer
+
+from semvertag import ioc
+from semvertag._errors import ConfigError, SemvertagError
+from semvertag._output import Output, build_json_output, build_rich_output
+from semvertag._settings import Settings, apply_cli_overlay
+from semvertag._use_case import SemvertagUseCase
+
+
+_PACKAGE_NAME: typing.Final = "semvertag"
+
+
+MAIN_APP: typing.Final = typer.Typer(
+    name="semvertag",
+    help=("Auto-tag GitLab repos with semantic version tags — one tool, two strategies."),
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+modern_di_typer.setup_di(MAIN_APP, ioc.container)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    try:
+        version = importlib.metadata.version(_PACKAGE_NAME)
+    except importlib.metadata.PackageNotFoundError:
+        version = "0"
+    typer.echo(version)
+    raise typer.Exit
+
+
+def _collect_overrides(  # noqa: PLR0913
+    *,
+    project_id: int | None,
+    strategy: str | None,
+    token: str | None,
+    default_branch: str | None,
+    gitlab_endpoint: str | None,
+    request_timeout: float | None,
+) -> dict[str, typing.Any]:
+    overrides: dict[str, typing.Any] = {}
+    if project_id is not None:
+        overrides["project_id"] = project_id
+    if strategy is not None:
+        overrides["strategy"] = strategy
+    if token is not None:
+        overrides["gitlab.token"] = pydantic.SecretStr(token)
+    if default_branch is not None:
+        overrides["default_branch"] = default_branch
+    if gitlab_endpoint is not None:
+        overrides["gitlab.endpoint"] = gitlab_endpoint
+    if request_timeout is not None:
+        overrides["request_timeout"] = request_timeout
+    return overrides
+
+
+def _config_error_from_validation(exc: pydantic.ValidationError) -> ConfigError:
+    first: typing.Final = exc.errors()[0]
+    loc: typing.Final = ".".join(str(part) for part in first.get("loc", ()))
+    detail: typing.Final = first.get("msg", "invalid value")
+    msg: typing.Final = f"Configuration error at '{loc}': {detail}. Check environment variables and command-line flags."
+    return ConfigError(msg)
+
+
+@MAIN_APP.callback()
+def _main_callback(  # noqa: PLR0913
+    ctx: typer.Context,
+    project_id: typing.Annotated[
+        int | None,
+        typer.Option("--project-id", help="GitLab project id (or set CI_PROJECT_ID)."),
+    ] = None,
+    strategy: typing.Annotated[
+        str | None,
+        typer.Option("--strategy", help="Bump strategy: branch-prefix | conventional-commits."),
+    ] = None,
+    token: typing.Annotated[
+        str | None,
+        typer.Option("--token", help="API token (overrides SEMVERTAG_TOKEN)."),
+    ] = None,
+    default_branch: typing.Annotated[
+        str | None,
+        typer.Option("--default-branch", help="Default branch name override."),
+    ] = None,
+    gitlab_endpoint: typing.Annotated[
+        str | None,
+        typer.Option("--gitlab-endpoint", help="GitLab API endpoint URL."),
+    ] = None,
+    request_timeout: typing.Annotated[
+        float | None,
+        typer.Option("--request-timeout", help="Per-request timeout in seconds (clamped to 10)."),
+    ] = None,
+    _version: typing.Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version and exit."),
+    ] = None,
+) -> None:
+    if ctx.resilient_parsing:
+        return
+
+    try:
+        settings = Settings()
+        try:
+            overrides = _collect_overrides(
+                project_id=project_id,
+                strategy=strategy,
+                token=token,
+                default_branch=default_branch,
+                gitlab_endpoint=gitlab_endpoint,
+                request_timeout=request_timeout,
+            )
+            settings = apply_cli_overlay(settings, overrides)
+        except ValueError as exc:
+            raise ConfigError(str(exc)) from exc
+    except pydantic.ValidationError as exc:
+        err = _config_error_from_validation(exc)
+        typer.echo(f"Error: {err}", err=True)
+        raise typer.Exit(code=err.exit_code) from err
+    except ConfigError as err:
+        typer.echo(f"Error: {err}", err=True)
+        raise typer.Exit(code=err.exit_code) from err
+
+    app_container = modern_di_typer.fetch_di_container(ctx)
+    app_container.set_context(Settings, settings)
+
+
+@modern_di_typer.inject
+def _resolve_use_case(
+    use_case: typing.Annotated[SemvertagUseCase, modern_di_typer.FromDI(SemvertagUseCase)],
+) -> SemvertagUseCase:
+    return use_case
+
+
+@MAIN_APP.command("tag")
+def _tag_command(
+    ctx: typer.Context,
+    quiet: typing.Annotated[
+        bool,
+        typer.Option("--quiet", help="Suppress progress narrative; final result still emits."),
+    ] = False,
+    json_flag: typing.Annotated[
+        bool,
+        typer.Option("--json", help="Emit a JSON envelope on stdout instead of human-readable output."),
+    ] = False,
+) -> None:
+    output: Output = build_json_output(quiet=quiet) if json_flag else build_rich_output(quiet=quiet)
+    try:
+        use_case = _resolve_use_case(ctx=ctx)
+        use_case(output=output)
+    except ImportError as exc:
+        err = ConfigError(f"Required module unavailable: {exc}.")
+        output.error(str(err))
+        raise typer.Exit(code=err.exit_code) from exc
+    except SemvertagError as err:
+        output.error(str(err))
+        raise typer.Exit(code=err.exit_code) from err
+    except BrokenPipeError as exc:
+        raise typer.Exit(code=0) from exc
+    except OSError as exc:
+        if exc.errno == errno.EPIPE:
+            raise typer.Exit(code=0) from exc
+        raise
+
+
+def main() -> None:
+    with ioc.container:
+        MAIN_APP()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

semvertag-0.1.0/semvertag/_commit_parse.py

@@ -0,0 +1,29 @@
+import typing
+
+
+def subject_line(message: str) -> str:
+    for line in message.splitlines():
+        if line.strip():
+            return line.rstrip()
+    return ""
+
+
+def body_lines(message: str) -> list[str]:
+    lines: typing.Final = message.splitlines()
+    subject_seen = False
+    separator_seen = False
+    collected: list[str] = []
+    for line in lines:
+        if not subject_seen:
+            if line.strip():
+                subject_seen = True
+            continue
+        if not separator_seen:
+            if not line.strip():
+                separator_seen = True
+                continue
+            collected.append(line.rstrip())
+            continue
+        if line.strip():
+            collected.append(line.rstrip())
+    return collected

semvertag-0.1.0/semvertag/_errors.py

@@ -0,0 +1,17 @@
+import typing
+
+
+class SemvertagError(Exception):
+    exit_code: typing.ClassVar[int] = 1
+
+
+class ConfigError(SemvertagError):
+    exit_code: typing.ClassVar[int] = 2
+
+
+class AuthError(SemvertagError):
+    exit_code: typing.ClassVar[int] = 3
+
+
+class ProviderAPIError(SemvertagError):
+    exit_code: typing.ClassVar[int] = 4

semvertag-0.1.0/semvertag/_output.py

@@ -0,0 +1,78 @@
+import dataclasses
+import json
+import sys
+import typing
+
+import rich.console
+
+from semvertag._redact import redact
+from semvertag._types import RunResult
+
+
+_COMMIT_SHORT_LEN: typing.Final = 7
+
+
+class Output(typing.Protocol):
+    def progress(self, message: str) -> None: ...
+    def emit(self, result: RunResult) -> None: ...
+    def error(self, message: str) -> None: ...
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class RichOutput:
+    info_console: rich.console.Console
+    error_console: rich.console.Console
+    quiet: bool = False
+
+    def progress(self, message: str) -> None:
+        if self.quiet:
+            return
+        self.info_console.print(redact(message), markup=False, highlight=False)
+
+    def emit(self, result: RunResult) -> None:
+        self.info_console.print(redact(_format_result(result)), markup=False, highlight=False)
+
+    def error(self, message: str) -> None:
+        self.error_console.print(redact(message), markup=False, highlight=False)
+
+
+@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
+class JsonOutput:
+    error_console: rich.console.Console
+    quiet: bool = False
+
+    def progress(self, message: str) -> None:
+        _ = message
+
+    def emit(self, result: RunResult) -> None:
+        payload: typing.Final = json.dumps(dataclasses.asdict(result), separators=(",", ":"))
+        sys.stdout.write(payload + "\n")
+        sys.stdout.flush()
+
+    def error(self, message: str) -> None:
+        self.error_console.print(redact(message), markup=False, highlight=False)
+
+
+def _format_result(result: RunResult) -> str:
+    if result.status == "created":
+        short: typing.Final = (result.commit or "")[:_COMMIT_SHORT_LEN]
+        return f"Created tag {result.tag} on commit {short} (strategy: {result.strategy}, bump: {result.bump})"
+    return (
+        f"No tag created (status: {result.status}, strategy: {result.strategy}, "
+        f"bump: {result.bump}, reason: {result.reason})"
+    )
+
+
+def build_rich_output(*, quiet: bool = False) -> RichOutput:
+    return RichOutput(
+        info_console=rich.console.Console(),
+        error_console=rich.console.Console(stderr=True),
+        quiet=quiet,
+    )
+
+
+def build_json_output(*, quiet: bool = False) -> JsonOutput:
+    return JsonOutput(
+        error_console=rich.console.Console(stderr=True),
+        quiet=quiet,
+    )

semvertag-0.1.0/semvertag/_redact.py

@@ -0,0 +1,20 @@
+import re
+import typing
+
+
+_REDACTION: typing.Final = "***"
+_TOKEN_PATTERN: typing.Final = re.compile(
+    r"glpat-[A-Za-z0-9_\-]{20,}"
+    r"|github_pat_[A-Za-z0-9_]{20,}"
+    r"|ghp_[A-Za-z0-9]{20,}"
+    r"|gho_[A-Za-z0-9]{20,}"
+    r"|ghu_[A-Za-z0-9]{20,}"
+    r"|ghs_[A-Za-z0-9]{20,}"
+    r"|ghr_[A-Za-z0-9]{20,}"
+    r"|ATBB[A-Za-z0-9]{20,}"
+    r"|\b[0-9a-fA-F]{32,}\b",
+)
+
+
+def redact(text: str) -> str:
+    return _TOKEN_PATTERN.sub(_REDACTION, text)

semvertag-0.1.0/semvertag/_settings.py

@@ -0,0 +1,107 @@
+import logging
+import typing
+
+import pydantic
+import pydantic_settings
+
+from semvertag.strategies.branch_prefix import BranchPrefixConfig
+from semvertag.strategies.conventional_commits import ConventionalCommitsConfig
+
+
+_logger: typing.Final = logging.getLogger(__name__)
+
+_REQUEST_TIMEOUT_CEILING: typing.Final = 10.0
+_ENV_PREFIX: typing.Final = "SEMVERTAG_"
+_ENV_NESTED_DELIMITER: typing.Final = "__"
+
+
+class GitLabConfig(pydantic_settings.BaseSettings):
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_prefix="SEMVERTAG_GITLAB__",
+        case_sensitive=False,
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    endpoint: str = "https://gitlab.com"
+    token: pydantic.SecretStr = pydantic.Field(
+        default=pydantic.SecretStr(""),
+        validation_alias=pydantic.AliasChoices(
+            "SEMVERTAG_GITLAB__TOKEN",
+            "SEMVERTAG_TOKEN",
+            "CI_JOB_TOKEN",
+            "GITLAB_TOKEN",
+        ),
+    )
+
+
+class GitHubConfig(pydantic_settings.BaseSettings):
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_prefix="SEMVERTAG_GITHUB__",
+        case_sensitive=False,
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    token: pydantic.SecretStr = pydantic.Field(
+        default=pydantic.SecretStr(""),
+        validation_alias=pydantic.AliasChoices(
+            "SEMVERTAG_GITHUB__TOKEN",
+            "SEMVERTAG_TOKEN",
+            "GITHUB_TOKEN",
+        ),
+    )
+
+
+class Settings(pydantic_settings.BaseSettings):
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_prefix=_ENV_PREFIX,
+        env_nested_delimiter=_ENV_NESTED_DELIMITER,
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    strategy: typing.Literal["branch-prefix", "conventional-commits"] = "branch-prefix"
+    default_branch: str | None = None
+    request_timeout: float = pydantic.Field(default=8.0, gt=0)
+    project_id: int | None = pydantic.Field(
+        default=None,
+        validation_alias=pydantic.AliasChoices("SEMVERTAG_PROJECT_ID", "CI_PROJECT_ID"),
+    )
+    gitlab: GitLabConfig = pydantic.Field(default_factory=GitLabConfig)
+    github: GitHubConfig = pydantic.Field(default_factory=GitHubConfig)
+    branch_prefix: BranchPrefixConfig = pydantic.Field(default_factory=BranchPrefixConfig)
+    conventional_commits: ConventionalCommitsConfig = pydantic.Field(default_factory=ConventionalCommitsConfig)
+
+    @pydantic.field_validator("request_timeout")
+    @classmethod
+    def _clamp_request_timeout(cls, value: float) -> float:
+        if value > _REQUEST_TIMEOUT_CEILING:
+            _logger.warning(
+                "request_timeout=%.3f exceeds ceiling %.1f; clamping to %.1f",
+                value,
+                _REQUEST_TIMEOUT_CEILING,
+                _REQUEST_TIMEOUT_CEILING,
+            )
+            return _REQUEST_TIMEOUT_CEILING
+        return value
+
+
+def apply_cli_overlay(settings: Settings, overrides: dict[str, typing.Any]) -> Settings:
+    top_updates: dict[str, typing.Any] = {}
+    nested_updates: dict[str, dict[str, typing.Any]] = {}
+    for dotted_key, value in overrides.items():
+        head, _, leaf = dotted_key.partition(".")
+        if "." in leaf:
+            msg = f"CLI overlay key '{dotted_key}' exceeds nesting depth 2."
+            raise ValueError(msg)
+        if leaf:
+            nested_updates.setdefault(head, {})[leaf] = value
+        else:
+            top_updates[head] = value
+    for head, leaves in nested_updates.items():
+        top_updates[head] = getattr(settings, head).model_copy(update=leaves)
+    copied = settings.model_copy(update=top_updates)
+    # Re-validate to trigger field validators (e.g. _clamp_request_timeout).
+    # getattr (not model_dump) preserves live SecretStr values.
+    return type(settings).model_validate({name: getattr(copied, name) for name in type(copied).model_fields})