git-a-grip 0.4.0__py3-none-any.whl

git_a_grip/__init__.py

@@ -0,0 +1 @@
+"""Personal pre-commit hooks."""

git_a_grip/audit.py

@@ -0,0 +1,288 @@
+"""Inventory the pre-commit configs of every repo under a directory tree.
+
+Answers the question a single `.pre-commit-config.yaml` cannot: across all
+the repos on this machine, which of *this* repo's hooks are actually in use
+and at what rev, what other third-party hooks have accumulated, and which
+`repo: local` hooks exist only in one project and nowhere else.
+
+    pre-commit-audit                 audit the sibling repos of this one
+    pre-commit-audit ~/projects ~/wk audit those trees instead
+    pre-commit-audit --json          the same data, machine-readable
+
+Repos with no config at all are listed too -- an unhooked repo is a finding,
+not an absence of one.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_NAME = '.pre-commit-config.yaml'
+SELF_MARKER = 'git-a-grip'
+# Directories that never contain a repo we care about but do contain
+# thousands of files, including vendored copies of other repos' configs.
+_PRUNED = {
+    '.git',
+    '.venv',
+    'node_modules',
+    '__pycache__',
+    '.tox',
+    '.mypy_cache',
+}
+
+USAGE = """\
+pre-commit-audit -- audit the pre-commit hooks of every local repo.
+
+  pre-commit-audit [PATH ...]  trees to scan (default: this repo's parent)
+  pre-commit-audit --json      emit JSON instead of a report
+  pre-commit-audit --help      show this
+"""
+
+
+@dataclass
+class HookUse:
+    """One hook id, as used by one repo, from one source repo at one rev."""
+
+    repo: str
+    rev: str
+    hook_id: str
+    entry: str = ''
+
+
+@dataclass
+class RepoAudit:
+    """Everything one local repo declares."""
+
+    path: Path
+    has_config: bool = True
+    error: str = ''
+    uses: list[HookUse] = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        """The repo's directory name."""
+        return self.path.name
+
+
+def find_repos(roots: list[Path]) -> list[Path]:
+    """Return every git working tree under `roots`, not recursing into one."""
+    found: list[Path] = []
+    stack = [r.resolve() for r in roots]
+    while stack:
+        current = stack.pop()
+        if not current.is_dir() or current.name in _PRUNED:
+            continue
+        if (current / '.git').exists():
+            found.append(current)
+            continue  # a repo's subdirectories are part of that repo
+        stack.extend(child for child in current.iterdir() if child.is_dir())
+    return sorted(found)
+
+
+def _hook_uses(config: dict[str, Any]) -> list[HookUse]:
+    uses = []
+    for entry in config.get('repos') or []:
+        if not isinstance(entry, dict):
+            continue
+        source = str(entry.get('repo', '?'))
+        rev = str(entry.get('rev', '')) if entry.get('rev') else ''
+        for hook in entry.get('hooks') or []:
+            if not isinstance(hook, dict):
+                continue
+            uses.append(
+                HookUse(
+                    repo=source,
+                    rev=rev,
+                    hook_id=str(hook.get('id', '?')),
+                    entry=str(hook.get('entry', '')),
+                ),
+            )
+    return uses
+
+
+def audit_repo(path: Path) -> RepoAudit:
+    """Read one repo's pre-commit config, tolerating a broken or absent one."""
+    config_path = path / CONFIG_NAME
+    if not config_path.is_file():
+        return RepoAudit(path=path, has_config=False)
+    try:
+        loaded = yaml.safe_load(config_path.read_text(encoding='utf-8'))
+    except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+        return RepoAudit(path=path, error=str(exc).splitlines()[0])
+    if not isinstance(loaded, dict):
+        return RepoAudit(path=path, error='config is not a mapping')
+    return RepoAudit(path=path, uses=_hook_uses(loaded))
+
+
+def is_self(use: HookUse) -> bool:
+    """Whether this use comes from this project's hooks."""
+    return SELF_MARKER in use.repo
+
+
+def is_local(use: HookUse) -> bool:
+    """Whether this use is a `repo: local` (or `meta`) hook."""
+    return use.repo in {'local', 'meta'}
+
+
+def _group(
+    audits: list[RepoAudit],
+    predicate: Any,  # noqa: ANN401 -- Callable[[HookUse], bool]
+) -> dict[str, list[tuple[RepoAudit, HookUse]]]:
+    grouped: dict[str, list[tuple[RepoAudit, HookUse]]] = defaultdict(list)
+    for audit in audits:
+        for use in audit.uses:
+            if predicate(use):
+                grouped[use.hook_id].append((audit, use))
+    return dict(sorted(grouped.items()))
+
+
+def _section(title: str, lines: list[str]) -> list[str]:
+    return [title, '=' * len(title), *(lines or ['  (none)']), '']
+
+
+def _self_section(audits: list[RepoAudit]) -> list[str]:
+    lines = []
+    for hook_id, pairs in _group(audits, is_self).items():
+        lines.append(f'  {hook_id}')
+        for audit, use in sorted(pairs, key=lambda p: p[0].name):
+            rev = use.rev or 'unpinned'
+            lines.append(f'    {audit.name:<28} {rev}')
+    return _section(f'{SELF_MARKER} hooks in use', lines)
+
+
+def _third_party_section(audits: list[RepoAudit]) -> list[str]:
+    by_source: dict[str, dict[str, set[str]]] = defaultdict(
+        lambda: defaultdict(set),
+    )
+    for audit in audits:
+        for use in audit.uses:
+            if is_self(use) or is_local(use):
+                continue
+            label = f'{use.hook_id} @ {use.rev or "unpinned"}'
+            by_source[use.repo][label].add(audit.name)
+    lines = []
+    for source, hooks in sorted(by_source.items()):
+        lines.append(f'  {source}')
+        for label, users in sorted(hooks.items()):
+            lines.append(f'    {label:<40} {", ".join(sorted(users))}')
+    return _section('Third-party hooks', lines)
+
+
+def _local_section(audits: list[RepoAudit]) -> list[str]:
+    lines = []
+    for audit in audits:
+        local = [use for use in audit.uses if is_local(use)]
+        if not local:
+            continue
+        lines.append(f'  {audit.name}')
+        for use in local:
+            entry = use.entry or '(no entry)'
+            lines.append(f'    {use.hook_id:<24} {entry}')
+    return _section('Local hooks (defined in one repo only)', lines)
+
+
+def _gaps_section(audits: list[RepoAudit]) -> list[str]:
+    lines = [
+        f'  {audit.name:<28} {audit.error or "no " + CONFIG_NAME}'
+        for audit in audits
+        if not audit.has_config or audit.error
+    ]
+    return _section('Repos with no usable config', lines)
+
+
+def render(audits: list[RepoAudit]) -> str:
+    """Render the whole audit as a plain-text report."""
+    hooked = sum(1 for a in audits if a.uses)
+    header = [
+        f'{len(audits)} repos scanned, {hooked} with pre-commit hooks.',
+        '',
+    ]
+    return '\n'.join(
+        [
+            *header,
+            *_self_section(audits),
+            *_third_party_section(audits),
+            *_local_section(audits),
+            *_gaps_section(audits),
+        ],
+    )
+
+
+def as_json(audits: list[RepoAudit]) -> str:
+    """Render the whole audit as JSON."""
+    return json.dumps(
+        [
+            {
+                'path': str(a.path),
+                'name': a.name,
+                'has_config': a.has_config,
+                'error': a.error,
+                'hooks': [
+                    {
+                        'repo': u.repo,
+                        'rev': u.rev,
+                        'id': u.hook_id,
+                        'entry': u.entry,
+                        'source': (
+                            'self'
+                            if is_self(u)
+                            else 'local'
+                            if is_local(u)
+                            else 'third-party'
+                        ),
+                    }
+                    for u in a.uses
+                ],
+            }
+            for a in audits
+        ],
+        indent=2,
+    )
+
+
+def default_roots() -> list[Path]:
+    """The directory holding this repo -- i.e. its sibling projects."""
+    top = subprocess.run(
+        ['git', 'rev-parse', '--show-toplevel'],  # noqa: S607
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.strip()
+    return [Path(top).parent if top else Path.cwd()]
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Scan, report, and return 0 unless the arguments make no sense."""
+    args = sys.argv[1:] if argv is None else argv
+    if '--help' in args or '-h' in args:
+        sys.stdout.write(USAGE)
+        return 0
+    want_json = '--json' in args
+    paths = [Path(a) for a in args if not a.startswith('-')]
+    missing = [p for p in paths if not p.is_dir()]
+    if missing:
+        sys.stderr.write(
+            f'audit: not a directory: {", ".join(str(p) for p in missing)}\n',
+        )
+        return 2
+
+    audits = [audit_repo(p) for p in find_repos(paths or default_roots())]
+    sys.stdout.write((as_json if want_json else render)(audits) + '\n')
+    return 0
+
+
+def main_cli() -> None:
+    """Console-script entry point."""
+    raise SystemExit(main())
+
+
+if __name__ == '__main__':
+    main_cli()

git_a_grip/commitizen_early.py

@@ -0,0 +1,153 @@
+"""Validate the commit message during the *pre-commit* stage, not commit-msg.
+
+Git runs hooks in the order pre-commit -> prepare-commit-msg -> editor ->
+commit-msg, so a `stages: [commit-msg]` commitizen hook can only ever reject
+a bad message *after* the slow pre-commit hooks (tests, ruff, ...) have run.
+No amount of hook ordering or `fail_fast` in .pre-commit-config.yaml changes
+that -- the stages are separate git invocations.
+
+When the message came from `git commit -m ...` (or `-F file`) it is already
+sitting in git's argv while pre-commit runs, so we can fish it out of the
+process tree and hand it to `cz check` immediately. Bad message => fail in
+about a second instead of after the full suite.
+
+If no message can be recovered (interactive editor, merge, rebase, ...) this
+exits 0 and the real commit-msg hook does the checking as before.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from git_a_grip import cz
+
+MAX_PARENT_DEPTH = 12
+_SHORT_FLAG_MIN_LEN = 2
+
+
+def _cmdline(pid: int) -> list[str] | None:
+    try:
+        raw = Path(f'/proc/{pid}/cmdline').read_bytes()
+    except OSError:
+        return None
+    return [a for a in raw.decode('utf-8', 'replace').split('\0') if a]
+
+
+def _ppid(pid: int) -> int | None:
+    try:
+        stat = Path(f'/proc/{pid}/stat').read_text()
+    except OSError:
+        return None
+    # comm can contain spaces/parens, so parse after the final ')'.
+    try:
+        return int(stat[stat.rindex(')') + 1 :].split()[1])
+    except (ValueError, IndexError):
+        return None
+
+
+def find_git_commit_argv() -> list[str] | None:
+    """Walk up process tree looking for the `git commit` that invoked us."""
+    pid: int | None = os.getppid()
+    for _ in range(MAX_PARENT_DEPTH):
+        if pid is None or pid <= 1:
+            return None
+        argv = _cmdline(pid)
+        if (
+            argv
+            and Path(argv[0]).name in {'git', 'git.exe'}
+            and 'commit' in argv
+        ):
+            return argv
+        pid = _ppid(pid)
+    return None
+
+
+def _parse_flag_value(
+    arg: str,
+    args: list[str],
+    i: int,
+) -> tuple[str | None, bool, int]:
+    """Parse a flag/value pair. Returns (value, is_file, next_index)."""
+    value: str | None = None
+    is_file = False
+    if arg in {'-m', '--message'}:
+        value = args[i + 1] if i + 1 < len(args) else None
+        i += 1
+    elif arg.startswith('--message='):
+        value = arg.split('=', 1)[1]
+    elif (
+        arg.startswith('-m')
+        and len(arg) > _SHORT_FLAG_MIN_LEN
+        and not arg.startswith('--')
+    ):
+        value = arg[2:]
+    elif arg in {'-F', '--file'}:
+        value = args[i + 1] if i + 1 < len(args) else None
+        is_file = True
+        i += 1
+    elif arg.startswith('--file='):
+        value, is_file = arg.split('=', 1)[1], True
+    elif (
+        arg.startswith('-') and not arg.startswith('--') and arg.endswith('m')
+    ):
+        # Clustered short flags, e.g. `git commit -am "msg"`.
+        value = args[i + 1] if i + 1 < len(args) else None
+        i += 1
+    return value, is_file, i
+
+
+def message_from_argv(argv: list[str]) -> str | None:
+    """Extract the -m/-F message from a `git commit` argv, if there is one."""
+    args = argv[argv.index('commit') + 1 :]
+    parts: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == '--':
+            break
+        if arg in {'-e', '--edit'}:
+            # Message will be edited after we run; let commit-msg judge it.
+            return None
+        value, is_file, i = _parse_flag_value(arg, args, i)
+        if value is not None:
+            if is_file:
+                if value == '-':
+                    return None
+                try:
+                    value = Path(value).read_text()
+                except OSError:
+                    return None
+            parts.append(value)
+        i += 1
+    return '\n\n'.join(parts) if parts else None
+
+
+def main() -> int:
+    """Check a recoverable commit message, or defer to the commit-msg hook."""
+    argv = find_git_commit_argv()
+    if argv is None:
+        return 0
+    message = message_from_argv(argv)
+    if message is None:
+        return 0
+    result = cz.run('check', '--message', message)
+    if result.returncode == 0:
+        return 0
+    sys.stdout.write(result.stdout)
+    sys.stderr.write(result.stderr)
+    sys.stderr.write(
+        '\nRejected before running the slow hooks. '
+        'Fix the message and re-commit.\n',
+    )
+    return 1
+
+
+def main_cli() -> None:
+    """Console-script entry point."""
+    raise SystemExit(main())
+
+
+if __name__ == '__main__':
+    main_cli()

git_a_grip/cz.py

@@ -0,0 +1,23 @@
+"""Run commitizen out of this hook's own interpreter.
+
+pre-commit installs this package into an isolated env with commitizen as a
+declared dependency, so `sys.executable -m commitizen` always resolves. That
+deliberately replaces per-repo invocations like `uv run cz` or
+`uvx --from commitizen cz`, which differ by consumer and are the thing most
+likely to break when a hook is copied between projects.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def run(*args: str) -> subprocess.CompletedProcess[str]:
+    """Invoke commitizen with `args`, capturing output."""
+    return subprocess.run(  # noqa: S603
+        [sys.executable, '-m', 'commitizen', *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )

git_a_grip/pytest_hook.py

@@ -0,0 +1,92 @@
+"""Run the consuming repo's test suite as a hook, from the repo root.
+
+Unlike the other hooks here, this one deliberately does *not* run inside the
+env pre-commit built for this package: a test suite needs the consuming
+project's own dependencies, which that isolated env will never have. So it
+shells out to a runner that resolves the project's environment -- `uv run
+pytest` by default -- and everything after the runner flags is handed
+straight to pytest:
+
+    - id: pytest
+      args: [tests/, -q]
+
+    - id: pytest
+      args: ['--runner=uv run --extra api pytest', tests/, -q]
+
+Two details that a hand-rolled `entry:` usually gets wrong: it runs from the
+repo root rather than wherever git was invoked, and it drops the VIRTUAL_ENV
+that pre-commit exports for its own hook env, which would otherwise point the
+runner at an environment holding none of the project's dependencies.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+DEFAULT_RUNNER = 'uv run pytest'
+_RUNNER_FLAG = '--runner='
+# pre-commit exports these for the isolated env it built for *this* package.
+# Leaking them into the runner would shadow the project's own environment.
+_INHERITED_ENV_VARS = ('VIRTUAL_ENV', 'PYTHONHOME', 'PYTHONPATH')
+
+
+def split_args(argv: list[str]) -> tuple[list[str], list[str]]:
+    """Split argv into the runner command and the arguments for pytest."""
+    runner = DEFAULT_RUNNER
+    rest: list[str] = []
+    for arg in argv:
+        if arg.startswith(_RUNNER_FLAG):
+            runner = arg[len(_RUNNER_FLAG) :]
+        else:
+            rest.append(arg)
+    return runner.split(), rest
+
+
+def repo_root() -> str:
+    """Return the top level of the working tree."""
+    return subprocess.run(
+        ['git', 'rev-parse', '--show-toplevel'],  # noqa: S607
+        capture_output=True,
+        text=True,
+        check=False,
+    ).stdout.strip()
+
+
+def clean_env() -> dict[str, str]:
+    """Return the environment minus pre-commit's own venv pointers."""
+    env = dict(os.environ)
+    for name in _INHERITED_ENV_VARS:
+        env.pop(name, None)
+    return env
+
+
+def main(argv: list[str]) -> int:
+    """Run the project's test suite, returning the runner's exit code."""
+    runner, pytest_args = split_args(argv)
+    if not runner:
+        sys.stderr.write('pytest: --runner is empty, nothing to run.\n')
+        return 1
+    try:
+        return subprocess.run(  # noqa: S603
+            [*runner, *pytest_args],
+            cwd=repo_root() or None,
+            env=clean_env(),
+            check=False,
+        ).returncode
+    except FileNotFoundError:
+        sys.stderr.write(
+            f'pytest: cannot run {runner[0]!r} -- it is not on PATH. '
+            f'Install it, or set args: ["--runner=<command>", ...].\n',
+        )
+        return 1
+
+
+def main_cli() -> None:
+    """Console-script entry point."""
+    raise SystemExit(main(sys.argv[1:]))
+
+
+if __name__ == '__main__':
+    main_cli()

git_a_grip/release.py

@@ -0,0 +1,148 @@
+"""Bump, tag and push as one command -- the ordering pre-push cannot have.
+
+This replaces a pre-push hook that did the same work (removed in v0.3.0).
+There, git had already chosen which sha to push before any hook ran, so a
+commit created afterwards could only end two ways: cancel the push, or let
+git push the superseded sha and watch it rejected as a non-fast-forward. Both
+print `error: failed to push some refs` over a release that succeeded.
+
+Run as a command instead, the order is simply right: bump first, push second,
+exit 0. Nothing to cancel, nothing to explain away. Point whatever alias you
+use for pushing at this, and a release stays one gesture.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from git_a_grip import cz
+
+# `cz bump` exit codes that mean "nothing to release", not "something broke".
+NO_COMMITS_FOUND = 21
+NONE_INCREMENT = 3
+PROTECTED_DEFAULT = 'main'
+
+
+def git(*args: str) -> subprocess.CompletedProcess[str]:
+    """Run git with `args`, capturing output."""
+    return subprocess.run(  # noqa: S603
+        ['git', *args],  # noqa: S607
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def current_branch() -> str:
+    """Return the checked-out branch."""
+    return git('rev-parse', '--abbrev-ref', 'HEAD').stdout.strip()
+
+
+def is_dirty() -> bool:
+    """Whether the working tree has uncommitted changes."""
+    return bool(git('status', '--porcelain').stdout.strip())
+
+
+def _push(branch: str, *extra: str) -> int:
+    # --no-verify so any pre-push hook the repo still has wired cannot
+    # re-enter this.
+    pushed = git(
+        'push',
+        '--no-verify',
+        '--follow-tags',
+        *extra,
+        'origin',
+        branch,
+    )
+    if pushed.returncode != 0:
+        sys.stderr.write(pushed.stderr)
+    return pushed.returncode
+
+
+USAGE = """\
+git-release -- bump the version, tag it, and push, in that order.
+
+  git-release              on main: bump, tag and push; elsewhere: just push
+  git-release --any-branch release from the current branch, whatever it is
+  git-release --help       show this
+
+Configure what the bump rewrites via [tool.commitizen] in the repo.
+"""
+
+
+def check_args(args: list[str]) -> int | None:
+    """Return an exit code if the args mean "do not release", else None."""
+    if '--help' in args or '-h' in args:
+        sys.stdout.write(USAGE)
+        return 0
+    # This command publishes. An argument it does not understand may well be
+    # someone asking for something other than "release now", so refuse rather
+    # than ignore it and push.
+    unknown = [a for a in args if a != '--any-branch']
+    if unknown:
+        sys.stderr.write(
+            f'release: unrecognised argument(s): {" ".join(unknown)}\n\n',
+        )
+        sys.stderr.write(USAGE)
+        return 2
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Bump if there is anything to release, then push. 0 means done."""
+    args = sys.argv[1:] if argv is None else argv
+
+    refused = check_args(args)
+    if refused is not None:
+        return refused
+
+    branch = current_branch()
+    if branch != PROTECTED_DEFAULT and '--any-branch' not in args:
+        # Not the release branch: just push, so this can stand in for
+        # `git push` everywhere without surprising anyone on a feature branch.
+        return _push(branch)
+
+    if is_dirty():
+        sys.stderr.write(
+            'release: working tree is dirty, refusing to bump. '
+            'Commit or stash first.\n',
+        )
+        return 1
+
+    return _bump_and_push(branch)
+
+
+def _bump_and_push(branch: str) -> int:
+    result = cz.run('bump', '--yes', '--no-verify')
+    if result.returncode in {NO_COMMITS_FOUND, NONE_INCREMENT}:
+        sys.stdout.write('No version-bumping commits since the last tag.\n')
+        return _push(branch)
+    if result.returncode != 0:
+        sys.stderr.write(result.stdout)
+        sys.stderr.write(result.stderr)
+        sys.stderr.write(
+            f'release: cz bump failed (exit {result.returncode}).\n',
+        )
+        return result.returncode
+
+    version = cz.run('version', '-p').stdout.strip()
+    code = _push(branch)
+    if code != 0:
+        sys.stderr.write(
+            f'release: bumped to v{version} locally but the push failed. '
+            'Fix the remote and run `git push --follow-tags`.\n',
+        )
+        return code
+
+    sys.stdout.write(f'Released v{version} (commit + tag pushed).\n')
+    return 0
+
+
+def main_cli() -> None:
+    """Console-script entry point."""
+    raise SystemExit(main())
+
+
+if __name__ == '__main__':
+    main_cli()

git_a_grip/restage.py

@@ -0,0 +1,55 @@
+"""Re-stage the files a hook rewrote, so its fixes land in the commit.
+
+A formatter that edits the working tree mid-commit leaves the fix *unstaged*:
+the commit still records the unformatted content and the next `git status` is
+dirty for no reason the human asked for. Every repo that hit this solved it
+the same way, with a `bash -c '... && git add "$@"'` wrapper around the entry.
+
+Doing it here instead means the `git add` is narrowed to the files that
+actually changed, compared by digest rather than assumed. pre-commit stashes
+unstaged changes for the duration of a hook run, so the working tree holds
+staged content only and re-adding a changed file cannot smuggle in an edit
+the author meant to keep back.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from pathlib import Path
+
+
+def target_paths(args: list[str]) -> list[str]:
+    """Pick the existing file paths out of a hook's argv.
+
+    Flag *values* that name a file (`--config .ruff.toml`) are picked up too,
+    which is harmless: a path is only ever re-staged after its digest changes,
+    and a config file the tool merely read has not changed.
+    """
+    return [a for a in args if not a.startswith('-') and Path(a).is_file()]
+
+
+def digests(paths: list[str]) -> dict[str, str]:
+    """Map each readable path to a digest of its current contents."""
+    out: dict[str, str] = {}
+    for path in paths:
+        try:
+            out[path] = hashlib.sha256(Path(path).read_bytes()).hexdigest()
+        except OSError:
+            continue
+    return out
+
+
+def changed(before: dict[str, str], after: dict[str, str]) -> list[str]:
+    """Return the paths whose digest moved between the two snapshots."""
+    return sorted(p for p, d in after.items() if before.get(p) != d)
+
+
+def add(paths: list[str]) -> int:
+    """Stage `paths`, returning git's exit code (0 when there is nothing)."""
+    if not paths:
+        return 0
+    return subprocess.run(  # noqa: S603
+        ['git', 'add', '--', *paths],  # noqa: S607
+        check=False,
+    ).returncode

git_a_grip/ruff_hooks.py

@@ -0,0 +1,57 @@
+"""Run ruff out of this hook's own interpreter, and keep its fixes staged.
+
+Same bargain as the commitizen hooks: ruff is a declared dependency of this
+package, so `sys.executable -m ruff` resolves inside the env pre-commit built
+here and a consuming repo needs no ruff on PATH, no venv, no `uv`. Pin a
+different ruff per repo with `additional_dependencies: [ruff==x.y.z]`.
+
+Both hooks rewrite files, and both re-stage what they rewrote -- including
+`ruff check --fix`, whose fixes otherwise sit unstaged while the commit
+records the unfixed code. A fixed file is committed as fixed; only the
+violations ruff *could not* fix stop the commit, via ruff's own exit code.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from git_a_grip import restage
+
+
+def _ruff(*args: str) -> int:
+    # Output is left to stream: ruff's diagnostics are the point of failing,
+    # and pre-commit already buffers a hook's output until it finishes.
+    return subprocess.run(  # noqa: S603
+        [sys.executable, '-m', 'ruff', *args],
+        check=False,
+    ).returncode
+
+
+def run(subcommand: str, args: list[str]) -> int:
+    """Run a rewriting ruff subcommand over `args` and re-stage its edits."""
+    paths = restage.target_paths(args)
+    before = restage.digests(paths)
+    # --force-exclude so the excludes in the repo's ruff config still apply
+    # to the paths pre-commit passes explicitly.
+    code = _ruff(subcommand, '--force-exclude', *args)
+    fixed = restage.changed(before, restage.digests(paths))
+    if fixed:
+        sys.stderr.write(
+            f'ruff {subcommand}: rewrote and re-staged {len(fixed)} file(s):\n'
+            + ''.join(f'  {p}\n' for p in fixed),
+        )
+        if restage.add(fixed) != 0:
+            sys.stderr.write('ruff: failed to re-stage the rewritten files.\n')
+            return 1
+    return code
+
+
+def check_cli() -> None:
+    """Console-script entry point for `ruff check --fix`."""
+    raise SystemExit(run('check', ['--fix', *sys.argv[1:]]))
+
+
+def format_cli() -> None:
+    """Console-script entry point for `ruff format`."""
+    raise SystemExit(run('format', sys.argv[1:]))

git_a_grip-0.4.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: git-a-grip
+Version: 0.4.0
+Summary: Pre-commit hooks that fail fast on bad commit messages, re-stage what they fix, and run your tests -- plus a release command and a cross-repo hook audit.
+Project-URL: Homepage, https://github.com/dannybrown37/git-a-grip
+Project-URL: Source, https://github.com/dannybrown37/git-a-grip
+Project-URL: Issues, https://github.com/dannybrown37/git-a-grip/issues
+Project-URL: Changelog, https://github.com/dannybrown37/git-a-grip/blob/main/CHANGELOG.md
+Author-email: Danny Brown <dannybrown37@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: commitizen,git,hooks,pre-commit,ruff
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: commitizen>=4.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: hooks
+Requires-Dist: ruff>=0.6; extra == 'hooks'
+Description-Content-Type: text/markdown
+
+# git-a-grip
+
+Personal [pre-commit](https://pre-commit.com) hooks.
+
+```yaml
+repos:
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.3.1
+    hooks:
+      - id: commitizen-early
+      - id: ruff-check
+      - id: ruff-format
+      - id: pytest
+        args: [tests/, -q]
+```
+
+The commitizen and ruff hooks reach their tool through
+`sys.executable -m <tool>` inside the env pre-commit builds for this repo, so
+a consuming project needs no `cz` or `ruff` on PATH, no venv and no
+`uv`/`uvx` of its own. (`pytest` is the exception — see below.)
+
+Each hook pays only for what it uses: commitizen is a dependency of the
+package, while ruff is declared by the two ruff hooks themselves, through
+`additional_dependencies` in `.pre-commit-hooks.yaml`. You still pass
+nothing. Pin your own ruff by setting `additional_dependencies:
+[ruff==x.y.z]` on the hook.
+
+## `commitizen-early` (pre-commit stage)
+
+Rejects a non-conventional commit message in about a third of a second,
+instead of after the whole slow hook suite has run.
+
+Git runs `pre-commit` -> `prepare-commit-msg` -> editor -> `commit-msg` as
+separate invocations, so a `stages: [commit-msg]` commitizen hook can only
+ever fail *after* your tests. Nothing in `.pre-commit-config.yaml` reorders
+that. This hook instead recovers the message from the `git commit` process's
+own argv while the pre-commit stage is still running, and checks it first.
+
+Pair it with the upstream `commitizen` hook, which still catches the cases
+argv cannot reach (interactive editor, merge, rebase) — this one exits 0 and
+defers whenever it finds no message:
+
+```yaml
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.3.1
+    hooks:
+      - id: commitizen-early
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.17.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+```
+
+Put it first and give it `fail_fast: true` if you want it to short-circuit
+the rest of the stage.
+
+## `git-release` (command, not a hook)
+
+Bump, tag and push, in that order, exiting 0. For repos that release from a
+laptop rather than from CI. Give it an alias that says what it does — not
+`gp`, which reads as `git push` right up until it publishes something:
+
+```bash
+alias release='uvx --from git-a-grip git-release'
+```
+
+This repo itself no longer uses it: releases here are cut by CI once the
+checks on `main` pass (see below). The command remains for projects with no
+such pipeline, where the alternative is remembering the four commands by
+hand.
+
+On `main` it bumps and pushes; on any other branch it just pushes, so it can
+replace `git push` outright. Refuses to run against a dirty tree, and pushes
+anyway when there are no bumpable commits.
+
+This exists because a pre-push hook *cannot* do this cleanly. Git chooses
+which sha to push before hooks run, so a commit created afterwards leaves two
+options: cancel the push, or let git push the now-superseded sha and have it
+rejected as a non-fast-forward. Both end in `error: failed to push some refs`
+on top of a release that worked. Running as a command puts the bump before
+the push and the problem disappears.
+
+Configure what the bump rewrites via `[tool.commitizen]` in the consuming
+repo (`version_provider`, `version_files`).
+
+> A `bump-on-push` pre-push hook did this up to v0.2.1 and was removed in
+> v0.3.0 for the reason above. If you pin an older rev, that hook still
+> exists there; on upgrading, drop `- id: bump-on-push` and use this command.
+
+## `ruff-check` and `ruff-format` (pre-commit stage)
+
+`ruff check --fix` and `ruff format`, with the fixes **re-staged** so they are
+part of the commit you just made rather than a dirty working tree you have to
+`git add` and amend. Only the violations ruff could not fix stop the commit,
+via ruff's own exit code.
+
+Pass ruff's flags through `args`:
+
+```yaml
+      - id: ruff-check
+        args: [--config, .ruff.toml]
+```
+
+`--force-exclude` is always passed, so the `exclude` in your ruff config still
+applies to the paths pre-commit hands over explicitly. The re-staged set is
+narrowed by content digest — a file ruff did not change is never touched, and
+because pre-commit stashes unstaged changes while a hook runs, re-adding a
+file cannot sweep in an edit you deliberately left unstaged.
+
+The ruff version is this repo's pinned dependency. To hold a repo at a
+different one:
+
+```yaml
+      - id: ruff-format
+        additional_dependencies: [ruff==0.16.1]
+```
+
+## `pytest` (pre-commit stage)
+
+Runs the test suite from the repo root. This hook can't use the isolated env
+pre-commit builds here — a test suite needs the *consuming* project's
+dependencies — so it shells out to a runner that resolves that environment,
+`uv run pytest` by default. Everything else in `args` goes to pytest:
+
+```yaml
+      - id: pytest
+        args: [tests/, -q]
+
+      - id: pytest
+        args: ['--runner=uv run --extra api pytest', tests/, -q]
+```
+
+It runs from the repo root regardless of where git was invoked, and drops the
+`VIRTUAL_ENV`/`PYTHONPATH` that pre-commit exports for its own hook env —
+which would otherwise point the runner at an environment holding none of your
+project's dependencies. Narrow when it runs with `files:` (default
+`^(src/|tests/).*`).
+
+## `pre-commit-audit` (command, not a hook)
+
+Audit every local repo's pre-commit setup at once, so a hook that drifted or
+never got installed shows up as a line rather than a surprise:
+
+```bash
+uvx --from git-a-grip pre-commit-audit
+```
+
+It walks the given trees (default: this repo's sibling directories), stops at
+each git working tree, and reports four things: which of this repo's hooks
+each project uses and the `rev` it pins, third-party hooks grouped by source
+repo and rev, one-off `repo: local` hooks with their entry, and repos with no
+usable config at all. `--json` emits the same data unformatted.
+
+```bash
+pre-commit-audit ~/projects ~/work
+pre-commit-audit --json | jq '.[] | select(.hooks == [])'
+```
+
+## Installing the commands
+
+The hooks need no installation — pre-commit builds this repo an isolated env
+from the `rev` you pin. The two commands (`git-release`, `pre-commit-audit`)
+are ordinary console scripts, published to PyPI:
+
+```bash
+uvx --from git-a-grip pre-commit-audit    # one-off
+uv tool install git-a-grip                # both commands, on PATH
+```
+
+That install carries only what the commands import — commitizen and pyyaml —
+not the ruff the hooks use. To run the hook entry points by hand as well, ask
+for the extra:
+
+```bash
+uv tool install 'git-a-grip[hooks]'
+```
+
+Straight from a tag works too, and is the way to run something not yet
+released:
+
+```bash
+uvx --from git+https://github.com/dannybrown37/git-a-grip@v0.3.1 git-release
+```
+
+## Releasing
+
+Merge to `main`. That is the whole gesture.
+
+`ci.yml` runs lint, tests and the install proofs on the merged commit; only
+if they all pass does its `bump` job run `cz bump`, which writes the version
+and changelog, commits, and tags. Pushing that tag triggers `publish.yml`,
+which builds and uploads to PyPI via trusted publishing. A push with no
+bumpable commits (docs, chores) ends after the checks and releases nothing.
+
+Nothing is tagged before the checks pass, so a red build cannot leave a
+version number stranded on a release that never shipped.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+This repo eats its own dog food: both hooks are wired into its own
+`.pre-commit-config.yaml`.

git_a_grip-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+git_a_grip/__init__.py,sha256=zrR82rhbTiePC05PtXOA46A_vuzYgyhU6KjeeablFec,33
+git_a_grip/audit.py,sha256=0fr3DBm5lVBpQjq6piVmIk4NuMM-5JIUPv9-wmINCtU,9032
+git_a_grip/commitizen_early.py,sha256=7NgJ5ouRfhyvYj_qI-g53qJha4WCaRxIoVrfmQENsyQ,4648
+git_a_grip/cz.py,sha256=6QzhZ_U5tXKa68U59TrN5vCk4SHJ0gimxp5GAPd0cjQ,759
+git_a_grip/pytest_hook.py,sha256=u_QH2UumuQyB__OwFAXslXnJy8WGoklyqglDTfUE33o,2934
+git_a_grip/release.py,sha256=wWuqQXNyNa39CCKBPuGob3hLp1PEXwRgbgGLwanExxU,4596
+git_a_grip/restage.py,sha256=qwcQG8PWhXSOPiY1KegUjmSEeV5KJQZG4GXGmB3H20s,2042
+git_a_grip/ruff_hooks.py,sha256=JmFtb8yqdWNPoMMQmdlPkQyDf5eXDraW2S-PipBW4Aw,2138
+git_a_grip-0.4.0.dist-info/METADATA,sha256=gaaeIpkd9tusz6HjezOc3IRaOuYQmJPbHOy5zORijOU,8583
+git_a_grip-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+git_a_grip-0.4.0.dist-info/entry_points.txt,sha256=0mpTtvufG8AhPnz2qFCDoXlRqn5rxxLtQne62p0w4wE,309
+git_a_grip-0.4.0.dist-info/licenses/LICENSE,sha256=tcsRhEYzrUgmGGe0RlgYZcUYVb_FCruDUBDFnCmGSrg,1068
+git_a_grip-0.4.0.dist-info/RECORD,,

git_a_grip-0.4.0.dist-info/WHEEL

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

git_a_grip-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,7 @@
+[console_scripts]
+commitizen-early = git_a_grip.commitizen_early:main_cli
+git-release = git_a_grip.release:main_cli
+pre-commit-audit = git_a_grip.audit:main_cli
+pytest-hook = git_a_grip.pytest_hook:main_cli
+ruff-check-hook = git_a_grip.ruff_hooks:check_cli
+ruff-format-hook = git_a_grip.ruff_hooks:format_cli

git_a_grip-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Brown
+
+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.