debugbrief 1.1.0__py3-none-any.whl

debugbrief/git_utils.py

@@ -0,0 +1,268 @@
+"""Thin, honest wrappers around the native ``git`` executable.
+
+We deliberately shell out to ``git`` via subprocess rather than depend on a
+library like GitPython. Every function fails safely: if ``git`` is missing, the
+directory is not a repo, or a command errors, callers get conservative defaults
+(e.g. ``None`` / empty lists) instead of exceptions.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .models import GitState
+
+_GIT_TIMEOUT_SECONDS = 15
+
+# Generated/cache artifact names that should never appear in a change summary.
+_ARTIFACT_DIR_NAMES = frozenset(
+    {
+        "__pycache__",
+        ".pytest_cache",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".cache",
+        ".tox",
+        ".nox",
+        ".hypothesis",
+        "node_modules",
+        ".DS_Store",
+    }
+)
+
+
+def _is_generated_artifact(path: str) -> bool:
+    """Return True for compiled/cache files that are not meaningful changes.
+
+    Filters out byte-compiled files (``*.pyc``/``*.pyo``), packaging metadata
+    (``*.egg-info``), editor/OS cruft (``.DS_Store``), and known cache or vendor
+    directories (``__pycache__``, the various ``.*_cache`` trees, ``node_modules``),
+    matching on any path segment. Real source files keep their names, so paths
+    like ``keymap.py`` or ``api_client.py`` are never filtered.
+    """
+    if path.endswith((".pyc", ".pyo")):
+        return True
+    for segment in path.replace("\\", "/").split("/"):
+        if not segment:
+            continue
+        if segment in _ARTIFACT_DIR_NAMES:
+            return True
+        if segment.endswith(".egg-info"):
+            return True
+    return False
+
+
+def _run_git(args: List[str], cwd: Path) -> Tuple[bool, str, str]:
+    """Run ``git <args>`` in ``cwd``.
+
+    Returns (success, stdout, stderr). ``success`` is True only when git is
+    available and exits 0.
+    """
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=str(cwd),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=_GIT_TIMEOUT_SECONDS,
+        )
+    except FileNotFoundError:
+        # git is not installed / not on PATH.
+        return False, "", "git executable not found"
+    except subprocess.TimeoutExpired:
+        return False, "", "git command timed out"
+    except OSError as exc:  # pragma: no cover - defensive
+        return False, "", str(exc)
+    return completed.returncode == 0, completed.stdout, completed.stderr
+
+
+def is_git_available() -> bool:
+    """Return True if a ``git`` executable can be invoked."""
+    ok, _, _ = _run_git(["--version"], Path.cwd())
+    return ok
+
+
+def find_repo_root(cwd: Path) -> Optional[str]:
+    """Return the absolute path of the enclosing Git repo root, or None."""
+    ok, out, _ = _run_git(["rev-parse", "--show-toplevel"], cwd)
+    if not ok:
+        return None
+    root = out.strip()
+    return root or None
+
+
+def is_inside_repo(cwd: Path) -> bool:
+    ok, out, _ = _run_git(["rev-parse", "--is-inside-work-tree"], cwd)
+    return ok and out.strip() == "true"
+
+
+def current_sha(cwd: Path) -> Optional[str]:
+    """Return the full HEAD SHA, or None (e.g. a repo with no commits yet)."""
+    ok, out, _ = _run_git(["rev-parse", "HEAD"], cwd)
+    if not ok:
+        return None
+    sha = out.strip()
+    return sha or None
+
+
+def current_short_sha(cwd: Path) -> Optional[str]:
+    """Return the abbreviated HEAD SHA, or None when unavailable."""
+    ok, out, _ = _run_git(["rev-parse", "--short", "HEAD"], cwd)
+    if not ok:
+        return None
+    sha = out.strip()
+    return sha or None
+
+
+def is_detached_head(cwd: Path) -> bool:
+    """Return True if HEAD is detached.
+
+    ``git symbolic-ref -q HEAD`` exits nonzero when HEAD is detached.
+    """
+    ok, out, _ = _run_git(["symbolic-ref", "-q", "HEAD"], cwd)
+    if ok and out.strip():
+        return False
+    # If there are no commits yet, treat HEAD as not detached (branch exists).
+    return current_sha(cwd) is not None
+
+
+def current_branch(cwd: Path) -> Optional[str]:
+    """Return the current branch name, or None when detached / unborn."""
+    ok, out, _ = _run_git(["symbolic-ref", "--short", "-q", "HEAD"], cwd)
+    if not ok:
+        return None
+    branch = out.strip()
+    return branch or None
+
+
+def _porcelain_label(code: str) -> str:
+    """Map a 2-char porcelain status code to a single M/A/D/R-style label.
+
+    Untracked files (``??``) are reported as ``A`` (added/new). For other
+    entries we use the index status when present, otherwise the worktree status.
+    """
+    if code == "??":
+        return "A"
+    x = code[0] if len(code) >= 1 else " "
+    y = code[1] if len(code) >= 2 else " "
+    primary = x if x != " " else y
+    mapping = {
+        "M": "M",  # modified
+        "A": "A",  # added
+        "D": "D",  # deleted
+        "R": "R",  # renamed
+        "C": "A",  # copied -> treat as added
+        "T": "M",  # type change -> treat as modified
+        "U": "M",  # unmerged -> treat as modified
+    }
+    return mapping.get(primary, primary if primary.strip() else "M")
+
+
+def name_status(cwd: Path) -> List[Tuple[str, str]]:
+    """Return sorted (label, path) pairs describing changed files.
+
+    Labels are M (modified), A (added/new), D (deleted), or R (renamed).
+    Combines staged, unstaged, and untracked changes via ``git status
+    --porcelain`` so the result reflects the working tree at call time. Safe
+    outside a repo: returns an empty list.
+    """
+    ok, out, _ = _run_git(["status", "--porcelain"], cwd)
+    if not ok:
+        return []
+    seen: Dict[str, str] = {}
+    for line in out.splitlines():
+        if not line.strip() or len(line) < 3:
+            continue
+        # Porcelain format: "XY <path>" or "XY <old> -> <new>" for renames.
+        code = line[:2]
+        path_part = line[3:]
+        if " -> " in path_part:
+            path_part = path_part.split(" -> ", 1)[1]
+        path_part = path_part.strip().strip('"')
+        if not path_part:
+            continue
+        if _is_generated_artifact(path_part):
+            continue
+        label = _porcelain_label(code)
+        # If a path appears twice, keep the first (most significant) label.
+        seen.setdefault(path_part, label)
+    return sorted(
+        ((label, path) for path, label in seen.items()), key=lambda item: item[1]
+    )
+
+
+def changed_files(cwd: Path) -> List[str]:
+    """Return a sorted, de-duplicated list of changed files.
+
+    Combines tracked changes (staged + unstaged) and untracked files from
+    ``git status --porcelain`` so the result reflects the working-tree state.
+    """
+    return [path for _label, path in name_status(cwd)]
+
+
+def shortstat(cwd: Path) -> Tuple[int, int]:
+    """Return (lines_added, lines_deleted) for unstaged + staged changes.
+
+    Uses ``git diff HEAD --shortstat`` which compares the working tree against
+    HEAD. Returns (0, 0) when there are no changes or stats are unavailable.
+    """
+    ok, out, _ = _run_git(["diff", "HEAD", "--shortstat"], cwd)
+    if not ok or not out.strip():
+        return 0, 0
+    return _parse_shortstat(out)
+
+
+def _parse_shortstat(text: str) -> Tuple[int, int]:
+    """Parse a ``--shortstat`` summary line into (added, deleted).
+
+    Example input:
+        " 3 files changed, 12 insertions(+), 4 deletions(-)"
+    """
+    added = 0
+    deleted = 0
+    for chunk in text.replace("\n", ",").split(","):
+        chunk = chunk.strip()
+        if "insertion" in chunk:
+            added = _leading_int(chunk)
+        elif "deletion" in chunk:
+            deleted = _leading_int(chunk)
+    return added, deleted
+
+
+def _leading_int(text: str) -> int:
+    digits = ""
+    for ch in text.strip():
+        if ch.isdigit():
+            digits += ch
+        else:
+            break
+    return int(digits) if digits else 0
+
+
+def capture_state(cwd: Path, initial: bool = True) -> GitState:
+    """Capture a snapshot of the Git state for ``cwd``.
+
+    Safe outside a repo: returns ``GitState(is_repo=False)``.
+    """
+    repo_root = find_repo_root(cwd)
+    if repo_root is None:
+        return GitState(is_repo=False)
+
+    detached = is_detached_head(cwd)
+    sha = current_sha(cwd)
+    branch = None if detached else current_branch(cwd)
+
+    state = GitState(
+        is_repo=True,
+        repo_root=repo_root,
+        branch=branch,
+        detached_head=detached,
+    )
+    if initial:
+        state.initial_sha = sha
+    else:
+        state.final_sha = sha
+    return state

debugbrief/models.py

@@ -0,0 +1,320 @@
+"""Typed data models for DebugBrief sessions and events.
+
+All persisted state flows through these dataclasses. Every model knows how to
+serialize itself to plain JSON-compatible dicts and reconstruct itself from
+them, which keeps persistence honest and round-trippable.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class SessionStatus(str, Enum):
+    ACTIVE = "ACTIVE"
+    COMPLETED = "COMPLETED"
+    INTERRUPTED = "INTERRUPTED"
+    ABANDONED = "ABANDONED"
+
+
+class EventType(str, Enum):
+    COMMAND = "command"
+    NOTE = "note"
+    SNAPSHOT = "snapshot"
+    WARNING = "warning"
+
+
+# Status values for a captured command.
+COMMAND_STATUS_PASSED = "passed"
+COMMAND_STATUS_FAILED = "failed"
+COMMAND_STATUS_TIMED_OUT = "timed_out"
+COMMAND_STATUS_ERROR = "error"  # could not execute (e.g. command not found)
+
+
+@dataclass
+class GitState:
+    is_repo: bool = False
+    repo_root: Optional[str] = None
+    initial_sha: Optional[str] = None
+    final_sha: Optional[str] = None
+    branch: Optional[str] = None
+    detached_head: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "is_repo": self.is_repo,
+            "repo_root": self.repo_root,
+            "initial_sha": self.initial_sha,
+            "final_sha": self.final_sha,
+            "branch": self.branch,
+            "detached_head": self.detached_head,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GitState":
+        return cls(
+            is_repo=bool(data.get("is_repo", False)),
+            repo_root=data.get("repo_root"),
+            initial_sha=data.get("initial_sha"),
+            final_sha=data.get("final_sha"),
+            branch=data.get("branch"),
+            detached_head=bool(data.get("detached_head", False)),
+        )
+
+
+@dataclass
+class Timestamps:
+    start: Optional[str] = None
+    end: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"start": self.start, "end": self.end}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Timestamps":
+        return cls(start=data.get("start"), end=data.get("end"))
+
+
+@dataclass
+class CommandClassification:
+    is_test: bool = False
+    is_verification: bool = False
+    tool: Optional[str] = None
+    status: str = COMMAND_STATUS_FAILED
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "is_test": self.is_test,
+            "is_verification": self.is_verification,
+            "tool": self.tool,
+            "status": self.status,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CommandClassification":
+        return cls(
+            is_test=bool(data.get("is_test", False)),
+            is_verification=bool(data.get("is_verification", False)),
+            tool=data.get("tool"),
+            status=data.get("status", COMMAND_STATUS_FAILED),
+        )
+
+
+@dataclass
+class CommandData:
+    """The ``data`` payload stored inside a command event."""
+
+    command: str
+    started_at: str
+    ended_at: str
+    duration_seconds: float
+    exit_code: Optional[int]
+    stdout_preview: str = ""
+    stderr_preview: str = ""
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+    used_shell: bool = False
+    classification: CommandClassification = field(default_factory=CommandClassification)
+    # Whether redaction masked anything in the stored command/output.
+    redacted: bool = False
+    # Lightweight git snapshot taken at the moment this command was recorded.
+    # Empty/None outside a repo or when git was unavailable (backward compatible:
+    # older session files simply omit these).
+    git_head: Optional[str] = None
+    git_changed_files: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "command": self.command,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+            "duration_seconds": self.duration_seconds,
+            "exit_code": self.exit_code,
+            "stdout_preview": self.stdout_preview,
+            "stderr_preview": self.stderr_preview,
+            "stdout_truncated": self.stdout_truncated,
+            "stderr_truncated": self.stderr_truncated,
+            "used_shell": self.used_shell,
+            "classification": self.classification.to_dict(),
+            "redacted": self.redacted,
+            "git_head": self.git_head,
+            "git_changed_files": list(self.git_changed_files),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CommandData":
+        return cls(
+            command=data.get("command", ""),
+            started_at=data.get("started_at", ""),
+            ended_at=data.get("ended_at", ""),
+            duration_seconds=float(data.get("duration_seconds", 0.0)),
+            exit_code=data.get("exit_code"),
+            stdout_preview=data.get("stdout_preview", ""),
+            stderr_preview=data.get("stderr_preview", ""),
+            stdout_truncated=bool(data.get("stdout_truncated", False)),
+            stderr_truncated=bool(data.get("stderr_truncated", False)),
+            used_shell=bool(data.get("used_shell", False)),
+            classification=CommandClassification.from_dict(
+                data.get("classification", {})
+            ),
+            redacted=bool(data.get("redacted", False)),
+            git_head=data.get("git_head"),
+            git_changed_files=list(data.get("git_changed_files", [])),
+        )
+
+
+@dataclass
+class Event:
+    type: str
+    timestamp: str
+    data: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": self.type, "timestamp": self.timestamp, "data": self.data}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Event":
+        return cls(
+            type=data.get("type", ""),
+            timestamp=data.get("timestamp", ""),
+            data=data.get("data", {}) or {},
+        )
+
+    # Convenience constructors -------------------------------------------------
+    @classmethod
+    def note(cls, text: str, timestamp: str) -> "Event":
+        return cls(type=EventType.NOTE.value, timestamp=timestamp, data={"text": text})
+
+    @classmethod
+    def warning(cls, message: str, timestamp: str) -> "Event":
+        return cls(
+            type=EventType.WARNING.value,
+            timestamp=timestamp,
+            data={"message": message},
+        )
+
+    @classmethod
+    def command(cls, command_data: CommandData, timestamp: str) -> "Event":
+        return cls(
+            type=EventType.COMMAND.value,
+            timestamp=timestamp,
+            data=command_data.to_dict(),
+        )
+
+    @classmethod
+    def snapshot(cls, payload: Dict[str, Any], timestamp: str) -> "Event":
+        return cls(type=EventType.SNAPSHOT.value, timestamp=timestamp, data=payload)
+
+
+@dataclass
+class FileChange:
+    """A single changed file with a name-status label (M/A/D/R)."""
+
+    status: str
+    path: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"status": self.status, "path": self.path}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FileChange":
+        return cls(status=data.get("status", "M"), path=data.get("path", ""))
+
+
+@dataclass
+class Summary:
+    modified_files: List[str] = field(default_factory=list)
+    file_changes: List[FileChange] = field(default_factory=list)
+    lines_added: int = 0
+    lines_deleted: int = 0
+    tests_run: List[str] = field(default_factory=list)
+    notes_count: int = 0
+    commands_count: int = 0
+    failed_commands_count: int = 0
+    command_capture_status: str = "full"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "modified_files": list(self.modified_files),
+            "file_changes": [fc.to_dict() for fc in self.file_changes],
+            "lines_added": self.lines_added,
+            "lines_deleted": self.lines_deleted,
+            "tests_run": list(self.tests_run),
+            "notes_count": self.notes_count,
+            "commands_count": self.commands_count,
+            "failed_commands_count": self.failed_commands_count,
+            "command_capture_status": self.command_capture_status,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Summary":
+        return cls(
+            modified_files=list(data.get("modified_files", [])),
+            file_changes=[
+                FileChange.from_dict(fc) for fc in data.get("file_changes", [])
+            ],
+            lines_added=int(data.get("lines_added", 0)),
+            lines_deleted=int(data.get("lines_deleted", 0)),
+            tests_run=list(data.get("tests_run", [])),
+            notes_count=int(data.get("notes_count", 0)),
+            commands_count=int(data.get("commands_count", 0)),
+            failed_commands_count=int(data.get("failed_commands_count", 0)),
+            command_capture_status=data.get("command_capture_status", "full"),
+        )
+
+
+@dataclass
+class Session:
+    title: str
+    project_root: str
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    status: str = SessionStatus.ACTIVE.value
+    warnings: List[str] = field(default_factory=list)
+    git: GitState = field(default_factory=GitState)
+    timestamps: Timestamps = field(default_factory=Timestamps)
+    events: List[Event] = field(default_factory=list)
+    summary: Summary = field(default_factory=Summary)
+
+    # Accessors ---------------------------------------------------------------
+    def command_events(self) -> List[Event]:
+        return [e for e in self.events if e.type == EventType.COMMAND.value]
+
+    def note_events(self) -> List[Event]:
+        return [e for e in self.events if e.type == EventType.NOTE.value]
+
+    def add_warning(self, message: str, timestamp: str) -> None:
+        """Record a warning both in the warnings list and the event timeline."""
+        if message not in self.warnings:
+            self.warnings.append(message)
+        self.events.append(Event.warning(message, timestamp))
+
+    # Serialization -----------------------------------------------------------
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "session_id": self.session_id,
+            "title": self.title,
+            "status": self.status,
+            "project_root": self.project_root,
+            "warnings": list(self.warnings),
+            "git": self.git.to_dict(),
+            "timestamps": self.timestamps.to_dict(),
+            "events": [e.to_dict() for e in self.events],
+            "summary": self.summary.to_dict(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Session":
+        return cls(
+            session_id=data.get("session_id", str(uuid.uuid4())),
+            title=data.get("title", ""),
+            status=data.get("status", SessionStatus.ACTIVE.value),
+            project_root=data.get("project_root", ""),
+            warnings=list(data.get("warnings", [])),
+            git=GitState.from_dict(data.get("git", {})),
+            timestamps=Timestamps.from_dict(data.get("timestamps", {})),
+            events=[Event.from_dict(e) for e in data.get("events", [])],
+            summary=Summary.from_dict(data.get("summary", {})),
+        )