prepush-ci 0.0.0__py3-none-any.whl

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/__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/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/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/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/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/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()
+    )

prepush_ci/core/config.py

@@ -0,0 +1,169 @@
+"""Turn the config table into a typed `Config`, or into every problem found in it."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_TRAILER_KEY = "Prepush-CI"
+DEFAULT_TRAILER_VALUE = "full"
+DEFAULT_BRANCH = "main"
+REMOTE = "origin"
+
+_TRAILER_TOKEN = re.compile(r"[A-Za-z0-9-]+")
+_KEYS = (
+    "check",
+    "preflight",
+    "require_env",
+    "require_up_to_date",
+    "default_branch",
+    "trailer",
+    "legacy_keys",
+    "cache",
+)
+_TRAILER_KEYS = ("key", "value")
+
+
+@dataclass(frozen=True)
+class Trailer:
+    key: str
+    value: str
+
+    def line(self) -> str:
+        return f"{self.key}: {self.value}"
+
+
+@dataclass(frozen=True)
+class Config:
+    check: str
+    preflight: str | None
+    require_env: tuple[str, ...]
+    require_up_to_date: str | None
+    default_branch: str
+    trailer: Trailer
+    legacy_keys: tuple[str, ...]
+    cache: bool
+
+
+class ConfigError(Exception):
+    """The config is missing or invalid; `problems` has one line per problem, each naming its key."""
+
+    def __init__(self, problems: list[str]) -> None:
+        super().__init__("\n".join(problems))
+        self.problems = problems
+
+
+def is_trailer_token(text: str) -> bool:
+    return _TRAILER_TOKEN.fullmatch(text) is not None
+
+
+def is_trailer_value(text: str) -> bool:
+    return bool(text) and text == text.strip() and "\n" not in text and "\r" not in text
+
+
+def parse_config(table: Mapping[str, Any]) -> Config:
+    problems: list[str] = []
+
+    def string(key: str, value: Any, *, default: str | None = None) -> str | None:
+        if value is None:
+            return default
+        if not isinstance(value, str):
+            problems.append(f"`{key}` must be a string")
+            return default
+        if not value:
+            problems.append(f"`{key}` must not be empty")
+            return default
+        return value
+
+    def strings(key: str, value: Any) -> tuple[str, ...]:
+        if value is None:
+            return ()
+        if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+            problems.append(f"`{key}` must be a list of strings")
+            return ()
+        return tuple(value)
+
+    problems.extend(
+        f"unknown key `{key}` (known keys: {', '.join(_KEYS)})"
+        for key in table
+        if key not in _KEYS
+    )
+
+    check = string("check", table.get("check"))
+    if "check" not in table:
+        problems.append("`check` is required: the command that runs your full CI check")
+    preflight = string("preflight", table.get("preflight"))
+    default_branch = string(
+        "default_branch", table.get("default_branch"), default=DEFAULT_BRANCH
+    )
+    require_env = strings("require_env", table.get("require_env"))
+    legacy_keys = strings("legacy_keys", table.get("legacy_keys"))
+    problems.extend(
+        f"`legacy_keys` contains {key!r}, which is not a valid trailer key "
+        "(letters, digits and hyphens only)"
+        for key in legacy_keys
+        if not is_trailer_token(key)
+    )
+
+    up_to_date = table.get("require_up_to_date")
+    if up_to_date is None or up_to_date is True:
+        require_up_to_date = f"{REMOTE}/{default_branch}"
+    elif up_to_date is False:
+        require_up_to_date = None
+    elif isinstance(up_to_date, str):
+        require_up_to_date = string("require_up_to_date", up_to_date)
+    else:
+        problems.append("`require_up_to_date` must be a string or a boolean")
+        require_up_to_date = None
+
+    trailer = _parse_trailer(table.get("trailer"), problems)
+
+    cache = table.get("cache", True)
+    if not isinstance(cache, bool):
+        problems.append("`cache` must be a boolean")
+
+    if problems or check is None or default_branch is None:
+        raise ConfigError(problems)
+    return Config(
+        check=check,
+        preflight=preflight,
+        require_env=require_env,
+        require_up_to_date=require_up_to_date,
+        default_branch=default_branch,
+        trailer=trailer,
+        legacy_keys=legacy_keys,
+        cache=bool(cache),
+    )
+
+
+def _parse_trailer(table: Any, problems: list[str]) -> Trailer:
+    default = Trailer(DEFAULT_TRAILER_KEY, DEFAULT_TRAILER_VALUE)
+    if table is None:
+        return default
+    if not isinstance(table, dict):
+        problems.append("`trailer` must be a table with `key` and `value`")
+        return default
+    problems.extend(
+        f"unknown key `trailer.{key}` (known keys: {', '.join(_TRAILER_KEYS)})"
+        for key in table
+        if key not in _TRAILER_KEYS
+    )
+    key = table.get("key", default.key)
+    value = table.get("value", default.value)
+    if not isinstance(key, str):
+        problems.append("`trailer.key` must be a string")
+    elif not is_trailer_token(key):
+        problems.append(
+            f"`trailer.key` is not a valid trailer key: {key!r} "
+            "(letters, digits and hyphens only)"
+        )
+    if not isinstance(value, str):
+        problems.append("`trailer.value` must be a string")
+    elif not is_trailer_value(value):
+        problems.append(
+            f"`trailer.value` must be a non-empty single line without leading or trailing whitespace: {value!r}"
+        )
+    return Trailer(
+        key if isinstance(key, str) else default.key,
+        value if isinstance(value, str) else default.value,
+    )

prepush_ci/core/config_source.py

@@ -0,0 +1,59 @@
+"""Pick the config source in use and parse only that one."""
+
+import tomllib
+from typing import Any
+
+from prepush_ci.core.config import Config, ConfigError, parse_config
+
+PREPUSH_CI_FILE = ".prepush-ci.toml"
+PYPROJECT_FILE = "pyproject.toml"
+PYPROJECT_TABLE = "[tool.prepush-ci]"
+
+_MISSING = (
+    f"no config found: create `{PREPUSH_CI_FILE}` at the repository root "
+    f"or add a `{PYPROJECT_TABLE}` table to `{PYPROJECT_FILE}`"
+)
+
+
+class ConfigMissing(ConfigError):
+    """There is no config at all (as opposed to an invalid one)."""
+
+
+def load_config(prepush_ci_toml: str | None, pyproject_toml: str | None) -> Config:
+    """Parse the config from the text of `.prepush-ci.toml`, else of `pyproject.toml`.
+
+    Each argument is the text of the file, or None when the file does not exist. The
+    dedicated file wins and the other one is not even parsed.
+    """
+    if prepush_ci_toml is not None:
+        return _parse(_parse_toml(prepush_ci_toml, PREPUSH_CI_FILE), PREPUSH_CI_FILE)
+    if pyproject_toml is None:
+        raise ConfigMissing([_MISSING])
+    data = _parse_toml(pyproject_toml, PYPROJECT_FILE)
+    tool = data.get("tool")
+    ours = tool.get("prepush-ci") if isinstance(tool, dict) else None
+    if ours is None:
+        raise ConfigMissing([_MISSING])
+    if not isinstance(ours, dict):
+        raise ConfigError(
+            [
+                f"{PYPROJECT_FILE}: `{PYPROJECT_TABLE}` must be a table, not a single value"
+            ]
+        )
+    return _parse(ours, f"{PYPROJECT_FILE} {PYPROJECT_TABLE}")
+
+
+def _parse_toml(text: str, name: str) -> dict[str, Any]:
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError([f"{name} is not valid TOML: {error}"]) from error
+
+
+def _parse(table: dict[str, Any], source: str) -> Config:
+    try:
+        return parse_config(table)
+    except ConfigError as error:
+        raise ConfigError(
+            [f"{source}: {problem}" for problem in error.problems]
+        ) from error