git_helpers.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/git_helpers.py
 
"""
Cohesive git helpers for prompt composition — plan 135 §3.5.
 
Purpose
-------
Provide the git facts the ``messages[1]`` environment sublayer needs —
``git_head_hash`` (branch/commit identity, may be cached by callers) and
``git_status_summary`` (the working-tree dirty summary) — behind a short
subprocess timeout that degrades gracefully and never raises into composition.
 
Responsibilities
----------------
- :func:`git_head_hash` — current ``HEAD`` short identity, ``""`` on any error.
- :func:`git_current_branch` — current branch name (``"HEAD"`` when detached,
  ``""`` on any error), for the ``messages[1]`` ``Git branch:`` field.
- :func:`git_status_summary` — modified/untracked/staged (+ ahead/behind)
  computed FRESH on each call (never HEAD-cached — working-tree status changes
  while ``HEAD`` does not), degrading to ``"(not a git repo)"`` on any error.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Neither function raises; both degrade to a sentinel string / ``""``.
- A short timeout bounds slow I/O (detached network drives, hung git).
- ``git_status_summary`` is never cached by the caller — it is recomputed on
  each (infrequent) variable-context render.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import subprocess
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.MAIN", "git_helpers", "module", 4)
 
_NOT_A_REPO = "(not a git repo)"
_GIT_TIMEOUT_S = 3.0
 
 
def git_head_hash() -> str:
    """Return the current git ``HEAD`` hash, or ``""`` if unavailable."""
    try:
        return subprocess.check_output(
            ["git", "rev-parse", "HEAD"],
            text=True, stderr=subprocess.DEVNULL, timeout=_GIT_TIMEOUT_S,
        ).strip()
    except (OSError, subprocess.SubprocessError):
        return ""
 
 
def git_current_branch() -> str:
    """Return the current branch name, ``"HEAD"`` when detached, or ``""`` on error."""
    try:
        return subprocess.check_output(
            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
            text=True, stderr=subprocess.DEVNULL, timeout=_GIT_TIMEOUT_S,
        ).strip()
    except (OSError, subprocess.SubprocessError):
        return ""
 
 
def git_status_summary() -> str:
    """Return a compact working-tree summary, or ``"(not a git repo)"`` on any error.
 
    Format: ``"<N> modified, <M> untracked, <K> staged"`` (+ ``", <P> ahead/<Q>
    behind origin"`` when the branch tracks a remote), or ``"clean"`` when there
    are no changes. Computed fresh every call — never cached by ``HEAD`` (the
    dirty summary changes while ``HEAD`` does not). Never raises.
    """
    func = "git_status_summary"
    try:
        proc = subprocess.run(
            ["git", "status", "--porcelain=v1", "-b"],
            capture_output=True, text=True, timeout=_GIT_TIMEOUT_S, check=False,
        )
    except (OSError, subprocess.SubprocessError) as exc:
        _dbg("OC_CHAT.MAIN", func, f"git status failed/timeout: {type(exc).__name__}", 3)
        return _NOT_A_REPO
    if proc.returncode != 0:
        return _NOT_A_REPO
    modified = untracked = staged = 0
    ahead = behind = 0
    for line in proc.stdout.splitlines():
        if line.startswith("## "):
            if "[" in line and "]" in line:
                tail = line[line.index("[") + 1: line.index("]")]
                for part in tail.split(","):
                    part = part.strip()
                    if part.startswith("ahead "):
                        ahead = int(part[6:] or 0)
                    elif part.startswith("behind "):
                        behind = int(part[7:] or 0)
            continue
        if not line:
            continue
        x, y = (line[0] if line else " "), (line[1] if len(line) > 1 else " ")
        if line[:2] == "??":
            untracked += 1
            continue
        if x not in (" ", "?"):
            staged += 1
        if y in ("M", "D"):
            modified += 1
    if not (modified or untracked or staged or ahead or behind):
        return "clean"
    summary = f"{modified} modified, {untracked} untracked, {staged} staged"
    if ahead or behind:
        summary += f", {ahead} ahead/{behind} behind origin"
    return summary
 
 
__all__ = ["git_head_hash", "git_current_branch", "git_status_summary"]