conventional-release 0.1.0__py3-none-any.whl

conventional_release/__init__.py

@@ -0,0 +1,8 @@
+"""standard-version-style CHANGELOG and release PRs from Conventional Commits."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("conventional-release")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"

conventional_release/__main__.py

@@ -0,0 +1,3 @@
+from conventional_release.cli import main
+
+raise SystemExit(main())

conventional_release/cli.py

@@ -0,0 +1,123 @@
+"""Command line: `conventional-release <command>` (alias `crel`)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from conventional_release import __version__, cliff, release
+from conventional_release.config import Config, ConfigError, load
+from conventional_release.git import GitError
+from conventional_release.versionfiles import VersionFileError
+
+EXPECTED = (ConfigError, GitError, VersionFileError, cliff.CliffError, release.ReleaseError)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="conventional-release",
+        description="standard-version-style CHANGELOG and release PRs from Conventional Commits.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument(
+        "-C", dest="root", type=Path, default=Path.cwd(), help="run as if started in this directory"
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    r = sub.add_parser("release", help="branch, CHANGELOG, version bump, commit, push, open a PR")
+    r.add_argument(
+        "bump", nargs="?", help="major | minor | patch | X.Y.Z (default: inferred from the commits)"
+    )
+    r.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print the version and the changelog section, change nothing",
+    )
+    r.add_argument("--no-push", action="store_true", help="stop after the local commit")
+    r.add_argument("--no-pr", action="store_true", help="push the branch but open no PR")
+
+    sub.add_parser("current", help="print the current version")
+    n = sub.add_parser("next", help="print the version the next release would get")
+    n.add_argument("bump", nargs="?", help="major | minor | patch | X.Y.Z")
+
+    no = sub.add_parser("notes", help="print one version's CHANGELOG section (release notes)")
+    no.add_argument("version")
+
+    d = sub.add_parser("detect", help="CI: is HEAD a release commit that still needs its tag?")
+    d.add_argument(
+        "--github-output",
+        action="store_true",
+        help="also append released/version/tag to $GITHUB_OUTPUT",
+    )
+
+    t = sub.add_parser("tag", help="CI: create the annotated tag for VERSION on HEAD")
+    t.add_argument("version")
+    t.add_argument("--push", action="store_true", help="push the tag to origin")
+
+    c = sub.add_parser("check-title", help="validate a PR title / commit subject")
+    c.add_argument("title")
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        config = load(args.root.resolve())
+        return _run(args, config)
+    except EXPECTED as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+def _run(args: argparse.Namespace, config: Config) -> int:
+    if args.command == "current":
+        print(release.current_version(config) or "")
+    elif args.command == "next":
+        print(release.plan(config, args.bump)[1])
+    elif args.command == "notes":
+        print(release.notes(config, args.version), end="")
+    elif args.command == "check-title":
+        problems = release.check_title(config, args.title)
+        for problem in problems:
+            print(f"error: {problem}", file=sys.stderr)
+        return 1 if problems else 0
+    elif args.command == "detect":
+        result = release.detect(config)
+        print(result.outputs(), end="")
+        if result.reason:
+            print(result.reason, file=sys.stderr)
+        if args.github_output:
+            with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+                f.write(result.outputs())
+    elif args.command == "tag":
+        print(release.create_tag(config, args.version, push=args.push))
+    elif args.command == "release":
+        return _release(args, config)
+    return 0
+
+
+def _release(args: argparse.Namespace, config: Config) -> int:
+    current, version = release.plan(config, args.bump)
+    print(f"release {current or '(none)'} -> {version}", file=sys.stderr)
+    if args.dry_run:
+        print(
+            f"(dry run — nothing written; branch would be {config.branch(version)})\n",
+            file=sys.stderr,
+        )
+        print(cliff.unreleased_section(config, version))
+        return 0
+    release.cut(config, args.bump, push=not args.no_push, open_pr=not args.no_pr)
+    if args.no_push:
+        print(
+            f"committed on {config.branch(version)}; push it and open a PR titled "
+            f'"chore(release): {version}"',
+            file=sys.stderr,
+        )
+    else:
+        print(
+            "Squash-merge the PR with its title as-is; CI tags the merge commit.", file=sys.stderr
+        )
+    return 0

conventional_release/cliff.py

@@ -0,0 +1,197 @@
+"""Drive git-cliff with a generated config that renders standard-version's CHANGELOG shape:
+
+    ## 1.2.0 (2026-09-25)
+
+    ### ⚠ BREAKING CHANGES
+
+    * **api:** drop the v1 endpoints
+
+    ### Features
+
+    * **cli:** add --json ([#42](https://github.com/o/r/issues/42)) ([abc1234](https://github.com/o/r/commit/abc1234...))
+
+The PR number comes from squash-merging: GitHub appends " (#N)" to the PR title, the title
+becomes the commit subject, and a preprocessor turns it into a link. A project with its own
+cliff.toml sets `cliff-config` and this module passes it through untouched.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from conventional_release import git
+from conventional_release.config import Config
+
+HEADER = """\
+# Changelog
+
+All notable changes to this project will be documented in this file. Generated by
+[conventional-release](https://github.com/MdaaaaO/conventional-release) from
+[Conventional Commits](https://www.conventionalcommits.org).
+
+"""
+
+
+class CliffError(Exception):
+    pass
+
+
+def _q(value: str) -> str:
+    """A TOML basic string. JSON's escaping is a subset of TOML's."""
+    return json.dumps(value, ensure_ascii=False)
+
+
+# Tera template. The trailing backslashes are TOML line continuations inside the """ string —
+# they are what keeps the output free of stray blank lines.
+_BODY = r"""
+{% if version %}\
+## {{ version | trim_start_matches(pat=@@PREFIX@@) }} ({{ timestamp | date(format="%Y-%m-%d") }})
+{% else %}\
+## Unreleased
+{% endif %}\
+{% set breaking = commits | filter(attribute="breaking", value=true) %}\
+{% if breaking | length > 0 %}
+
+### ⚠ BREAKING CHANGES
+
+{% for commit in breaking %}\
+* {% if commit.scope %}**{{ commit.scope }}:** {% endif %}\
+{% if commit.breaking_description %}{{ commit.breaking_description | trim }}\
+{% else %}{{ commit.message | trim }}{% endif %}
+{% endfor %}\
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+
+### {{ group | striptags | trim }}
+
+{% for commit in commits %}\
+* {% if commit.scope %}**{{ commit.scope }}:** {% endif %}{{ commit.message | trim }}@@LINK@@
+{% endfor %}\
+{% endfor %}
+"""
+
+_LINK = (
+    r' ([{{ commit.id | truncate(length=7, end="") }}]'
+    r"(@@URL@@/commit/{{ commit.id }}))"
+)
+
+
+def render_config(config: Config, repo_url: str | None, *, with_header: bool) -> str:
+    body = _BODY.replace("@@PREFIX@@", _q(config.tag_prefix))
+    body = body.replace("@@LINK@@", _LINK.replace("@@URL@@", repo_url) if repo_url else "")
+
+    parsers = ['  { message = "^chore\\\\(release\\\\)", skip = true },']
+    for n, t in enumerate(config.types):
+        pattern = _q(rf"^{re.escape(t.type)}(\(.*\))?!?:")
+        if t.hidden:
+            parsers.append(f"  {{ message = {pattern}, skip = true }},")
+        else:
+            group = _q(f"<!-- {n:02d} -->{t.section}")
+            parsers.append(f"  {{ message = {pattern}, group = {group} }},")
+
+    preprocessors = []
+    if repo_url:
+        # (?m): a squash commit's message is the subject *plus* the PR body, so "$" must mean
+        # end of line — without the flag nothing matches.
+        pattern = _q(r"(?m)\s\(#([0-9]+)\)$")
+        replace = _q(" ([#${1}](" + repo_url + "/issues/${1}))")
+        preprocessors.append(f"  {{ pattern = {pattern}, replace = {replace} }},")
+
+    header = HEADER if with_header else ""
+    return f'''\
+[changelog]
+header = {_q(header)}
+body = """{body}"""
+trim = true
+footer = ""
+
+[git]
+conventional_commits = true
+filter_unconventional = true
+split_commits = false
+protect_breaking_commits = true
+sort_commits = "oldest"
+tag_pattern = {_q("^" + re.escape(config.tag_prefix) + "[0-9]")}
+commit_preprocessors = [
+{chr(10).join(preprocessors)}
+]
+commit_parsers = [
+{chr(10).join(parsers)}
+]
+
+[bump]
+features_always_bump_minor = true
+breaking_always_bump_major = true
+initial_tag = {_q(config.tag(config.initial_version))}
+'''
+
+
+def binary() -> str:
+    """git-cliff from this interpreter's environment (the `git-cliff` wheel), else PATH."""
+    sibling = Path(sys.executable).parent / "git-cliff"
+    if sibling.is_file():
+        return str(sibling)
+    found = shutil.which("git-cliff")
+    if found is None:
+        raise CliffError("git-cliff not found — install the git-cliff package")
+    return found
+
+
+def repo_url(config: Config) -> str | None:
+    if config.repo_url:
+        return config.repo_url.rstrip("/")
+    remote = git.remote_url(config.root)
+    return git.web_url(remote) if remote else None
+
+
+@contextmanager
+def _config_file(config: Config, *, with_header: bool) -> Iterator[Path]:
+    if config.cliff_config:
+        yield config.root / config.cliff_config
+        return
+    with tempfile.TemporaryDirectory(prefix="conventional-release-") as tmp:
+        path = Path(tmp) / "cliff.toml"
+        path.write_text(render_config(config, repo_url(config), with_header=with_header))
+        yield path
+
+
+def run(config: Config, *args: str, with_header: bool = False) -> str:
+    with _config_file(config, with_header=with_header) as cfg:
+        proc = subprocess.run(
+            [binary(), "--config", str(cfg), *args],
+            cwd=config.root,
+            capture_output=True,
+            text=True,
+        )
+    if proc.returncode != 0:
+        raise CliffError(f"git-cliff {' '.join(args)} failed:\n{proc.stderr.strip()}")
+    return proc.stdout
+
+
+def bumped_version(config: Config) -> str:
+    out = run(config, "--bumped-version").strip()
+    return out.removeprefix(config.tag_prefix)
+
+
+def unreleased_section(config: Config, version: str) -> str:
+    """The section the next release will add, heading included, no header."""
+    return run(config, "--unreleased", "--tag", config.tag(version), "--strip", "all").strip()
+
+
+def regenerate(config: Config, version: str) -> None:
+    run(
+        config,
+        "--tag",
+        config.tag(version),
+        "--output",
+        str(config.changelog_path),
+        with_header=True,
+    )

conventional_release/config.py

@@ -0,0 +1,164 @@
+"""Project configuration: `.conventional-release.toml`, or `[tool.conventional-release]` in
+pyproject.toml. Every key is optional; the defaults reproduce standard-version's behaviour."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILE = ".conventional-release.toml"
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class CommitType:
+    type: str
+    section: str
+    hidden: bool = False
+
+
+# The Angular set, which Conventional Commits grew out of, in the order standard-version's
+# `.versionrc` examples use. Every type gets a section by default; set `hidden = true` to drop one.
+DEFAULT_TYPES: tuple[CommitType, ...] = (
+    CommitType("feat", "Features"),
+    CommitType("fix", "Bug Fixes"),
+    CommitType("docs", "Documentation"),
+    CommitType("style", "Styling"),
+    CommitType("refactor", "Refactors"),
+    CommitType("perf", "Performance"),
+    CommitType("test", "Tests"),
+    CommitType("build", "Build System"),
+    CommitType("ci", "CI"),
+    CommitType("chore", "Chore"),
+    CommitType("revert", "Reverts"),
+)
+
+VERSION_SOURCES = ("file", "tag")
+CHANGELOG_MODES = ("prepend", "regenerate")
+
+# Probed in this order when `version-files` is not set and `version-source = "file"`.
+AUTODETECT_FILES = ("pyproject.toml", "package.json", "Cargo.toml", "VERSION", "version")
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path
+    version_source: str = "file"
+    version_files: tuple[str, ...] = ()
+    changelog: str = "CHANGELOG.md"
+    changelog_mode: str = "prepend"
+    tag_prefix: str = "v"
+    base_branch: str = "main"
+    branch_prefix: str = "release/"
+    initial_version: str = "0.1.0"
+    repo_url: str | None = None
+    cliff_config: str | None = None
+    subject_lowercase: bool = True
+    types: tuple[CommitType, ...] = field(default=DEFAULT_TYPES)
+
+    @property
+    def changelog_path(self) -> Path:
+        return self.root / self.changelog
+
+    def tag(self, version: str) -> str:
+        return f"{self.tag_prefix}{version}"
+
+    def branch(self, version: str) -> str:
+        return f"{self.branch_prefix}{self.tag(version)}"
+
+
+_SCALAR_KEYS = {
+    "version-source": ("version_source", str),
+    "changelog": ("changelog", str),
+    "changelog-mode": ("changelog_mode", str),
+    "tag-prefix": ("tag_prefix", str),
+    "base-branch": ("base_branch", str),
+    "branch-prefix": ("branch_prefix", str),
+    "initial-version": ("initial_version", str),
+    "repo-url": ("repo_url", str),
+    "cliff-config": ("cliff_config", str),
+    "subject-lowercase": ("subject_lowercase", bool),
+}
+
+
+def _raw(root: Path) -> tuple[dict[str, Any], str]:
+    dedicated = root / CONFIG_FILE
+    if dedicated.is_file():
+        with dedicated.open("rb") as f:
+            return tomllib.load(f), CONFIG_FILE
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+        section = data.get("tool", {}).get("conventional-release")
+        if section is not None:
+            return section, "pyproject.toml [tool.conventional-release]"
+    return {}, "defaults"
+
+
+def load(root: Path) -> Config:
+    raw, where = _raw(root)
+    kwargs: dict[str, Any] = {}
+    for key, value in raw.items():
+        if key in _SCALAR_KEYS:
+            name, kind = _SCALAR_KEYS[key]
+            if not isinstance(value, kind):
+                raise ConfigError(f"{where}: {key} must be a {kind.__name__}")
+            kwargs[name] = value
+        elif key == "version-files":
+            if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                raise ConfigError(f"{where}: version-files must be a list of paths")
+            kwargs["version_files"] = tuple(value)
+        elif key == "types":
+            kwargs["types"] = _types(value, where)
+        else:
+            raise ConfigError(f"{where}: unknown key {key!r}")
+
+    config = Config(root=root, **kwargs)
+    if config.version_source not in VERSION_SOURCES:
+        raise ConfigError(f"{where}: version-source must be one of {VERSION_SOURCES}")
+    if config.changelog_mode not in CHANGELOG_MODES:
+        raise ConfigError(f"{where}: changelog-mode must be one of {CHANGELOG_MODES}")
+    return config
+
+
+def _types(value: Any, where: str) -> tuple[CommitType, ...]:
+    if not isinstance(value, list) or not value:
+        raise ConfigError(f"{where}: types must be a non-empty array of tables")
+    out = []
+    for item in value:
+        if not isinstance(item, dict) or not isinstance(item.get("type"), str):
+            raise ConfigError(f"{where}: every types entry needs a string 'type'")
+        section = item.get("section", item["type"])
+        hidden = item.get("hidden", False)
+        if not isinstance(section, str) or not isinstance(hidden, bool):
+            raise ConfigError(f"{where}: types.{item['type']}: section is a string, hidden a bool")
+        out.append(CommitType(item["type"], section, hidden))
+    return tuple(out)
+
+
+def version_files(config: Config) -> list[Path]:
+    """The files that carry the version, auto-detected when not configured."""
+    if config.version_source == "tag":
+        return []
+    if config.version_files:
+        paths = [config.root / p for p in config.version_files]
+        missing = [str(p.relative_to(config.root)) for p in paths if not p.is_file()]
+        if missing:
+            raise ConfigError(f"version-files not found: {', '.join(missing)}")
+        return paths
+    from conventional_release import versionfiles
+
+    for name in AUTODETECT_FILES:
+        path = config.root / name
+        if path.is_file() and versionfiles.has_version(path):
+            return [path]
+    raise ConfigError(
+        "no version file found (looked for " + ", ".join(AUTODETECT_FILES) + "). "
+        'Set version-files, or version-source = "tag" if the git tag is the version.'
+    )

conventional_release/git.py

@@ -0,0 +1,68 @@
+"""Thin wrappers over the git CLI. Every call raises on a non-zero exit."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+
+class GitError(Exception):
+    pass
+
+
+def run(root: Path, *args: str) -> str:
+    proc = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise GitError(f"git {' '.join(args)}: {proc.stderr.strip() or proc.stdout.strip()}")
+    return proc.stdout.strip()
+
+
+def status_porcelain(root: Path) -> str:
+    return run(root, "status", "--porcelain")
+
+
+def latest_tag(root: Path, prefix: str) -> str | None:
+    try:
+        return run(root, "describe", "--tags", "--abbrev=0", "--match", f"{prefix}[0-9]*")
+    except GitError:
+        return None
+
+
+def tag_exists(root: Path, tag: str) -> bool:
+    try:
+        run(root, "rev-parse", "--verify", "--quiet", f"refs/tags/{tag}")
+    except GitError:
+        return False
+    return True
+
+
+def branch_exists(root: Path, branch: str) -> bool:
+    try:
+        run(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
+    except GitError:
+        return False
+    return True
+
+
+def head_subject(root: Path) -> str:
+    return run(root, "log", "-1", "--pretty=%s")
+
+
+def remote_url(root: Path, remote: str = "origin") -> str | None:
+    try:
+        return run(root, "remote", "get-url", remote)
+    except GitError:
+        return None
+
+
+_SSH = re.compile(r"^(?:ssh://)?git@([^:/]+)[:/](.+?)(?:\.git)?/?$")
+_HTTPS = re.compile(r"^https?://(?:[^@/]+@)?([^/]+)/(.+?)(?:\.git)?/?$")
+
+
+def web_url(remote: str) -> str | None:
+    """git@github.com:o/r.git, https://x@github.com/o/r → https://github.com/o/r"""
+    for pattern in (_SSH, _HTTPS):
+        if m := pattern.match(remote):
+            return f"https://{m.group(1)}/{m.group(2)}"
+    return None