debugbrief 1.1.0__py3-none-any.whl

debugbrief/doctor.py

@@ -0,0 +1,324 @@
+"""Health-check logic for ``debugbrief doctor``.
+
+Runs a series of read-only checks (with an optional, safe ``--fix``) and reports
+PASS / WARN / FAIL lines plus an overall verdict and exit code:
+
+    0  ready (all PASS)
+    1  usable with warnings (>=1 WARN, no FAIL)
+    2  blocking issues (>=1 FAIL)
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from . import git_utils
+from .paths import DEBUGBRIEF_DIRNAME, ProjectPaths, ensure_local_ignore
+from .utils import is_supported_platform, read_json
+
+PASS = "PASS"
+WARN = "WARN"
+FAIL = "FAIL"
+
+EXIT_READY = 0
+EXIT_WARN = 1
+EXIT_BLOCKED = 2
+
+
+@dataclass
+class CheckResult:
+    level: str
+    name: str
+    detail: str = ""
+
+
+@dataclass
+class DoctorReport:
+    checks: List[CheckResult]
+    exit_code: int
+    summary: str
+
+
+def _overall(checks: List[CheckResult]) -> Tuple[int, str]:
+    if any(c.level == FAIL for c in checks):
+        return EXIT_BLOCKED, "DebugBrief has blocking issues."
+    if any(c.level == WARN for c in checks):
+        return EXIT_WARN, "DebugBrief is usable with warnings."
+    return EXIT_READY, "DebugBrief is ready."
+
+
+def _exclude_has_entry(paths: ProjectPaths) -> Optional[bool]:
+    """Return True/False if the exclude entry is present, or None if N/A."""
+    if not paths.is_git_repo or paths.repo_root is None:
+        return None
+    exclude = paths.repo_root / ".git" / "info" / "exclude"
+    if not exclude.exists():
+        return False
+    try:
+        lines = {
+            line.strip() for line in exclude.read_text(encoding="utf-8").splitlines()
+        }
+    except OSError:
+        return False
+    return f"{DEBUGBRIEF_DIRNAME}/" in lines or DEBUGBRIEF_DIRNAME in lines
+
+
+def run_doctor(paths: ProjectPaths, fix: bool = False) -> DoctorReport:
+    checks: List[CheckResult] = []
+
+    # Optional safe fixes applied up-front so subsequent checks reflect them.
+    fix_notes: List[str] = []
+    if fix:
+        try:
+            paths.ensure_directories()
+            fix_notes.append("ensured .debugbrief/ directories exist")
+        except OSError as exc:
+            fix_notes.append(f"could not create .debugbrief/ ({exc})")
+        changed, _warnings = ensure_local_ignore(paths)
+        if changed:
+            fix_notes.append("added .debugbrief/ to .git/info/exclude")
+
+    # 1. Platform
+    if is_supported_platform():
+        checks.append(CheckResult(PASS, "Platform", f"{platform.system()} (supported)"))
+    else:
+        checks.append(
+            CheckResult(
+                FAIL,
+                "Platform",
+                f"{platform.system()} is not supported (Unix-like only).",
+            )
+        )
+
+    # 2. Python version
+    py = ".".join(str(v) for v in sys.version_info[:3])
+    if sys.version_info[:2] >= (3, 9):
+        checks.append(CheckResult(PASS, "Python version", f"{py} (>= 3.9)"))
+    else:
+        checks.append(
+            CheckResult(FAIL, "Python version", f"{py} (3.9+ required)")
+        )
+
+    # 3. Project root
+    checks.append(
+        CheckResult(PASS, "Project root", str(paths.project_root))
+    )
+
+    # 4. Inside a Git repo?
+    if paths.is_git_repo:
+        checks.append(CheckResult(PASS, "Git repository", "inside a Git repo"))
+        # 5. Branch / detached HEAD
+        if git_utils.is_detached_head(paths.project_root):
+            checks.append(
+                CheckResult(
+                    WARN,
+                    "Git branch",
+                    "HEAD is detached; consider working on a branch.",
+                )
+            )
+        else:
+            branch = git_utils.current_branch(paths.project_root) or "(unborn branch)"
+            checks.append(CheckResult(PASS, "Git branch", branch))
+    else:
+        checks.append(
+            CheckResult(
+                WARN,
+                "Git repository",
+                "not inside a Git repo; Git metadata capture is disabled "
+                "(this is supported).",
+            )
+        )
+
+    # 6. .debugbrief directory exists?
+    if paths.base_dir.is_dir():
+        checks.append(
+            CheckResult(PASS, ".debugbrief directory", str(paths.base_dir))
+        )
+    else:
+        checks.append(
+            CheckResult(
+                WARN,
+                ".debugbrief directory",
+                "does not exist yet (created on first 'start', or run "
+                "'debugbrief doctor --fix').",
+            )
+        )
+
+    # 7. Writable / creatable?
+    writable_target = paths.base_dir if paths.base_dir.exists() else paths.project_root
+    if os.access(writable_target, os.W_OK):
+        checks.append(
+            CheckResult(PASS, "Storage writable", f"{writable_target} is writable")
+        )
+    else:
+        checks.append(
+            CheckResult(
+                FAIL,
+                "Storage writable",
+                f"{writable_target} is not writable; cannot persist sessions.",
+            )
+        )
+
+    # 8. .git/info/exclude contains .debugbrief/
+    has_exclude = _exclude_has_entry(paths)
+    if has_exclude is None:
+        checks.append(
+            CheckResult(PASS, "Local ignore", "N/A (not a Git repo)")
+        )
+    elif has_exclude:
+        checks.append(
+            CheckResult(PASS, "Local ignore", ".debugbrief/ is in .git/info/exclude")
+        )
+    else:
+        checks.append(
+            CheckResult(
+                WARN,
+                "Local ignore",
+                ".debugbrief/ is not in .git/info/exclude (run "
+                "'debugbrief doctor --fix' to add it).",
+            )
+        )
+
+    # 9-12. Active session checks
+    _active_session_checks(paths, checks)
+
+    # 13. Reports directory writable
+    reports_dir = paths.reports_dir
+    if reports_dir.is_dir():
+        if os.access(reports_dir, os.W_OK):
+            checks.append(
+                CheckResult(PASS, "Reports directory", f"{reports_dir} (writable)")
+            )
+        else:
+            checks.append(
+                CheckResult(
+                    FAIL, "Reports directory", f"{reports_dir} is not writable."
+                )
+            )
+    else:
+        checks.append(
+            CheckResult(
+                WARN,
+                "Reports directory",
+                "does not exist yet (created on 'end', or run "
+                "'debugbrief doctor --fix').",
+            )
+        )
+
+    # 14. Experimental shell mode
+    checks.append(
+        CheckResult(
+            PASS,
+            "Experimental shell mode",
+            "'start --shell' is unavailable by design in v1.",
+        )
+    )
+
+    exit_code, summary = _overall(checks)
+    if fix and fix_notes:
+        # Surface what --fix did as an informational PASS line.
+        checks.insert(
+            0, CheckResult(PASS, "Applied --fix", "; ".join(fix_notes))
+        )
+    return DoctorReport(checks=checks, exit_code=exit_code, summary=summary)
+
+
+def _active_session_checks(
+    paths: ProjectPaths, checks: List[CheckResult]
+) -> None:
+    pointer_path = paths.active_session_file
+    if not pointer_path.exists():
+        checks.append(
+            CheckResult(PASS, "Active session", "none (no active_session.json)")
+        )
+        return
+
+    # 9. exists
+    checks.append(CheckResult(PASS, "Active session", "active_session.json exists"))
+
+    # 10. valid JSON
+    try:
+        pointer = read_json(pointer_path)
+    except (ValueError, OSError) as exc:
+        checks.append(
+            CheckResult(
+                FAIL,
+                "Active session JSON",
+                f"active_session.json is not valid JSON ({exc}). Remove it to recover.",
+            )
+        )
+        return
+    if not isinstance(pointer, dict) or "session_id" not in pointer:
+        checks.append(
+            CheckResult(
+                FAIL,
+                "Active session JSON",
+                "active_session.json is malformed (missing session_id).",
+            )
+        )
+        return
+    checks.append(CheckResult(PASS, "Active session JSON", "valid"))
+
+    session_id = pointer.get("session_id", "")
+    session_file = paths.session_file(session_id)
+
+    # 12. interrupted?
+    if not session_file.exists():
+        checks.append(
+            CheckResult(
+                WARN,
+                "Session integrity",
+                "session looks interrupted (session file missing). Run "
+                "'debugbrief status' for recovery steps.",
+            )
+        )
+        return
+
+    try:
+        session_data = read_json(session_file)
+    except (ValueError, OSError) as exc:
+        checks.append(
+            CheckResult(
+                FAIL,
+                "Session integrity",
+                f"session file is unreadable ({exc}).",
+            )
+        )
+        return
+
+    status = session_data.get("status")
+    if status != "ACTIVE":
+        checks.append(
+            CheckResult(
+                WARN,
+                "Session integrity",
+                f"active pointer references a session with status {status!r}.",
+            )
+        )
+    else:
+        checks.append(CheckResult(PASS, "Session integrity", "consistent"))
+
+    # 11. points to current project root?
+    session_root = session_data.get("project_root", "")
+    try:
+        same = Path(session_root).resolve() == Path(paths.project_root).resolve()
+    except (OSError, ValueError):
+        same = session_root == str(paths.project_root)
+    if same:
+        checks.append(
+            CheckResult(PASS, "Session project root", "matches current project")
+        )
+    else:
+        checks.append(
+            CheckResult(
+                WARN,
+                "Session project root",
+                f"active session root ({session_root}) differs from current "
+                f"project root ({paths.project_root}).",
+            )
+        )

debugbrief/filters.py

@@ -0,0 +1,280 @@
+"""Command classification, report-noise filtering, and deduplication.
+
+This module is deterministic and dependency-free. It never guesses intent: it
+only recognizes well-known tool invocations by their token patterns and reports
+pass/fail strictly from real exit codes.
+"""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+from .models import (
+    COMMAND_STATUS_ERROR,
+    COMMAND_STATUS_FAILED,
+    COMMAND_STATUS_PASSED,
+    COMMAND_STATUS_TIMED_OUT,
+    CommandClassification,
+    CommandData,
+    Event,
+)
+from .utils import parse_iso8601
+
+# Default window (seconds) within which identical commands are squashed in reports.
+DEFAULT_DEDUP_WINDOW_SECONDS = 30
+
+# Low-value commands dropped from reports unless they failed.
+_NOISE_SINGLE = {"ls", "ll", "pwd", "cd", "clear", "history", "cat"}
+_NOISE_PAIRS = {("git", "status")}
+
+# (pattern_tokens, tool) for test-command detection.
+_TEST_PATTERNS: List[Tuple[List[str], str]] = [
+    (["pytest"], "pytest"),
+    (["py.test"], "pytest"),
+    (["npm", "test"], "npm"),
+    (["npm", "run", "test"], "npm"),
+    (["pnpm", "test"], "pnpm"),
+    (["pnpm", "run", "test"], "pnpm"),
+    (["yarn", "test"], "yarn"),
+    (["yarn", "run", "test"], "yarn"),
+    (["jest"], "jest"),
+    (["go", "test"], "go"),
+    (["cargo", "test"], "cargo"),
+    (["rspec"], "rspec"),
+    (["bundle", "exec", "rspec"], "rspec"),
+    (["mvn", "test"], "maven"),
+    (["gradle", "test"], "gradle"),
+    (["./gradlew", "test"], "gradle"),
+]
+
+# (pattern_tokens, tool, category) for build/lint/typecheck detection.
+_BUILD_PATTERNS: List[Tuple[List[str], str, str]] = [
+    (["npm", "run", "build"], "npm", "build"),
+    (["pnpm", "build"], "pnpm", "build"),
+    (["pnpm", "run", "build"], "pnpm", "build"),
+    (["yarn", "build"], "yarn", "build"),
+    (["npm", "run", "lint"], "npm", "lint"),
+    (["pnpm", "lint"], "pnpm", "lint"),
+    (["pnpm", "run", "lint"], "pnpm", "lint"),
+    (["yarn", "lint"], "yarn", "lint"),
+    (["npm", "run", "typecheck"], "npm", "typecheck"),
+    (["pnpm", "typecheck"], "pnpm", "typecheck"),
+    (["pnpm", "run", "typecheck"], "pnpm", "typecheck"),
+    (["yarn", "typecheck"], "yarn", "typecheck"),
+    (["mypy"], "mypy", "typecheck"),
+    (["ruff", "check"], "ruff", "lint"),
+    (["black", "--check"], "black", "lint"),
+    (["tsc", "--noEmit"], "tsc", "typecheck"),
+]
+
+
+def _tokenize(command: str) -> List[str]:
+    """Tokenize a command string, tolerating shlex parse errors."""
+    try:
+        return shlex.split(command)
+    except ValueError:
+        return command.split()
+
+
+def _contains_subsequence(tokens: List[str], pattern: List[str]) -> bool:
+    """Return True if ``pattern`` appears as a contiguous run inside ``tokens``."""
+    if not pattern or len(pattern) > len(tokens):
+        return False
+    for start in range(len(tokens) - len(pattern) + 1):
+        if tokens[start : start + len(pattern)] == pattern:
+            return True
+    return False
+
+
+def _match_test(tokens: List[str]) -> Optional[str]:
+    for pattern, tool in _TEST_PATTERNS:
+        if _contains_subsequence(tokens, pattern):
+            return tool
+    return None
+
+
+def _match_build(tokens: List[str]) -> Optional[Tuple[str, str]]:
+    for pattern, tool, category in _BUILD_PATTERNS:
+        if _contains_subsequence(tokens, pattern):
+            return tool, category
+    return None
+
+
+def status_from_outcome(
+    exit_code: Optional[int], timed_out: bool, errored: bool
+) -> str:
+    """Map an execution outcome to a command status string."""
+    if timed_out:
+        return COMMAND_STATUS_TIMED_OUT
+    if errored:
+        return COMMAND_STATUS_ERROR
+    if exit_code == 0:
+        return COMMAND_STATUS_PASSED
+    return COMMAND_STATUS_FAILED
+
+
+def classify_command(
+    command: str,
+    exit_code: Optional[int],
+    timed_out: bool = False,
+    errored: bool = False,
+) -> CommandClassification:
+    """Classify a command into test / verification categories.
+
+    A command is verification-worthy only if it is a recognized test command
+    that exited 0, or a recognized build/lint/typecheck command that exited 0.
+    Pass/fail is derived strictly from the real exit code.
+    """
+    tokens = _tokenize(command)
+    status = status_from_outcome(exit_code, timed_out, errored)
+    passed = status == COMMAND_STATUS_PASSED
+
+    test_tool = _match_test(tokens)
+    if test_tool is not None:
+        return CommandClassification(
+            is_test=True,
+            is_verification=passed,
+            tool=test_tool,
+            status=status,
+        )
+
+    build_match = _match_build(tokens)
+    if build_match is not None:
+        tool, _category = build_match
+        return CommandClassification(
+            is_test=False,
+            is_verification=passed,
+            tool=tool,
+            status=status,
+        )
+
+    return CommandClassification(
+        is_test=False,
+        is_verification=False,
+        tool=None,
+        status=status,
+    )
+
+
+def is_noise_command(command: str) -> bool:
+    """Return True for low-value commands that reports should usually omit."""
+    stripped = command.strip()
+    if not stripped:
+        return True
+    tokens = stripped.split()
+    if not tokens:
+        return True
+    if tokens[0] in _NOISE_SINGLE:
+        return True
+    return len(tokens) >= 2 and (tokens[0], tokens[1]) in _NOISE_PAIRS
+
+
+@dataclass
+class ReportCommand:
+    """A command as it should appear in a report, after dedup/filtering."""
+
+    command: str
+    count: int
+    first_timestamp: str
+    last_timestamp: str
+    exit_code: Optional[int]
+    status: str
+    is_test: bool
+    is_verification: bool
+    tool: Optional[str]
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+    stderr_preview: str = ""
+
+    @property
+    def failed(self) -> bool:
+        return self.status in (
+            COMMAND_STATUS_FAILED,
+            COMMAND_STATUS_TIMED_OUT,
+            COMMAND_STATUS_ERROR,
+        )
+
+
+def _event_seconds(event: Event) -> float:
+    try:
+        return parse_iso8601(event.timestamp).timestamp()
+    except (ValueError, TypeError):
+        return 0.0
+
+
+def build_report_commands(
+    command_events: List[Event],
+    dedup_window_seconds: int = DEFAULT_DEDUP_WINDOW_SECONDS,
+    drop_noise: bool = True,
+) -> List[ReportCommand]:
+    """Turn raw command events into a concise, deduplicated report list.
+
+    - Noise commands (ls, cd, git status, ...) are dropped unless they failed.
+    - Identical commands within ``dedup_window_seconds`` are squashed, tracking
+      a count and keeping the most recent timestamp and outcome.
+    """
+    ordered = sorted(command_events, key=_event_seconds)
+    results: List[ReportCommand] = []
+
+    for event in ordered:
+        data = CommandData.from_dict(event.data)
+        command_text = data.command
+        cls = data.classification
+        status = cls.status
+        is_failure = status in (
+            COMMAND_STATUS_FAILED,
+            COMMAND_STATUS_TIMED_OUT,
+            COMMAND_STATUS_ERROR,
+        )
+
+        if drop_noise and is_noise_command(command_text) and not is_failure:
+            continue
+
+        ts = event.timestamp
+        ts_seconds = _event_seconds(event)
+
+        merged = False
+        for existing in results:
+            if existing.command != command_text:
+                continue
+            try:
+                gap = ts_seconds - parse_iso8601(existing.last_timestamp).timestamp()
+            except (ValueError, TypeError):
+                gap = dedup_window_seconds + 1
+            if 0 <= gap <= dedup_window_seconds:
+                existing.count += 1
+                existing.last_timestamp = ts
+                existing.exit_code = data.exit_code
+                existing.status = status
+                existing.is_test = cls.is_test
+                existing.is_verification = cls.is_verification
+                existing.tool = cls.tool
+                existing.stdout_truncated = data.stdout_truncated
+                existing.stderr_truncated = data.stderr_truncated
+                existing.stderr_preview = data.stderr_preview
+                merged = True
+                break
+
+        if merged:
+            continue
+
+        results.append(
+            ReportCommand(
+                command=command_text,
+                count=1,
+                first_timestamp=ts,
+                last_timestamp=ts,
+                exit_code=data.exit_code,
+                status=status,
+                is_test=cls.is_test,
+                is_verification=cls.is_verification,
+                tool=cls.tool,
+                stdout_truncated=data.stdout_truncated,
+                stderr_truncated=data.stderr_truncated,
+                stderr_preview=data.stderr_preview,
+            )
+        )
+
+    return results