gate-cache 0.1.0__tar.gz → 0.2.0__tar.gz

{gate_cache-0.1.0 → gate_cache-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gate-cache
-Version: 0.1.0
+Version: 0.2.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>
@@ -127,7 +127,7 @@ A command that exits 0 but changes the tree does not get a record. Examples are
 
 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.
+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. To change that limit, set `GATE_CACHE_MAX_AGE_DAYS`.
 
 ## Marker format
 
@@ -171,7 +171,9 @@ gate-cache has two commands in addition to the default run. Run `gate-cache --he
 
 ### status
 
-`gate-cache status` reports whether a gate would skip on the current tree. It runs nothing.
+`gate-cache status` reports which gates would skip on the current tree. It runs nothing.
+
+With `--name`, it reports on one gate:
 
 ```console
 $ gate-cache status --name pytest
@@ -181,7 +183,19 @@ $ gate-cache status --name pytest
   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.
+The command exits 0 on a hit and 1 otherwise.
+
+Without `--name`, it lists every gate that passed on the current tree:
+
+```console
+$ gate-cache status
+  tree:  aaff74984cccd156a469afa7d9ab10e4777beb24
+  gates: api-lint, pytest
+```
+
+The command exits 0 when at least one gate matches. If no gate matches, it prints `No gates match the current tree` and exits 1. The list reads the JSON content of each marker, so it does not show a marker that another tool wrote without that content. Such a marker still makes its gate skip.
+
+In both forms, if the tree is unknown, the `tree` line gives the reason, such as `unknown: untracked file: notes.txt`, and the command exits 1.
 
 ### clear
 
@@ -192,14 +206,29 @@ $ gate-cache clear
 gate-cache: removed 3 markers
 ```
 
-## Turn off caching
+## Environment variables
 
-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.
+Two environment variables control the cache.
+
+| Variable                  | Effect                                                         | Default |
+| ------------------------- | -------------------------------------------------------------- | ------- |
+| `GATE_CACHE_DISABLE`      | Any value that is not empty and not `0` turns off caching.     | not set |
+| `GATE_CACHE_MAX_AGE_DAYS` | The age in days at which gate-cache deletes a marker.          | `30`    |
+
+With caching off, gate-cache runs every command and never reads or writes markers, and `gate-cache status` exits 1.
 
 ```sh
 GATE_CACHE_DISABLE=1 git push
 ```
 
+The marker directory holds one small file for each gate that passed on each tree. After each new marker, gate-cache deletes every marker older than `GATE_CACHE_MAX_AGE_DAYS`, so the directory holds only the passes from that period. The age counts from when gate-cache wrote the marker. A skip does not reset it, so a marker that a gate hits every day still expires. A smaller value keeps the directory smaller and causes more runs on old trees.
+
+```sh
+export GATE_CACHE_MAX_AGE_DAYS=7
+```
+
+The value must be a positive whole number. If it is not, gate-cache prints a warning and uses 30 days.
+
 ## 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 → gate_cache-0.2.0}/README.md

@@ -91,7 +91,7 @@ A command that exits 0 but changes the tree does not get a record. Examples are
 
 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.
+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. To change that limit, set `GATE_CACHE_MAX_AGE_DAYS`.
 
 ## Marker format
 
@@ -135,7 +135,9 @@ gate-cache has two commands in addition to the default run. Run `gate-cache --he
 
 ### status
 
-`gate-cache status` reports whether a gate would skip on the current tree. It runs nothing.
+`gate-cache status` reports which gates would skip on the current tree. It runs nothing.
+
+With `--name`, it reports on one gate:
 
 ```console
 $ gate-cache status --name pytest
@@ -145,7 +147,19 @@ $ gate-cache status --name pytest
   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.
+The command exits 0 on a hit and 1 otherwise.
+
+Without `--name`, it lists every gate that passed on the current tree:
+
+```console
+$ gate-cache status
+  tree:  aaff74984cccd156a469afa7d9ab10e4777beb24
+  gates: api-lint, pytest
+```
+
+The command exits 0 when at least one gate matches. If no gate matches, it prints `No gates match the current tree` and exits 1. The list reads the JSON content of each marker, so it does not show a marker that another tool wrote without that content. Such a marker still makes its gate skip.
+
+In both forms, if the tree is unknown, the `tree` line gives the reason, such as `unknown: untracked file: notes.txt`, and the command exits 1.
 
 ### clear
 
@@ -156,14 +170,29 @@ $ gate-cache clear
 gate-cache: removed 3 markers
 ```
 
-## Turn off caching
+## Environment variables
 
-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.
+Two environment variables control the cache.
+
+| Variable                  | Effect                                                         | Default |
+| ------------------------- | -------------------------------------------------------------- | ------- |
+| `GATE_CACHE_DISABLE`      | Any value that is not empty and not `0` turns off caching.     | not set |
+| `GATE_CACHE_MAX_AGE_DAYS` | The age in days at which gate-cache deletes a marker.          | `30`    |
+
+With caching off, gate-cache runs every command and never reads or writes markers, and `gate-cache status` exits 1.
 
 ```sh
 GATE_CACHE_DISABLE=1 git push
 ```
 
+The marker directory holds one small file for each gate that passed on each tree. After each new marker, gate-cache deletes every marker older than `GATE_CACHE_MAX_AGE_DAYS`, so the directory holds only the passes from that period. The age counts from when gate-cache wrote the marker. A skip does not reset it, so a marker that a gate hits every day still expires. A smaller value keeps the directory smaller and causes more runs on old trees.
+
+```sh
+export GATE_CACHE_MAX_AGE_DAYS=7
+```
+
+The value must be a positive whole number. If it is not, gate-cache prints a warning and uses 30 days.
+
 ## 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 → gate_cache-0.2.0}/pyproject.toml

@@ -13,7 +13,7 @@ description = "Skip lint and test gates that already passed on the exact same gi
 name = "gate-cache"
 readme = "README.md"
 requires-python = ">=3.11"
-version = "0.1.0"
+version = "0.2.0"
 
 [[project.authors]]
 name = "Nate Landau"

{gate_cache-0.1.0 → gate_cache-0.2.0}/pyproject.toml.orig

@@ -12,7 +12,7 @@
     name = "gate-cache"
     readme = "README.md"
     requires-python = ">=3.11"
-    version = "0.1.0"
+    version = "0.2.0"
 
     [project.scripts]
         gate-cache = "gate_cache.cli:main"

{gate_cache-0.1.0 → gate_cache-0.2.0}/src/gate_cache/__init__.py

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

{gate_cache-0.1.0 → gate_cache-0.2.0}/src/gate_cache/cli.py

@@ -29,10 +29,13 @@ Both --name and -- are required, and only --name may come before --. Everything
 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.
+  status  0 when the named gate, or any gate without --name, passed on 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.
+Set GATE_CACHE_MAX_AGE_DAYS to a positive whole number to change how many days a
+recorded pass lasts (default 30).
 
 Only file content is keyed. Never wrap checks that depend on anything else,
 such as commit-message or branch-name checks.
@@ -48,7 +51,7 @@ app = App(
     help_format="plaintext",
     usage=(
         "Usage: gate-cache --name NAME -- COMMAND [ARGS...]\n"
-        "       gate-cache status --name NAME\n"
+        "       gate-cache status [--name NAME]\n"
         "       gate-cache clear"
     ),
     result_action="return_int_as_exit_code_else_zero",
@@ -86,16 +89,19 @@ def run(
 
 
 @app.command
-def status(*, name: str) -> int:
-    """Report whether the gate would skip, without running anything.
+def status(*, name: str | None = None) -> int:
+    """Report whether gates 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.
+    With --name, print the tree hash (or why it is unknown), the marker path,
+    and hit or miss. Exit 0 on a hit, 1 otherwise.
+
+    Without --name, list every gate that passed on the current tree.
+    Exit 0 when at least one gate matches, 1 otherwise.
 
     Parameters
     ----------
     name
-        Gate name to look up.
+        Gate name to look up. Omit it to list every gate that passed on this tree.
     """
     return gate_status(name)
 

{gate_cache-0.1.0 → gate_cache-0.2.0}/src/gate_cache/gate.py

@@ -8,15 +8,23 @@ 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.markers import (
+    clear_markers,
+    marker_path,
+    passed_names,
+    prune_markers,
+    write_marker,
+)
 from gate_cache.runner import run_child
-from gate_cache.snapshot import git_common_dir, take_snapshot
+from gate_cache.snapshot import Snapshot, git_common_dir, take_snapshot
 
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
     from pathlib import Path
 
 DISABLE_ENV = "GATE_CACHE_DISABLE"
+MAX_AGE_ENV = "GATE_CACHE_MAX_AGE_DAYS"
+DEFAULT_MAX_AGE_DAYS = 30
 _DISABLED_REASON = f"caching disabled by {DISABLE_ENV}"
 _NO_COMMON_DIR_REASON = "could not locate git directory"
 
@@ -34,6 +42,35 @@ def cache_disabled(environ: Mapping[str, str] | None = None) -> bool:
     return value not in {"", "0"}
 
 
+def marker_max_age_days(environ: Mapping[str, str] | None = None) -> int:
+    """Read how many days a marker lives before pruning deletes it.
+
+    An invalid value warns and falls back to the default, so a typo in the setting
+    can never fail a gate.
+
+    Args:
+        environ: Environment to read; defaults to the process environment.
+
+    Returns:
+        The positive whole number of days from GATE_CACHE_MAX_AGE_DAYS, or 30 when it
+        is unset, empty, or invalid.
+    """
+    value = (os.environ if environ is None else environ).get(MAX_AGE_ENV, "").strip()
+    if not value:
+        return DEFAULT_MAX_AGE_DAYS
+    try:
+        days = int(value)
+    except ValueError:
+        days = 0
+    if days < 1:
+        say(
+            f"warning: {MAX_AGE_ENV}={value!r} is not a positive whole number of days, "
+            f"using {DEFAULT_MAX_AGE_DAYS}"
+        )
+        return DEFAULT_MAX_AGE_DAYS
+    return days
+
+
 def _marker_exists(path: Path) -> bool:
     """Return True only when the marker is known to exist."""
     try:
@@ -55,7 +92,7 @@ def _record_pass(path: Path, *, tree: str, name: str, command: Sequence[str]) ->
     except OSError as error:
         say(f"warning: could not record pass: {error}")
         return
-    prune_markers(path.parent)
+    prune_markers(path.parent, max_age_days=marker_max_age_days())
 
 
 def _record_if_unchanged(path: Path, *, tree: str, name: str, command: Sequence[str]) -> None:
@@ -106,20 +143,25 @@ def run_gate(name: str, command: Sequence[str]) -> int:
     return result.exit_code
 
 
-def gate_status(name: str) -> int:
-    """Print whether a gate would skip, without running anything.
+def gate_status(name: str | None = None) -> int:
+    """Print whether a gate would skip, or list every gate that would, without running.
 
     Args:
-        name: Gate name to look up.
+        name: Gate name to look up. When None, list every gate with a recorded pass on
+            the current tree.
 
     Returns:
-        0 when a recorded pass exists for the current tree, 1 otherwise.
+        0 when a recorded pass exists for the gate, or for at least one gate when
+        listing, and 1 otherwise.
     """
     if cache_disabled():
         say(_DISABLED_REASON)
         return 1
 
     snapshot = take_snapshot()
+    if name is None:
+        return _list_passed(snapshot)
+
     tree = snapshot.tree
     path: Path | None = None
     marker = "none"
@@ -143,6 +185,24 @@ def gate_status(name: str) -> int:
     return 0 if hit else 1
 
 
+def _list_passed(snapshot: Snapshot) -> int:
+    """Print the gates with a recorded pass on the snapshot's tree."""
+    if snapshot.tree is None:
+        pp.kv({"tree": f"unknown: {snapshot.reason}"})
+        return 1
+    common_dir = git_common_dir()
+    if common_dir is None:
+        pp.kv({"tree": snapshot.tree, "gates": f"unknown: {_NO_COMMON_DIR_REASON}"})
+        return 1
+    names = passed_names(common_dir, snapshot.tree)
+    if not names:
+        pp.kv({"tree": snapshot.tree})
+        pp.console().print("No gates match the current tree", markup=False, highlight=False)
+        return 1
+    pp.kv({"tree": snapshot.tree, "gates": ", ".join(names)})
+    return 0
+
+
 def clear_cache() -> int:
     """Delete every marker for the current repository.
 

{gate_cache-0.1.0 → gate_cache-0.2.0}/src/gate_cache/markers.py

@@ -96,6 +96,45 @@ def write_marker(path: Path, *, tree: str, name: str, command: Sequence[str]) ->
         raise
 
 
+def passed_names(common_dir: Path, tree: str) -> list[str]:
+    """List the gates with a recorded pass on a tree, for reporting what would skip.
+
+    Marker filenames are one-way hashes, so names come from each marker's JSON content.
+    A file whose content is missing, unreadable, or does not hash to its own filename is
+    left out. Markers written by other tools without that content still count for skips
+    but cannot be listed.
+
+    Args:
+        common_dir: Absolute path to the git common directory.
+        tree: Git tree hash to match.
+
+    Returns:
+        Sorted, unique gate names.
+    """
+    names: set[str] = set()
+    try:
+        entries = list(marker_dir(common_dir).iterdir())
+    except OSError:
+        return []
+    for entry in entries:
+        if entry.name.startswith(TEMP_PREFIX):
+            continue
+        try:
+            data = json.loads(entry.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, ValueError):
+            continue
+        if not isinstance(data, dict):
+            continue
+        name = data.get("name")
+        if (
+            data.get("tree") == tree
+            and isinstance(name, str)
+            and marker_key(tree, name) == entry.name
+        ):
+            names.add(name)
+    return sorted(names)
+
+
 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.