gate-cache 0.1.0__py3-none-any.whl

gate_cache/__init__.py

@@ -0,0 +1,3 @@
+"""Skip lint and test gates that already passed on the exact same git tree."""
+
+__version__ = "0.1.0"

gate_cache/cli.py

@@ -0,0 +1,147 @@
+"""Command line interface for gate-cache."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from gate_cache import __version__
+from gate_cache.console import say
+from gate_cache.gate import clear_cache, gate_status, run_gate
+
+_USAGE_ERROR = 2
+_INTERRUPTED = 130
+_SUBCOMMANDS = {"status", "clear"}
+_INFO_FLAGS = {"-h", "--help", "--version"}
+
+_HELP = """\
+Skip a lint or test command that already passed on the same git tree. gate-cache runs
+the command, records a pass keyed on the git tree of the tracked files (the index, when
+the working copy matches it), and skips the command next time the tree is identical.
+With unstaged changes or untracked files the command runs without caching and nothing
+is recorded.
+
+Both --name and -- are required, and only --name may come before --. Everything after
+-- is the command, verbatim.
+
+Exit codes:
+  run     the command's own exit code, or 0 when a recorded pass lets it skip.
+          Usage errors exit 2.
+  status  0 when a recorded pass exists for the current tree, 1 otherwise.
+  clear   0 on success, 1 on failure.
+
+Set GATE_CACHE_DISABLE to any non-empty value other than 0 to always run the command.
+
+Only file content is keyed. Never wrap checks that depend on anything else,
+such as commit-message or branch-name checks.
+
+Typical use:
+  gate-cache --name pytest -- uv run pytest -x
+"""
+
+app = App(
+    name="gate-cache",
+    version=__version__,
+    help=_HELP,
+    help_format="plaintext",
+    usage=(
+        "Usage: gate-cache --name NAME -- COMMAND [ARGS...]\n"
+        "       gate-cache status --name NAME\n"
+        "       gate-cache clear"
+    ),
+    result_action="return_int_as_exit_code_else_zero",
+)
+
+
+@app.default
+def run(
+    command: Annotated[
+        list[str], Parameter(allow_leading_hyphen=True, negative_iterable="", show_default=False)
+    ],
+    /,
+    *,
+    name: str,
+) -> int:
+    """Run COMMAND unless it already passed on the current git tree.
+
+    On a skip, prints one line to stderr and exits 0 without running anything. Otherwise
+    runs the command and exits with its exit code. The command runs without caching
+    (and nothing is recorded) when GATE_CACHE_DISABLE is set, the tree has unstaged
+    changes or untracked files, or this is not a git repository. A pass is recorded only
+    when the command exits 0 and the run leaves the tree unchanged.
+
+    Parameters
+    ----------
+    command
+        The command and its arguments, given after `--`. Example: -- uv run pytest -x
+    name
+        Gate name. Records match only when the name and the tree both match.
+    """
+    if not command:
+        say("no command given after --")
+        return _USAGE_ERROR
+    return run_gate(name, command)
+
+
+@app.command
+def status(*, name: str) -> int:
+    """Report whether the gate would skip, without running anything.
+
+    Prints the current tree hash (or why it is unknown), the marker path, and hit or
+    miss to stdout. Exits 0 on a hit, 1 otherwise.
+
+    Parameters
+    ----------
+    name
+        Gate name to look up.
+    """
+    return gate_status(name)
+
+
+@app.command
+def clear() -> int:
+    """Delete every recorded pass for this repository.
+
+    Use after something outside git changes, such as a tool upgrade. Exits 1 outside a
+    git repository.
+    """
+    return clear_cache()
+
+
+def _usage_error(tokens: list[str]) -> str | None:
+    """Return the usage problem with a run invocation, or None when it is well formed.
+
+    Only `--name X` or `--name=X` may precede `--`, so a stray option such as `--version`
+    or the first word of the command can never be mistaken for one of ours.
+    """
+    if not tokens or tokens[0] in _SUBCOMMANDS | _INFO_FLAGS:
+        return None
+    index = 0
+    while index < len(tokens):
+        arg = tokens[index]
+        if arg == "--":
+            return None
+        if arg == "--name":
+            if index + 1 == len(tokens) or tokens[index + 1] == "--":
+                return "--name needs a value, e.g. gate-cache --name pytest -- uv run pytest"
+            index += 2
+        elif arg.startswith("--name="):
+            index += 1
+        else:
+            break
+    return "put -- before the command, e.g. gate-cache --name pytest -- uv run pytest"
+
+
+def main() -> None:
+    """Run the gate-cache command line interface and exit with its code."""
+    tokens = sys.argv[1:]
+    if problem := _usage_error(tokens):
+        say(problem)
+        sys.exit(_USAGE_ERROR)
+    try:
+        code = app(tokens)
+    except KeyboardInterrupt:
+        sys.exit(_INTERRUPTED)
+    sys.exit(code)

gate_cache/console.py

@@ -0,0 +1,14 @@
+"""User-facing gate-cache messages."""
+
+from __future__ import annotations
+
+from nclutils import pp
+
+
+def say(message: str) -> None:
+    """Print a gate-cache message to stderr, verbatim.
+
+    Args:
+        message: Text to print after the `gate-cache: ` prefix.
+    """
+    pp.err_console().print(f"gate-cache: {message}", markup=False, highlight=False, soft_wrap=True)

gate_cache/gate.py

@@ -0,0 +1,162 @@
+"""Run a gate command, skipping it when it already passed on the same tree."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from nclutils import pp
+
+from gate_cache.console import say
+from gate_cache.markers import clear_markers, marker_path, prune_markers, write_marker
+from gate_cache.runner import run_child
+from gate_cache.snapshot import git_common_dir, take_snapshot
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+DISABLE_ENV = "GATE_CACHE_DISABLE"
+_DISABLED_REASON = f"caching disabled by {DISABLE_ENV}"
+_NO_COMMON_DIR_REASON = "could not locate git directory"
+
+
+def cache_disabled(environ: Mapping[str, str] | None = None) -> bool:
+    """Report whether GATE_CACHE_DISABLE turns caching off.
+
+    Args:
+        environ: Environment to read; defaults to the process environment.
+
+    Returns:
+        True when the variable is set to any non-empty value other than `0`.
+    """
+    value = (os.environ if environ is None else environ).get(DISABLE_ENV, "")
+    return value not in {"", "0"}
+
+
+def _marker_exists(path: Path) -> bool:
+    """Return True only when the marker is known to exist."""
+    try:
+        return path.exists()
+    except OSError:
+        return False
+
+
+def _run_uncached(reason: str, command: Sequence[str]) -> int:
+    """Explain why caching is off, then run the command."""
+    say(f"{reason}, running without cache")
+    return run_child(command).exit_code
+
+
+def _record_pass(path: Path, *, tree: str, name: str, command: Sequence[str]) -> None:
+    """Write the marker and prune old ones; a failure only warns."""
+    try:
+        write_marker(path, tree=tree, name=name, command=command)
+    except OSError as error:
+        say(f"warning: could not record pass: {error}")
+        return
+    prune_markers(path.parent)
+
+
+def _record_if_unchanged(path: Path, *, tree: str, name: str, command: Sequence[str]) -> None:
+    """Record the pass only when the run left the tree it was keyed on untouched."""
+    # A command that rewrote tracked files or left new files behind did not pass on `tree`.
+    if take_snapshot().tree == tree:
+        _record_pass(path, tree=tree, name=name, command=command)
+    else:
+        say("files changed during the run, not recording pass")
+
+
+def run_gate(name: str, command: Sequence[str]) -> int:
+    """Run a gate command unless it already passed on the tree about to be tested.
+
+    Args:
+        name: Gate name that, with the tree, identifies a recorded pass.
+        command: Command and arguments to run.
+
+    Returns:
+        The command's exit code, or 0 when a recorded pass lets it skip.
+    """
+    if cache_disabled():
+        return _run_uncached(_DISABLED_REASON, command)
+
+    snapshot = take_snapshot()
+    tree = snapshot.tree
+    if tree is None:
+        return _run_uncached(snapshot.reason or "tree unknown", command)
+
+    common_dir = git_common_dir()
+    if common_dir is None:
+        return _run_uncached(_NO_COMMON_DIR_REASON, command)
+
+    path = marker_path(common_dir, tree, name)
+    if _marker_exists(path):
+        say(f"{name} already passed on tree {tree[:12]}, skipping")
+        return 0
+
+    result = run_child(command)
+    if result.interrupted or result.exit_code != 0:
+        return result.exit_code
+
+    # Recording is best effort: nothing after a passing run may change its exit code.
+    try:
+        _record_if_unchanged(path, tree=tree, name=name, command=command)
+    except Exception as error:  # noqa: BLE001
+        say(f"warning: could not record pass: {error}")
+    return result.exit_code
+
+
+def gate_status(name: str) -> int:
+    """Print whether a gate would skip, without running anything.
+
+    Args:
+        name: Gate name to look up.
+
+    Returns:
+        0 when a recorded pass exists for the current tree, 1 otherwise.
+    """
+    if cache_disabled():
+        say(_DISABLED_REASON)
+        return 1
+
+    snapshot = take_snapshot()
+    tree = snapshot.tree
+    path: Path | None = None
+    marker = "none"
+    if tree is not None:
+        common_dir = git_common_dir()
+        if common_dir is None:
+            marker = f"none: {_NO_COMMON_DIR_REASON}"
+        else:
+            path = marker_path(common_dir, tree, name)
+            marker = str(path)
+    hit = path is not None and _marker_exists(path)
+
+    pp.kv(
+        {
+            "name": name,
+            "tree": tree if tree is not None else f"unknown: {snapshot.reason}",
+            "marker": marker,
+            "result": "hit" if hit else "miss",
+        }
+    )
+    return 0 if hit else 1
+
+
+def clear_cache() -> int:
+    """Delete every marker for the current repository.
+
+    Returns:
+        0 on success, 1 outside a git repository or when markers cannot be removed.
+    """
+    common_dir = git_common_dir()
+    if common_dir is None:
+        say("not a git repository")
+        return 1
+    try:
+        count = clear_markers(common_dir)
+    except OSError as error:
+        say(f"could not clear markers: {error}")
+        return 1
+    say(f"removed {count} marker{'' if count == 1 else 's'}")
+    return 0

gate_cache/markers.py

@@ -0,0 +1,154 @@
+"""Marker files that record a gate command passing on a git tree."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from nclutils.utils import iso_timestamp
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+MARKER_DIRNAME = "gate-cache"
+TEMP_PREFIX = ".tmp-"
+
+
+def marker_key(tree: str, name: str) -> str:
+    """Compute the marker key for a tree and gate name.
+
+    The key is the lowercase hex sha256 of tree, a NUL byte, and name. This is a public
+    contract shared with shell consumers; changing it is a breaking change.
+
+    Args:
+        tree: Git tree hash.
+        name: Gate name.
+
+    Returns:
+        The lowercase hex digest.
+    """
+    return hashlib.sha256(f"{tree}\0{name}".encode()).hexdigest()
+
+
+def marker_dir(common_dir: Path) -> Path:
+    """Return the marker directory inside a git common dir.
+
+    Args:
+        common_dir: Absolute path to the git common directory.
+
+    Returns:
+        The directory that holds markers.
+    """
+    return common_dir / MARKER_DIRNAME
+
+
+def marker_path(common_dir: Path, tree: str, name: str) -> Path:
+    """Return the marker file path for a tree and gate name.
+
+    Args:
+        common_dir: Absolute path to the git common directory.
+        tree: Git tree hash.
+        name: Gate name.
+
+    Returns:
+        The path whose existence signals a cached pass.
+    """
+    return marker_dir(common_dir) / marker_key(tree, name)
+
+
+def write_marker(path: Path, *, tree: str, name: str, command: Sequence[str]) -> None:
+    """Atomically write a marker file.
+
+    Args:
+        path: Destination marker path; its parent directory is created if needed.
+        tree: Git tree hash the command passed on.
+        name: Gate name.
+        command: The command that passed.
+
+    Raises:
+        OSError: If the marker cannot be written. Any temp file is removed.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "tree": tree,
+        "name": name,
+        "command": list(command),
+        "timestamp": iso_timestamp(),
+    }
+    tmp_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w", encoding="utf-8", dir=path.parent, prefix=TEMP_PREFIX, delete=False
+        ) as tmp:
+            tmp_name = tmp.name
+            json.dump(payload, tmp)
+        Path(tmp_name).replace(path)
+    except OSError:
+        if tmp_name is not None:
+            with contextlib.suppress(OSError):
+                Path(tmp_name).unlink()
+        raise
+
+
+def prune_markers(directory: Path, *, max_age_days: int = 30, now: float | None = None) -> None:
+    """Delete markers older than the cutoff, ignoring every filesystem error.
+
+    Args:
+        directory: Marker directory to prune.
+        max_age_days: Age in days beyond which a file is deleted.
+        now: Current epoch time; defaults to the system clock.
+    """
+    cutoff = (time.time() if now is None else now) - max_age_days * 86400
+    try:
+        for entry in directory.iterdir():
+            with contextlib.suppress(OSError):
+                if entry.is_file() and not entry.is_symlink() and entry.stat().st_mtime < cutoff:
+                    entry.unlink()
+    except OSError:
+        return
+
+
+def clear_markers(common_dir: Path) -> int:
+    """Delete every marker and the marker directory.
+
+    Files that vanish mid-clear and leftover subdirectories are tolerated, so a concurrent
+    writer cannot make clearing fail.
+
+    Args:
+        common_dir: Absolute path to the git common directory.
+
+    Returns:
+        The number of markers deleted, not counting in-flight temp files; 0 when the
+        directory is missing.
+
+    Raises:
+        OSError: If the marker directory cannot be listed, a file cannot be deleted, or the
+            directory remains afterward.
+    """
+    directory = marker_dir(common_dir)
+    if not directory.is_dir():
+        return 0
+    count = 0
+    for entry in directory.iterdir():
+        if entry.is_dir() and not entry.is_symlink():
+            continue
+        try:
+            entry.unlink()
+        except FileNotFoundError:
+            continue
+        if not entry.name.startswith(TEMP_PREFIX):
+            count += 1
+    try:
+        directory.rmdir()
+    except OSError:
+        shutil.rmtree(directory, ignore_errors=True)
+    if directory.exists():
+        msg = f"could not remove {directory}"
+        raise OSError(msg)
+    return count

gate_cache/runner.py

@@ -0,0 +1,127 @@
+"""Run the wrapped gate command."""
+
+from __future__ import annotations
+
+import contextlib
+import signal
+import subprocess
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from gate_cache.console import say
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Sequence
+    from types import FrameType
+
+_EXIT_NOT_EXECUTABLE = 126
+_EXIT_NOT_FOUND = 127
+_SIGNAL_EXIT_BASE = 128
+_FORWARDED_SIGNALS = (signal.SIGTERM, signal.SIGHUP)
+
+
+@dataclass(frozen=True)
+class ChildResult:
+    """Outcome of the wrapped command.
+
+    Attributes:
+        exit_code: Exit code to propagate, with signal deaths mapped to 128 + signal.
+        interrupted: True when gate-cache received SIGINT, SIGTERM, or SIGHUP while the
+            child ran.
+    """
+
+    exit_code: int
+    interrupted: bool
+
+
+@dataclass
+class _SignalState:
+    """Signals received while the child runs, and the child to forward them to."""
+
+    proc: subprocess.Popen[bytes] | None = None
+    interrupted: bool = False
+    pending: list[int] = field(default_factory=list)
+
+    def handle(self, signum: int, _frame: FrameType | None) -> None:
+        """Record a signal and forward SIGTERM or SIGHUP to the child."""
+        self.interrupted = True
+        if self.proc is None:
+            # A signal during spawn may predate the fork, so the child never saw it.
+            self.pending.append(signum)
+        elif signum != signal.SIGINT:
+            # SIGINT already reaches a running child through the shared process group. A
+            # group-wide TERM or HUP reaches it twice; that beats orphaning it on a direct one.
+            _forward(self.proc, signum)
+
+    def attach(self, proc: subprocess.Popen[bytes]) -> None:
+        """Set the child and forward any signal that arrived while it was starting."""
+        self.proc = proc
+        while self.pending:
+            _forward(proc, self.pending.pop(0))
+
+
+def _forward(proc: subprocess.Popen[bytes], signum: int) -> None:
+    with contextlib.suppress(OSError):
+        proc.send_signal(signum)
+
+
+@contextlib.contextmanager
+def _trap_signals(state: _SignalState) -> Generator[None]:
+    """Route SIGINT, SIGTERM, and SIGHUP to state, restoring the previous handlers after.
+
+    Python handlers reset to the default on exec, so the child keeps normal signal
+    behavior. Ignored signals stay ignored so the child inherits that disposition, as
+    under `nohup` or a background job. Handlers can only be set from the main thread;
+    elsewhere signals keep their current disposition.
+    """
+    if threading.current_thread() is not threading.main_thread():
+        yield
+        return
+    previous = {
+        signum: signal.signal(signum, state.handle)
+        for signum in (signal.SIGINT, *_FORWARDED_SIGNALS)
+        if signal.getsignal(signum) is not signal.SIG_IGN
+    }
+    try:
+        yield
+    finally:
+        for signum, handler in previous.items():
+            # None means a handler installed outside Python, which cannot be reinstated.
+            if handler is not None:
+                signal.signal(signum, handler)
+
+
+def run_child(argv: Sequence[str]) -> ChildResult:
+    """Run a command with inherited streams and environment, and wait for it.
+
+    The child shares our process group, so Ctrl-C reaches it directly; SIGTERM and SIGHUP
+    sent to gate-cache are forwarded to it. Either way gate-cache keeps waiting and
+    reports the child's status instead of abandoning it.
+
+    Args:
+        argv: Command and arguments to execute.
+
+    Returns:
+        The exit code (127 if not found, 126 if it cannot be executed) and whether a
+        signal arrived while the child ran.
+    """
+    state = _SignalState()
+    with _trap_signals(state):
+        try:
+            proc = subprocess.Popen(list(argv))  # noqa: S603
+        except FileNotFoundError:
+            say(f"command not found: {argv[0]}")
+            return ChildResult(_EXIT_NOT_FOUND, interrupted=state.interrupted)
+        except PermissionError:
+            say(f"permission denied: {argv[0]}")
+            return ChildResult(_EXIT_NOT_EXECUTABLE, interrupted=state.interrupted)
+        except OSError as error:
+            say(f"could not run {argv[0]}: {error}")
+            return ChildResult(_EXIT_NOT_EXECUTABLE, interrupted=state.interrupted)
+        state.attach(proc)
+        code = proc.wait()
+
+    if code < 0:
+        code = _SIGNAL_EXIT_BASE - code
+    return ChildResult(code, interrupted=state.interrupted)

gate_cache/snapshot.py

@@ -0,0 +1,110 @@
+"""Detect the git tree that a gate command is about to test."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from nclutils.git import run_git
+from nclutils.sh import ShellCommandError, ShellCommandNotFoundError
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """The tree a gate is about to test, or why that tree is unknown.
+
+    Attributes:
+        tree: Git tree hash describing the content under test, or None when unknown.
+        reason: Why the tree is unknown, or None when it is known.
+    """
+
+    tree: str | None
+    reason: str | None
+
+    @property
+    def known(self) -> bool:
+        """Return True when a tree hash identifies the content under test."""
+        return self.tree is not None
+
+
+def _work_tree_root(cwd: Path | None) -> Path | None:
+    """Return the absolute top of the work tree, or None when there is none."""
+    result = run_git("rev-parse", "--show-toplevel", cwd=cwd, check=False)
+    output = result.stdout.strip()
+    if result.returncode != 0 or not output or "\n" in output:
+        return None
+    return Path(output)
+
+
+def _unknown_reason(cwd: Path | None) -> str | None:
+    """Return why the working copy cannot be described by one tree, or None if it can."""
+    if run_git("rev-parse", "--git-dir", cwd=cwd, check=False).returncode != 0:
+        return "not a git repository"
+    # ls-files only lists paths under its cwd. Probing from the top avoids the `:/` pathspec,
+    # which GIT_LITERAL_PATHSPECS turns into a literal path that matches nothing.
+    root = _work_tree_root(cwd)
+    if root is None:
+        return "could not locate work tree"
+    if run_git("ls-files", "--unmerged", cwd=root).stdout:
+        return "unmerged index"
+    if run_git("diff", "--quiet", cwd=root, okay_codes=(0, 1)).returncode != 0:
+        return "unstaged changes to tracked files"
+    untracked = run_git("ls-files", "--others", "--exclude-standard", "-z", cwd=root).stdout
+    if untracked:
+        return f"untracked file: {untracked.split(chr(0))[0]}"
+    return None
+
+
+def take_snapshot(cwd: Path | None = None) -> Snapshot:
+    """Identify the tree a gate command is about to test.
+
+    The snapshot is known only when the working copy matches the index for tracked files and
+    no untracked, non-ignored files exist. Every other situation, including any git failure,
+    resolves to unknown so the caller runs the command uncached.
+
+    Args:
+        cwd: Directory to run git in. Defaults to the process working directory.
+
+    Returns:
+        A Snapshot holding the tree hash, or the reason it is unknown.
+    """
+    try:
+        reason = _unknown_reason(cwd)
+    except ShellCommandNotFoundError:
+        return Snapshot(tree=None, reason="git not found")
+    except (ShellCommandError, UnicodeDecodeError):
+        return Snapshot(tree=None, reason="could not inspect git state")
+    if reason:
+        return Snapshot(tree=None, reason=reason)
+
+    try:
+        tree = run_git("write-tree", cwd=cwd).stdout
+    except (ShellCommandError, UnicodeDecodeError):
+        return Snapshot(tree=None, reason="could not compute tree")
+    return Snapshot(tree=tree, reason=None)
+
+
+def git_common_dir(cwd: Path | None = None) -> Path | None:
+    """Return the absolute git common directory shared by all linked worktrees.
+
+    Args:
+        cwd: Directory to run git in. Defaults to the process working directory.
+
+    Returns:
+        The absolute path, or None when git fails or its output is not a single path.
+    """
+    try:
+        result = run_git("rev-parse", "--git-common-dir", cwd=cwd)
+    except (ShellCommandError, UnicodeDecodeError):
+        return None
+    output = result.stdout.strip()
+    if not output or "\n" in output:
+        return None
+    path = Path(output)
+    if path.is_absolute():
+        return path
+    try:
+        base = Path(cwd) if cwd is not None else Path.cwd()
+        return (base / path).resolve()
+    except (OSError, RuntimeError):
+        return None

gate_cache-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.3
+Name: gate-cache
+Version: 0.1.0
+Summary: Skip lint and test gates that already passed on the exact same git tree.
+Author: Nate Landau
+Author-email: Nate Landau <github@natenate.org>
+License: MIT License
+         
+         Copyright (c) 2026 Nate Landau
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: cyclopts>=5.2.0,<6.0.0
+Requires-Dist: nclutils>=3.4.4,<4.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# gate-cache
+
+Skip lint and test gates that already passed on the exact same git tree.
+
+The same code often goes through the same gates many times before it ships: at the end of local work, in a pre-commit hook, again after a rebase that changed nothing, and again in a pre-push hook. When a test suite takes minutes, this repetition is the slowest part of the cycle.
+
+gate-cache wraps one gate command. When the command passes, gate-cache records the pass against the git tree of the tracked files. If you run the same named gate on the same tree again, gate-cache exits 0 in milliseconds and does not run the command. CI starts from a fresh clone with no records, so CI still runs every gate.
+
+```console
+$ gate-cache --name pytest -- uv run pytest
+... pytest output ...
+$ gate-cache --name pytest -- uv run pytest
+gate-cache: pytest already passed on tree aaff74984ccc, skipping
+```
+
+## Install
+
+gate-cache requires Python 3.11 or later.
+
+To install the command line tool, run:
+
+```sh
+uv tool install gate-cache
+```
+
+You do not need to install anything to use gate-cache as a hook. [prek](https://github.com/j178/prek) and [pre-commit](https://pre-commit.com) 3.2 or later install it from the hook repository.
+
+## Use it as a hook
+
+Add one `gate-cache` entry for each gate that you want to cache. Each entry gives the gate a name with `--name` and puts the command after `--`:
+
+```yaml
+repos:
+  - repo: https://github.com/natelandau/gate-cache
+    rev: v0.1.0
+    hooks:
+      - id: gate-cache
+        name: pytest
+        alias: pytest
+        args: [--name, pytest, --, uv, run, pytest]
+        files: ^(src/|tests/|uv\.lock|pyproject\.toml)
+      - id: gate-cache
+        name: ruff
+        alias: ruff
+        args: [--name, ruff, --, uv, run, ruff, check, .]
+```
+
+The hook sets `pass_filenames: false`, so the runner does not append file names to the wrapped command. The `files` and `always_run` keys are your choice. The hook runs in the `pre-commit`, `pre-push`, and `manual` stages.
+
+The wrapped command runs in the environment of the hook. prek and pre-commit install gate-cache in its own virtual environment, so the command sees `VIRTUAL_ENV` set to that environment, and the `bin` directory of that environment comes first on `PATH`. gate-cache does not change this environment. Thus:
+
+- Start the command with `uv run`, or give an absolute path or a command that your project supplies. Do not use a bare tool name such as `pytest`, because it can find the copy in the hook environment, or find nothing.
+- `uv run` prints `VIRTUAL_ENV=... does not match the project environment path .venv and will be ignored`. This warning is harmless: `uv run` uses the project environment.
+
+Agents, scripts, and people can call the same command directly. A pass that one caller records is a hit for every other caller:
+
+```sh
+gate-cache --name pytest -- uv run pytest
+```
+
+Both `--name` and `--` are required, and only `--name` can come before `--`. gate-cache passes everything after `--` to the command without changes. A missing `--name` or `--`, or any other argument before `--`, is a usage error: gate-cache runs nothing and exits 2. Otherwise gate-cache exits with the exit code of the command, or 0 on a skip. If a signal stops the command, gate-cache exits with 128 plus the signal number.
+
+## Never wrap these
+
+gate-cache keys a pass only on the content of tracked files. Never wrap a command whose result depends on anything else. A wrapped check of that kind can be skipped when a fresh run fails.
+
+Keep these as normal, unwrapped hooks:
+
+- Commit message checks, such as the commitizen `commit-msg` hook.
+- Branch name checks.
+- Any command that talks to a remote.
+- Secret scanners and other hooks that must always run, such as gitleaks.
+
+gate-cache decides only about the command that it wraps. It never skips other hooks.
+
+## How a cache hit is decided
+
+Each time it runs, gate-cache does these steps in this sequence:
+
+1. If `GATE_CACHE_DISABLE` turns caching off, run the command and record nothing.
+2. Find the tree to key on. The tree is `git write-tree`, which is the content of the index. gate-cache uses it only if the tracked files in the working copy match the index and no untracked, non-ignored files exist.
+3. If the tree is unknown, run the command without the cache and record nothing. The tree is unknown with unstaged changes, untracked non-ignored files, an unmerged index, outside a git repository, or after any git error.
+4. If git cannot find the git directory that holds the markers, run the command without the cache and record nothing.
+5. If a marker for the tree and name exists, print a skip line and exit 0.
+6. Run the command.
+7. If the command exits 0 and the tree is still the same, write the marker.
+
+At commit time, prek and pre-commit stash unstaged edits, so the key is the staged content that you commit. At push time with a clean checkout, the key is the tree of `HEAD`.
+
+A command that exits 0 but changes the tree does not get a record. Examples are a formatter that rewrites files and a command that leaves new untracked files. gate-cache prints `files changed during the run, not recording pass` in this case.
+
+A failing command, a signal, or Ctrl-C never writes a marker. If gate-cache gets `SIGTERM` or `SIGHUP` while the command runs, it sends the signal to the command, waits for the command to stop, and exits with the status of the command. A cache error never changes the exit code of the command. If gate-cache cannot write a marker, it prints a warning and keeps the exit code.
+
+Markers live in the git common directory, so all linked worktrees of a repository share them. After each new marker, gate-cache deletes markers older than 30 days.
+
+## Marker format
+
+Other tools can read and write markers without calling gate-cache. The marker format is a public contract, and any change to it is a breaking change.
+
+The key is the lowercase hex SHA-256 of the tree hash, a NUL byte, and the gate name:
+
+```text
+key    = sha256( tree_hash + "\0" + name )
+marker = $(git rev-parse --git-common-dir)/gate-cache/<key>
+```
+
+To find the marker for the `pytest` gate from a shell, run:
+
+```bash
+tree=$(git write-tree)
+key=$(printf '%s\0%s' "$tree" pytest | shasum -a 256 | cut -d' ' -f1)
+marker="$(git rev-parse --git-common-dir)/gate-cache/$key"
+```
+
+On Linux systems without `shasum`, use `sha256sum` instead.
+
+The existence of the marker file is the signal. The file holds a small JSON object with `tree`, `name`, `command`, and `timestamp` keys for debugging. Do not depend on its content.
+
+## Blind spots
+
+The key covers only the content and the modes of tracked files. It does not cover:
+
+- Ignored inputs, such as `.env` and `.venv`.
+- Environment variables.
+- Tool versions that a lockfile does not pin.
+- External services.
+- Changes that git is told to ignore. `core.fileMode=false` hides changes to the executable bit. `git update-index --assume-unchanged` and `--skip-worktree` hide edits to tracked files.
+- Changes in submodules that git is told to ignore. `diff.ignoreSubmodules` and the `submodule.<name>.ignore` setting can hide a dirty submodule, so a run with uncommitted submodule edits can record a pass for the tree of the parent repository.
+
+If a gate depends on one of these, gate-cache can skip it when a fresh run fails. CI still runs every gate from a fresh clone. After a change outside git, such as a tool upgrade, run `gate-cache clear`. To run gates without the cache, set `GATE_CACHE_DISABLE=1`.
+
+## Commands
+
+gate-cache has two commands in addition to the default run. Run `gate-cache --help` for the full reference.
+
+### status
+
+`gate-cache status` reports whether a gate would skip on the current tree. It runs nothing.
+
+```console
+$ gate-cache status --name pytest
+  name:   pytest
+  tree:   aaff74984cccd156a469afa7d9ab10e4777beb24
+  marker: /path/to/repo/.git/gate-cache/698af5f62774dab7babf59a4b8969fed12d8668428cee49ca89baf4aa392de6d
+  result: hit
+```
+
+If the tree is unknown, the `tree` line gives the reason, such as `unknown: untracked file: notes.txt`. The command exits 0 on a hit and 1 otherwise.
+
+### clear
+
+`gate-cache clear` deletes every marker for the current repository, in all of its worktrees. Use it after a change that git cannot see, such as a tool upgrade. Outside a git repository, it exits 1.
+
+```console
+$ gate-cache clear
+gate-cache: removed 3 markers
+```
+
+## Turn off caching
+
+If `GATE_CACHE_DISABLE` has a value that is not empty and not `0`, gate-cache runs every command and never reads or writes markers. With caching off, `gate-cache status` exits 1.
+
+```sh
+GATE_CACHE_DISABLE=1 git push
+```
+
+## Supported runners and platforms
+
+gate-cache works with prek and with pre-commit 3.2 or later. It runs on macOS and Linux. Windows is not supported.

gate_cache-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gate_cache/__init__.py,sha256=eGz5PZOmseZDtmcQqgxUajZMGqbRXk15YHEU_pWvvLM,102
+gate_cache/cli.py,sha256=jSePrbgeYBuSp16g9eKl1d0NezXS57iPqqFBe24czKk,4597
+gate_cache/console.py,sha256=8rjGYBWiXMeuZ9A0v8Ot0JKrQt2_std5Qb8AmJjd_WY,371
+gate_cache/gate.py,sha256=Od-qNwGyvAWi1js5_r_TaHsBo4luJPg8ulunsRZRjG4,5091
+gate_cache/markers.py,sha256=xYRvuXO1q0RZ3GhayPWoszWaSkz6iiHBJ4wZvjYUrG0,4510
+gate_cache/runner.py,sha256=LRNAOWBG-7doKih-r9hUbfilbcl7_nqjInvHATypFhI,4475
+gate_cache/snapshot.py,sha256=3HFijtH63T8C0zr-ZXN_4l47oqrY5LMIKe364xARSv8,3988
+gate_cache-0.1.0.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+gate_cache-0.1.0.dist-info/entry_points.txt,sha256=6w3QTtXIFBOvsGxS73hecc0ZO61aGFASNnQdvooGR28,52
+gate_cache-0.1.0.dist-info/METADATA,sha256=P2TIxoz6eB7BW5ifETLxYnaIG1YlJvEI7q0v65iJWgg,10574
+gate_cache-0.1.0.dist-info/RECORD,,

gate_cache-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gate_cache-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gate-cache = gate_cache.cli:main
+