prepush-ci 0.0.0__tar.gz

prepush_ci-0.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: prepush-ci
+Version: 0.0.0
+Summary: Run the full CI check in the pre-push hook and let pull request CI skip commits that provably went through it
+Keywords: git,pre-push,ci,git-hooks,ai-agents,claude-code
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/CapeOfGoodCode/prepush-ci
+Project-URL: Issues, https://github.com/CapeOfGoodCode/prepush-ci/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/CapeOfGoodCode/prepush-ci/main/docs/assets/logo.svg" alt="prepush-ci logo" width="128">
+</p>
+
+# prepush-ci
+
+[![CI](https://github.com/CapeOfGoodCode/prepush-ci/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/CapeOfGoodCode/prepush-ci/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/CapeOfGoodCode/prepush-ci/python-coverage-comment-action-data/badge.svg)](https://github.com/CapeOfGoodCode/prepush-ci/tree/python-coverage-comment-action-data)
+[![PyPI](https://img.shields.io/pypi/v/prepush-ci)](https://pypi.org/project/prepush-ci/)
+[![Python](https://img.shields.io/pypi/pyversions/prepush-ci)](https://pypi.org/project/prepush-ci/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Built by loops](https://img.shields.io/badge/built%20by-5%20AI%20loops-8a2be2)](LOOP.md)
+[![Loops run on Spool](https://img.shields.io/badge/loops%20run%20on-Spool-0f172a)](https://github.com/enes-alatas/spool)
+
+Run the full CI check in the `pre-push` hook of an AI agent's cloud session (or any machine that opts in), and let pull request CI skip commits that provably went through it. The default branch always runs CI in full.
+
+The full check can run on any machine that opts in, for example on the VM of a [Claude Code cloud session](https://code.claude.com/docs/en/claude-code-on-the-web), which has no separate VM charge; pull request CI then does not repeat it on billed runners.
+
+> **Status: under construction.** The tool is being built by a small fleet of AI coding loops from the intent in [issue #1](https://github.com/CapeOfGoodCode/prepush-ci/issues/1). Nothing here is released yet.
+
+## How it works (in one paragraph)
+
+When `PREPUSH_CI=full` is set, a `commit-msg` hook writes the trailer `Prepush-CI: full` into each commit. The `pre-push` hook refuses to push a tip commit that carries the trailer unless the full check passes on it. A small gate in pull request CI reads the trailer of the head commit and skips the remaining jobs. The default branch ignores the trailer and runs CI in full. See [issue #1](https://github.com/CapeOfGoodCode/prepush-ci/issues/1) for the full design.
+
+## How this repository is built
+
+This repository is also an example of agentic engineering:
+
+- [`AGENTS.md`](AGENTS.md) is the rulebook for every contributor, human or agent (`CLAUDE.md` imports it).
+- [`LOOP.md`](LOOP.md) describes the loops that build the tool: their roles, the label state machine they share, what each may touch, and where a human decides.
+- [`openspec/`](openspec/) holds the specifications. Every feature starts as an OpenSpec change.
+- [`scripts/ci`](scripts/ci) is the one entry point for the full check; CI and the pre-push hook run the same script.
+- [`docs/agentic-engineering.md`](docs/agentic-engineering.md) maps the practices from [loop-engineering](https://github.com/cobusgreyling/loop-engineering) this repository adopts, and where it deviates.
+
+## Development
+
+```sh
+uv sync && npm ci          # Python tooling, OpenSpec CLI
+uv run pre-commit install  # commit-msg, pre-commit and pre-push hooks
+sh scripts/ci              # the full check, exactly as CI runs it
+```
+
+## License
+
+[MIT](LICENSE)

prepush_ci-0.0.0/README.md

@@ -0,0 +1,45 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/CapeOfGoodCode/prepush-ci/main/docs/assets/logo.svg" alt="prepush-ci logo" width="128">
+</p>
+
+# prepush-ci
+
+[![CI](https://github.com/CapeOfGoodCode/prepush-ci/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/CapeOfGoodCode/prepush-ci/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/CapeOfGoodCode/prepush-ci/python-coverage-comment-action-data/badge.svg)](https://github.com/CapeOfGoodCode/prepush-ci/tree/python-coverage-comment-action-data)
+[![PyPI](https://img.shields.io/pypi/v/prepush-ci)](https://pypi.org/project/prepush-ci/)
+[![Python](https://img.shields.io/pypi/pyversions/prepush-ci)](https://pypi.org/project/prepush-ci/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Built by loops](https://img.shields.io/badge/built%20by-5%20AI%20loops-8a2be2)](LOOP.md)
+[![Loops run on Spool](https://img.shields.io/badge/loops%20run%20on-Spool-0f172a)](https://github.com/enes-alatas/spool)
+
+Run the full CI check in the `pre-push` hook of an AI agent's cloud session (or any machine that opts in), and let pull request CI skip commits that provably went through it. The default branch always runs CI in full.
+
+The full check can run on any machine that opts in, for example on the VM of a [Claude Code cloud session](https://code.claude.com/docs/en/claude-code-on-the-web), which has no separate VM charge; pull request CI then does not repeat it on billed runners.
+
+> **Status: under construction.** The tool is being built by a small fleet of AI coding loops from the intent in [issue #1](https://github.com/CapeOfGoodCode/prepush-ci/issues/1). Nothing here is released yet.
+
+## How it works (in one paragraph)
+
+When `PREPUSH_CI=full` is set, a `commit-msg` hook writes the trailer `Prepush-CI: full` into each commit. The `pre-push` hook refuses to push a tip commit that carries the trailer unless the full check passes on it. A small gate in pull request CI reads the trailer of the head commit and skips the remaining jobs. The default branch ignores the trailer and runs CI in full. See [issue #1](https://github.com/CapeOfGoodCode/prepush-ci/issues/1) for the full design.
+
+## How this repository is built
+
+This repository is also an example of agentic engineering:
+
+- [`AGENTS.md`](AGENTS.md) is the rulebook for every contributor, human or agent (`CLAUDE.md` imports it).
+- [`LOOP.md`](LOOP.md) describes the loops that build the tool: their roles, the label state machine they share, what each may touch, and where a human decides.
+- [`openspec/`](openspec/) holds the specifications. Every feature starts as an OpenSpec change.
+- [`scripts/ci`](scripts/ci) is the one entry point for the full check; CI and the pre-push hook run the same script.
+- [`docs/agentic-engineering.md`](docs/agentic-engineering.md) maps the practices from [loop-engineering](https://github.com/cobusgreyling/loop-engineering) this repository adopts, and where it deviates.
+
+## Development
+
+```sh
+uv sync && npm ci          # Python tooling, OpenSpec CLI
+uv run pre-commit install  # commit-msg, pre-commit and pre-push hooks
+sh scripts/ci              # the full check, exactly as CI runs it
+```
+
+## License
+
+[MIT](LICENSE)

prepush_ci-0.0.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "prepush-ci"
+version = "0.0.0"
+description = "Run the full CI check in the pre-push hook and let pull request CI skip commits that provably went through it"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+keywords = [
+    "git",
+    "pre-push",
+    "ci",
+    "git-hooks",
+    "ai-agents",
+    "claude-code",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://github.com/CapeOfGoodCode/prepush-ci"
+Issues = "https://github.com/CapeOfGoodCode/prepush-ci/issues"
+
+[project.scripts]
+prepush-ci = "prepush_ci.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]>=7.10",
+    "mypy>=1.18",
+    "pre-commit>=4.3",
+    "pytest>=8.4",
+    "ruff>=0.13",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "*_spec.py"
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+source = ["prepush_ci"]
+branch = true
+relative_files = true
+patch = ["subprocess"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "E",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "C4",
+    "SIM",
+]
+ignore = ["E501"]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+python_version = "3.11"

prepush_ci-0.0.0/pyproject.toml.orig

@@ -0,0 +1,70 @@
+[project]
+name = "prepush-ci"
+version = "0.0.0"
+description = "Run the full CI check in the pre-push hook and let pull request CI skip commits that provably went through it"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"   # tomllib in the standard library; uvx brings its own Python anyway
+dependencies = []
+keywords = ["git", "pre-push", "ci", "git-hooks", "ai-agents", "claude-code"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://github.com/CapeOfGoodCode/prepush-ci"
+Issues = "https://github.com/CapeOfGoodCode/prepush-ci/issues"
+
+[project.scripts]
+prepush-ci = "prepush_ci.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]>=7.10",
+    "mypy>=1.18",
+    "pre-commit>=4.3",
+    "pytest>=8.4",
+    "ruff>=0.13",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "*_spec.py"   # tests are specs; pytest collects nothing else
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+source = ["prepush_ci"]
+branch = true
+relative_files = true   # the coverage comment action reads paths relative to the repository
+patch = ["subprocess"]  # hooks run the CLI in a subprocess via git; measure that too
+
+[tool.coverage.report]
+# Gates live in scripts/ci: 100% of core from tests/unit alone, 95% overall. patch=subprocess
+# measures the CLI when tests start it as `sys.executable -m prepush_ci`, and combines automatically.
+show_missing = true
+exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]   # the formatter owns line length
+
+[tool.mypy]
+strict = true
+files = ["src"]
+python_version = "3.11"

prepush_ci-0.0.0/src/prepush_ci/__init__.py

@@ -0,0 +1 @@
+"""prepush-ci: run the full CI check before push, let pull request CI skip what it proved."""

prepush_ci-0.0.0/src/prepush_ci/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m prepush_ci`: how hooks and integration tests start the CLI (coverage follows it)."""
+
+from prepush_ci.cli import main
+
+raise SystemExit(main())

prepush_ci-0.0.0/src/prepush_ci/checking.py

@@ -0,0 +1,52 @@
+"""The steps `run` and the pre-push hook share: what must hold before the check, and the check."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+from prepush_ci.core.config import Config
+from prepush_ci.core.pre_push import message_dirty, message_hidden
+from prepush_ci.git import dirty, git, hidden
+
+
+class Refused(Exception):
+    """The check cannot run on this state; the message says why."""
+
+
+def head(cwd: Path) -> str:
+    result = git(cwd, "rev-parse", "--verify", "--quiet", "HEAD^{commit}")
+    if result.returncode != 0:
+        raise Refused("HEAD points to no commit, so there is nothing to check")
+    return result.stdout.strip()
+
+
+def require_clean(root: Path) -> None:
+    """Refuse a worktree whose state is not the commit: changes, or changes git hides."""
+    dirty_files = dirty(root)
+    if dirty_files:
+        raise Refused(message_dirty(dirty_files))
+    hidden_files = hidden(root)
+    if hidden_files:
+        raise Refused(message_hidden(hidden_files))
+
+
+def worktree_root(cwd: Path) -> Path:
+    result = git(cwd, "rev-parse", "--show-toplevel")
+    if result.returncode != 0:
+        raise Refused(
+            "the repository has no worktree, so there is no commit to check here"
+        )
+    return Path(result.stdout.strip())
+
+
+def run_check(config: Config, root: Path) -> int:
+    outcome = subprocess.run(
+        config.check, shell=True, cwd=root, stdin=subprocess.DEVNULL, check=False
+    )
+    if outcome.returncode != 0:
+        print(
+            f"prepush-ci: the check failed (exit {outcome.returncode}): {config.check}",
+            file=sys.stderr,
+        )
+        return 1
+    return 0

prepush_ci-0.0.0/src/prepush_ci/cli.py

@@ -0,0 +1,79 @@
+"""Command-line entry point."""
+
+import argparse
+import os
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from prepush_ci import (
+    commit_msg_hook,
+    install_command,
+    pre_push_hook,
+    run_command,
+    strip_command,
+    verify_command,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_in = sys.argv[1:] if argv is None else argv
+    if args_in[:1] == ["--"]:
+        args_in = args_in[
+            1:
+        ]  # `prepush-ci -- verify "$SHA"` must reach the route below
+    if args_in[:1] == ["verify"]:
+        # Before argparse: its usage errors exit 2 and `--help` exits 0, but a CI gate must only
+        # ever see 0 (verified) or 1.
+        return verify_command.run(args_in[1:], Path.cwd())
+    parser = argparse.ArgumentParser(
+        prog="prepush-ci",
+        epilog="also: verify <sha>  exit 0 when a commit carries the trailer and was not "
+        "made by a server",  # not a subparser: argparse could never be allowed to answer for it
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {version('prepush-ci')}"
+    )
+    commands = parser.add_subparsers(dest="command")
+    hook = commands.add_parser("hook", help="entry points that git hooks call")
+    hooks = hook.add_subparsers(dest="hook", required=True)
+    commands.add_parser(
+        "run",
+        help="run the preflight and the check on HEAD, as the pre-push hook would",
+    )
+    commands.add_parser("install", help="point git at hooks that run this tool")
+    commit_msg = hooks.add_parser(
+        "commit-msg", help="write the trailer when PREPUSH_CI=full"
+    )
+    commit_msg.add_argument(
+        "file", type=Path, help="the commit message file git passes"
+    )
+    pre_push = hooks.add_parser(
+        "pre-push",
+        help="refuse to push a commit with the trailer unless the check passes",
+    )
+    pre_push.add_argument(
+        "git_args", nargs="*", help="the remote name and url git passes (unused)"
+    )
+    strip = commands.add_parser(
+        "strip",
+        help="remove the trailer from the commits since <base>, so a push needs no check",
+    )
+    strip.add_argument(
+        "base",
+        nargs="*",
+        help="the commit before yours (default: the merge base with the default branch)",
+    )
+    args = parser.parse_args(args_in)
+    if args.command == "strip":
+        return strip_command.run(args.base, Path.cwd())
+    if args.command == "run":
+        return run_command.run(os.environ, Path.cwd())
+    if args.command == "install":
+        return install_command.run(Path.cwd())
+    if args.command == "hook" and args.hook == "pre-push":
+        return pre_push_hook.run(sys.stdin, os.environ, Path.cwd())
+    if args.command == "hook":
+        return commit_msg_hook.run(args.file, os.environ, Path.cwd())
+    parser.print_help()
+    return 0

prepush_ci-0.0.0/src/prepush_ci/commit_msg_hook.py

@@ -0,0 +1,116 @@
+"""`prepush-ci hook commit-msg <file>`: write the trailer that demands the full check."""
+
+import subprocess
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from prepush_ci.core.commit_msg import (
+    InvalidMode,
+    Mode,
+    UnsupportedCommentChar,
+    editor_was_used,
+    is_blank_message,
+    is_template_untouched,
+    parse_mode,
+    require_known_comment_setting,
+    resolve_cleanup,
+)
+from prepush_ci.core.config import ConfigError
+from prepush_ci.repo_config import load_repository_config
+
+ENV_VAR = "PREPUSH_CI"
+
+
+def run(message_file: Path, env: Mapping[str, str], cwd: Path) -> int:
+    """Run the hook; return the exit code (non-zero makes git abort the commit)."""
+    try:
+        mode = parse_mode(env.get(ENV_VAR))
+    except InvalidMode as error:
+        print(f"prepush-ci: {error}", file=sys.stderr)
+        return 1
+    if mode is Mode.OFF:
+        return 0
+    try:
+        config = load_repository_config(cwd)
+    except ConfigError as error:
+        for problem in error.problems:
+            print(f"prepush-ci: {problem}", file=sys.stderr)
+        return 1
+    try:
+        require_known_comment_setting(_comment_setting(cwd))
+    except UnsupportedCommentChar as error:
+        print(f"prepush-ci: {error}", file=sys.stderr)
+        return 1
+    text = message_file.read_text(encoding="utf-8")
+    editor_used = editor_was_used(env.get("GIT_EDITOR"), text)
+    cleanup = resolve_cleanup(_git_config(cwd, "commit.cleanup"), editor_used)
+    comment = _comment_prefix(cwd)
+    if is_blank_message(text, cleanup, comment):
+        return 0
+    template = (
+        _commit_template(cwd) if editor_used else None
+    )  # git checks only after an editor
+    if template is not None and is_template_untouched(text, template, cleanup, comment):
+        return 0
+    subprocess.run(
+        [
+            "git",
+            "interpret-trailers",
+            "--in-place",
+            "--no-divider",
+            "--where",
+            "start",
+            "--if-exists",
+            "doNothing",
+            "--trailer",
+            config.trailer.line(),
+            str(message_file),
+        ],
+        check=True,
+    )
+    return 0
+
+
+def _comment_setting(cwd: Path) -> str | None:
+    """What the repository configures as comment prefix (`commentString` is newer git)."""
+    for name in ("core.commentString", "core.commentChar"):
+        value = _git_config(cwd, name)
+        if value is not None:
+            return value
+    return None
+
+
+def _git_config(cwd: Path, name: str, *, as_path: bool = False) -> str | None:
+    result = subprocess.run(
+        ["git", "config", "--get", *(["--type=path"] if as_path else []), name],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.removesuffix("\n") if result.returncode == 0 else None
+
+
+def _comment_prefix(cwd: Path) -> str:
+    """The comment prefix of the git that runs the hook, whichever settings it honours."""
+    result = subprocess.run(
+        ["git", "stripspace", "--comment-lines"],
+        cwd=cwd,
+        input="x\n",
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.removesuffix(" x\n")
+
+
+def _commit_template(cwd: Path) -> str | None:
+    """The text of `commit.template`, or None when unset or unreadable (git reports that itself)."""
+    path = _git_config(cwd, "commit.template", as_path=True)
+    if path is None:
+        return None
+    try:
+        return (cwd / path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None

prepush_ci-0.0.0/src/prepush_ci/core/__init__.py

@@ -0,0 +1,5 @@
+"""The pure core: decisions without I/O (trailers, config values, ref lines, verify).
+
+Nothing here touches the file system, processes, the environment or the network; the CLI and
+hook modules do that and pass plain values in. tests/unit covers this package to 100% on its own.
+"""

prepush_ci-0.0.0/src/prepush_ci/core/commit_msg.py

@@ -0,0 +1,144 @@
+"""Decisions of the commit-msg hook: what `PREPUSH_CI` asks for, and whether a message is empty."""
+
+from enum import Enum
+
+
+class Mode(Enum):
+    OFF = "off"
+    FULL = "full"
+
+
+class InvalidMode(Exception):
+    """`PREPUSH_CI` holds a value other than `full`, `off` or the empty string."""
+
+
+def parse_mode(value: str | None) -> Mode:
+    """Unset and empty mean `off`; values are compared exactly, so `FULL` is refused."""
+    if value is None or value == "":
+        return Mode.OFF
+    try:
+        return Mode(value)
+    except ValueError:
+        raise InvalidMode(
+            f"PREPUSH_CI={value!r} is not valid: use `full` to demand the full check "
+            "on this commit, or `off` (or leave it unset) to commit as usual"
+        ) from None
+
+
+SIGN_OFF = (
+    "Signed-off-by: "  # `git commit -s`; git does not count these lines as a message
+)
+
+
+class UnsupportedCommentChar(Exception):
+    """`core.commentChar` holds a value the hook cannot interpret."""
+
+
+def require_known_comment_setting(setting: str | None) -> None:
+    """Refuse `auto` and empty: git picks the comment prefix per commit, so it cannot be known here."""
+    if setting in ("", "auto"):
+        raise UnsupportedCommentChar(
+            f"core.commentChar={setting!r} is not supported with PREPUSH_CI=full: "
+            "git picks the comment character per commit, so the hook cannot tell an "
+            "empty message from one that holds only the trailer; set core.commentChar "
+            "to a fixed character such as `#`, or commit with PREPUSH_CI=off"
+        )
+
+
+class Cleanup(Enum):
+    """How git cleans the message up after the `commit-msg` hook (`commit.cleanup`)."""
+
+    STRIP = "strip"
+    WHITESPACE = "whitespace"
+    VERBATIM = "verbatim"
+    SCISSORS = "scissors"
+
+
+def editor_was_used(git_editor: str | None, text: str) -> bool:
+    """Whether git launched an editor, which hooks cannot be told directly.
+
+    Git sets `GIT_EDITOR=:` for its hooks when it launches none. A user who chose the no-op
+    editor `:` still leaves git's template in the message, which starts with an empty line.
+    """
+    return git_editor != ":" or text.startswith("\n")
+
+
+def resolve_cleanup(configured: str | None, editor_used: bool) -> Cleanup:
+    """The cleanup git applies: `commit.cleanup`, else `strip` with an editor, `whitespace` without.
+
+    An explicit `git commit --cleanup=<mode>` is invisible to hooks and not accounted for.
+    """
+    try:
+        return Cleanup(configured)
+    except ValueError:  # unset or "default"
+        return Cleanup.STRIP if editor_used else Cleanup.WHITESPACE
+
+
+def is_blank_message(
+    text: str, cleanup: Cleanup = Cleanup.STRIP, comment: str = "#"
+) -> bool:
+    """True when git will find nothing in the message after its cleanup and abort the commit.
+
+    Like git, ignore everything from the scissors line on (the diff of `git commit -v`) and
+    sign-off lines (`git commit -s` adds one to an empty message).
+    Only `strip` drops comment lines; in the other modes they are the message.
+    """
+    scissors = f"{comment} ------------------------ >8 ------------------------"
+    kept: list[str] = []
+    for line in text.splitlines():
+        if line.startswith(scissors):
+            break
+        kept.append(line)
+    if cleanup is Cleanup.VERBATIM:
+        return not kept
+    drops_comments = cleanup is Cleanup.STRIP
+    return not any(
+        line.strip()
+        and not line.startswith(SIGN_OFF)
+        and not (drops_comments and line.startswith(comment))
+        for line in kept
+    )
+
+
+def clean_up(text: str, cleanup: Cleanup, comment: str = "#") -> str:
+    """The message the way git's cleanup leaves it (`git stripspace`), for comparing messages.
+
+    Like git, cut at the scissors line, trim trailing whitespace, collapse runs of empty lines
+    and drop leading and trailing ones; `strip` also drops comment lines. `verbatim` keeps the text.
+    """
+    scissors = f"{comment} ------------------------ >8 ------------------------"
+    if cleanup is Cleanup.VERBATIM:
+        return text
+    lines: list[str] = []
+    for line in text.splitlines():
+        if line.startswith(scissors):
+            break
+        if cleanup is Cleanup.STRIP and line.startswith(comment):
+            continue
+        line = line.rstrip()
+        if line or (lines and lines[-1]):
+            lines.append(line)
+    while lines and not lines[-1]:
+        lines.pop()
+    return "".join(f"{line}\n" for line in lines)
+
+
+def is_template_untouched(
+    text: str, template: str, cleanup: Cleanup, comment: str = "#"
+) -> bool:
+    """True when git will find the message unchanged from `commit.template` and abort the commit.
+
+    Git compares the cleaned message with the cleaned template, so a trailer added by the hook
+    would make an unedited template look edited. Sign-off lines after the template do not count
+    as an edit, and a verbatim message is never untouched.
+    """
+    if cleanup is Cleanup.VERBATIM or not template:
+        return False
+    cleaned_template = clean_up(template, cleanup, comment)
+    cleaned = clean_up(text, cleanup, comment)
+    if not cleaned.startswith(cleaned_template):
+        return False
+    rest = cleaned.removeprefix(cleaned_template)
+    return all(
+        not line.strip() or line.startswith(SIGN_OFF) for line in rest.splitlines()
+    )