gitrelevance 0.1.0__py3-none-any.whl

gitrelevance/git/files.py

@@ -0,0 +1,185 @@
+"""File change tracking and file history operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import git as gitmodule
+
+from gitrelevance.git.commits import Commit
+from gitrelevance.git.repository import GitRepository
+
+
+@dataclass(frozen=True, slots=True)
+class FileChange:
+    """Represents a change to a file in a commit.
+
+    Attributes:
+        path: Current path of the file
+        change_type: Type of change (added, modified, deleted, renamed)
+        old_path: Previous path if the file was renamed, None otherwise
+    """
+
+    path: str
+    change_type: Literal["added", "modified", "deleted", "renamed"]
+    old_path: str | None
+
+
+class FileOperations:
+    """Provides file-related operations for GitRepository.
+
+    This class wraps a GitRepository to add file-related functionality
+    without modifying the main class.
+    """
+
+    def __init__(self, repo: GitRepository) -> None:
+        """Initialize with a GitRepository instance.
+
+        Args:
+            repo: The GitRepository to operate on
+        """
+        self._repo = repo
+
+    @property
+    def _git_repo(self) -> gitmodule.Repo:
+        """Access the underlying GitPython repo object."""
+        return self._repo._repo  # type: ignore[return-value]
+
+    def file_exists_at_head(self, path: str) -> bool:
+        """Check if a file exists at HEAD.
+
+        Args:
+            path: Path to the file relative to repository root
+
+        Returns:
+            True if the file exists at HEAD
+        """
+        try:
+            self._git_repo.head.commit.tree[path]
+            return True
+        except (KeyError, Exception):
+            return False
+
+    def file_history(self, path: str) -> list[Commit]:
+        """Get the history of a file, following renames.
+
+        Uses ``git log --follow`` (not ``git rev-list --follow``, which is
+        unsupported) so that rename tracking works correctly.
+
+        Args:
+            path: Current path to the file
+
+        Returns:
+            List of commits that touched this file, newest first
+        """
+        try:
+            # git log --follow --format=%H emits one sha per commit, newest first.
+            # We must call git log (not rev-list); --follow is only a log option.
+            output: str = self._git_repo.git.log(
+                "--follow",
+                "--format=%H",
+                "--",
+                path,
+            )
+        except gitmodule.GitCommandError:
+            return []
+
+        if not output.strip():
+            return []
+
+        commits: list[Commit] = []
+        for sha in output.strip().splitlines():
+            sha = sha.strip()
+            if sha:
+                try:
+                    git_commit = self._git_repo.commit(sha)
+                    commits.append(Commit.from_gitpython(git_commit))
+                except Exception:
+                    continue
+        return commits
+
+    def was_file_deleted(self, path: str) -> bool:
+        """Check if a file was deleted (does not exist at HEAD).
+
+        Args:
+            path: Path to check
+
+        Returns:
+            True if the file does not exist at HEAD but existed in history
+        """
+        if self.file_exists_at_head(path):
+            return False
+
+        # Check whether the path ever appeared in commit history
+        try:
+            output: str = self._git_repo.git.log(
+                "--format=%H",
+                "--max-count=1",
+                "--diff-filter=D",
+                "--",
+                path,
+            )
+            # If git log --diff-filter=D finds anything, the file was deleted
+            if output.strip():
+                return True
+            # Also check if it was ever added at all (it might be renamed out)
+            output2: str = self._git_repo.git.log(
+                "--follow",
+                "--format=%H",
+                "--max-count=1",
+                "--",
+                path,
+            )
+            return bool(output2.strip())
+        except Exception:
+            return False
+
+    def find_renames(self, path: str) -> list[tuple[str, str]]:
+        """Find all renames of a file, returning (old_path, new_path) pairs.
+
+        Args:
+            path: Current or historical path of the file
+
+        Returns:
+            List of (old_path, new_path) tuples showing the rename chain,
+            in chronological order (oldest rename first).
+        """
+        try:
+            # -M enables rename detection across repository commits
+            output: str = self._git_repo.git.log(
+                "-M",
+                "--diff-filter=R",
+                "--name-status",
+                "--format=",
+            )
+        except gitmodule.GitCommandError:
+            return []
+
+        renames: list[tuple[str, str]] = []
+        for line in output.splitlines():
+            line = line.strip()
+            if not line or not line.startswith("R"):
+                continue
+            parts = line.split("\t")
+            if len(parts) >= 3:
+                old, new = parts[1].strip(), parts[2].strip()
+                if path == old or path == new:
+                    renames.append((old, new))
+
+        # git log returns newest-first; reverse to get chronological order
+        renames.reverse()
+        return renames
+
+
+# Convenience function to get file operations for a repository
+def get_file_operations(repo: GitRepository) -> FileOperations:
+    """Get a FileOperations instance for a repository.
+
+    Args:
+        repo: The GitRepository to get file operations for
+
+    Returns:
+        FileOperations instance
+    """
+    return FileOperations(repo)

gitrelevance/git/history.py

@@ -0,0 +1,217 @@
+"""Commit reference index and revert detection for issue tracking."""
+
+from __future__ import annotations
+
+import re
+from typing import Protocol
+
+from gitrelevance.git.commits import Commit
+from gitrelevance.git.repository import GitRepository
+
+
+# Cache key for the commit reference index on GitRepository instances
+_INDEX_CACHE_KEY = "_gitrelevance_commit_reference_index"
+
+# ---------------------------------------------------------------------------
+# Issue-number extraction helpers (private)
+# ---------------------------------------------------------------------------
+
+# Matches any #123-style number in a message body
+_HASH_ISSUE_RE = re.compile(r"#(\d+)")
+
+# Matches GH-123-style references (unambiguous, never a PR number)
+_GH_ISSUE_RE = re.compile(r"GH-(\d+)", re.IGNORECASE)
+
+# Detects PR-number contexts like "pull request #42" or "PR #42".
+# We check whether the 30 characters *before* the # match this pattern.
+_PR_CONTEXT_RE = re.compile(r"(?:pull\s+request|PR)\s+$", re.IGNORECASE)
+
+
+def _extract_issue_numbers(message: str) -> list[int]:
+    """Extract genuine issue numbers from a commit message.
+
+    Matches ``#123`` and ``GH-123`` patterns, but **excludes** numbers that
+    appear in PR-number contexts (e.g. ``pull request #42``, ``PR #42``).
+    Those are GitHub pull-request identifiers, *not* issue references, and
+    attributing a commit's file changes to a PR number causes evidence
+    cross-contamination across unrelated issues.
+
+    Returns a de-duplicated list of issue numbers in first-seen order.
+    """
+    numbers: list[int] = []
+    seen: set[int] = set()
+
+    # --- #NNN references ---
+    for match in _HASH_ISSUE_RE.finditer(message):
+        num = int(match.group(1))
+        if num in seen:
+            continue
+
+        start = match.start()
+
+        # Require a word boundary before '#': whitespace or start-of-string.
+        # This prevents matching inside URLs, file paths, or parenthetical
+        # PR-title patterns like "Feature (#42)".
+        if start > 0 and not message[start - 1].isspace():
+            continue
+
+        # Filter PR-number false positives.
+        # In squash-merge / merge-commit messages the subject line often
+        # reads "Merge pull request #42 from …".  The #42 there is a PR
+        # number, not an issue number.  We check the ~30 characters of
+        # context preceding the # to decide.
+        prefix = message[max(0, start - 30) : start]
+        if _PR_CONTEXT_RE.search(prefix):
+            continue
+
+        seen.add(num)
+        numbers.append(num)
+
+    # --- GH-NNN references (always unambiguous) ---
+    for match in _GH_ISSUE_RE.finditer(message):
+        num = int(match.group(1))
+        if num not in seen:
+            seen.add(num)
+            numbers.append(num)
+
+    return numbers
+
+
+def build_commit_reference_index(repo: GitRepository) -> dict[int, list[Commit]]:
+    """Build an index mapping issue numbers to commits that reference them.
+
+    This function walks the commit log exactly once and caches the result
+    on the repository instance for reuse. This is critical for performance
+    with large repositories (10,000+ commits).
+
+    Issue references are detected by patterns like #123 or GH-123 in commit
+    messages, where N is an issue number.  PR-number references (e.g.
+    ``pull request #42``, ``PR #42``) are explicitly excluded to prevent
+    evidence cross-contamination.
+
+    Args:
+        repo: The GitRepository to build the index for
+
+    Returns:
+        Dictionary mapping issue numbers to lists of commits referencing them
+    """
+    # Check if index already cached on repo instance
+    if hasattr(repo, _INDEX_CACHE_KEY):
+        return getattr(repo, _INDEX_CACHE_KEY)
+
+    # Build the index by walking commits once
+    index: dict[int, list[Commit]] = {}
+
+    for commit in repo.commits_since(None):
+        issue_nums = _extract_issue_numbers(commit.message)
+        for num in issue_nums:
+            if num not in index:
+                index[num] = []
+            index[num].append(commit)
+
+    # Cache the index on the repo instance
+    setattr(repo, _INDEX_CACHE_KEY, index)
+
+    return index
+
+
+def commits_referencing(repo: GitRepository, issue_number: int) -> list[Commit]:
+    """Get all commits that reference a specific issue.
+
+    Uses the cached index instead of scanning history itself.
+
+    Args:
+        repo: The GitRepository to search
+        issue_number: The issue number to find commits for
+
+    Returns:
+        List of commits referencing the issue, newest first
+    """
+    index = build_commit_reference_index(repo)
+    return index.get(issue_number, [])
+
+
+class RevertDetector(Protocol):
+    """Protocol for detecting reverts of commits.
+
+    Future implementations could use inverse-diff comparison,
+    message heuristics, patch similarity, or semantic analysis.
+    """
+
+    def find_reverts_of(self, repo: GitRepository, commit_sha: str) -> list[Commit]:
+        """Find commits that revert the specified commit.
+
+        Args:
+            repo: The GitRepository to search
+            commit_sha: SHA of the commit to find reverts of
+
+        Returns:
+            List of commits that revert the specified commit
+        """
+        ...
+
+
+class GitNativeRevertDetector:
+    """MVP implementation: detects only commits Git's own revert machinery produced.
+
+    This detector uses Git's native revert detection, which relies on
+    the parent/trailer relationship that 'git revert' creates. It does
+    NOT use free-text commit-message pattern matching or inverse-diff
+    comparison.
+    """
+
+    def find_reverts_of(self, repo: GitRepository, commit_sha: str) -> list[Commit]:
+        """Find commits that revert the specified commit using Git's native detection.
+
+        ``git revert`` always inserts exactly this sentence into the commit
+        message::
+
+            This reverts commit <full-sha>.
+
+        That line is generated by Git's own revert machinery and is the
+        authoritative signal we use.  We deliberately do NOT match commits
+        that merely mention "revert" in their message (the fake-revert test
+        exercises this).
+
+        Args:
+            repo: The GitRepository to search
+            commit_sha: SHA of the commit to find reverts of
+
+        Returns:
+            List of commits that revert the specified commit, or empty list
+        """
+        # Resolve the full SHA so partial SHAs compare correctly
+        target_commit = repo.get_commit(commit_sha)
+        if target_commit is None:
+            return []
+        full_sha = target_commit.sha
+
+        reverts: list[Commit] = []
+        for commit in repo.commits_since(None):
+            # Look for the exact Git-generated trailer line.
+            # git revert writes: "This reverts commit <sha>."
+            # where <sha> is the full 40-character hex SHA.
+            if f"This reverts commit {full_sha}." in commit.message:
+                reverts.append(commit)
+
+        return reverts
+
+
+# Default detector instance (module-level singleton)
+_default_detector: GitNativeRevertDetector | None = None
+
+
+def default_revert_detector() -> RevertDetector:
+    """Get the default revert detector.
+
+    Returns the singleton instance of GitNativeRevertDetector.
+    This can be swapped out later by reassigning the module-level variable
+    or by providing an alternative factory.
+
+    Returns:
+        The default RevertDetector implementation
+    """
+    global _default_detector
+    if _default_detector is None:
+        _default_detector = GitNativeRevertDetector()
+    return _default_detector

gitrelevance/git/repository.py

@@ -0,0 +1,161 @@
+"""GitRepository class for accessing Git repository data."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Iterator
+
+import git
+from git.exc import InvalidGitRepositoryError, NoSuchPathError
+
+from gitrelevance.git.commits import Commit
+
+
+class NotAGitRepositoryError(Exception):
+    """Raised when the provided path is not a valid Git repository."""
+
+    def __init__(self, path: str) -> None:
+        """Initialize the exception.
+
+        Args:
+            path: The path that was not a valid Git repository
+        """
+        self.path = path
+        super().__init__(f"Not a Git repository: {path}")
+
+
+class GitRepository:
+    """A read-only wrapper around a GitPython repository.
+
+    This class provides a clean interface for reading Git repository data
+    without modifying the .git directory.
+
+    Attributes:
+        path: Absolute path to the repository root
+        _repo: The underlying GitPython Repo object
+    """
+
+    def __init__(self, path: str) -> None:
+        """Initialize the GitRepository.
+
+        Args:
+            path: Path to the Git repository root (or a directory within it)
+
+        Raises:
+            NotAGitRepositoryError: If the path is not a valid Git repository
+        """
+        try:
+            self._repo = git.Repo(path, search_parent_directories=True)
+            self.path = str(self._repo.working_dir)
+        except (InvalidGitRepositoryError, NoSuchPathError, git.exc.GitError) as e:
+            raise NotAGitRepositoryError(path) from e
+
+    def current_branch(self) -> str:
+        """Get the name of the current branch.
+
+        Returns:
+            Name of the current branch (without 'refs/heads/' prefix)
+
+        Raises:
+            RuntimeError: If in detached HEAD state
+        """
+        if self._repo.head.is_detached:
+            raise RuntimeError("Repository is in detached HEAD state")
+        return self._repo.active_branch.name
+
+    def head_commit(self) -> Commit:
+        """Get the commit at HEAD.
+
+        Returns:
+            Commit object for HEAD
+
+        Raises:
+            RuntimeError: If there are no commits yet
+        """
+        try:
+            return Commit.from_gitpython(self._repo.head.commit)
+        except (TypeError, AttributeError):
+            raise RuntimeError("Repository has no commits yet")
+
+    def remote_url(self, name: str = "origin") -> str | None:
+        """Get the URL of a remote.
+
+        Args:
+            name: Name of the remote (default: "origin")
+
+        Returns:
+            Remote URL if the remote exists, None otherwise
+        """
+        try:
+            remote = self._repo.remote(name)
+            if remote.refs:
+                return str(remote.url)
+            return str(remote.url) if remote.url else None
+        except (ValueError, AttributeError):
+            return None
+
+    def get_commit(self, sha: str) -> Commit | None:
+        """Get a commit by its SHA.
+
+        Args:
+            sha: Full or abbreviated commit SHA
+
+        Returns:
+            Commit object if found, None otherwise
+        """
+        try:
+            commit = self._repo.commit(sha)
+            return Commit.from_gitpython(commit)
+        except (git.BadName, ValueError):
+            return None
+
+    def commit_exists(self, sha: str) -> bool:
+        """Check if a commit exists.
+
+        Args:
+            sha: Full or abbreviated commit SHA
+
+        Returns:
+            True if the commit exists, False otherwise
+        """
+        return self.get_commit(sha) is not None
+
+    def is_ancestor(self, ancestor_sha: str, descendant_sha: str) -> bool:
+        """Check if one commit is an ancestor of another.
+
+        Args:
+            ancestor_sha: Potential ancestor commit SHA
+            descendant_sha: Potential descendant commit SHA
+
+        Returns:
+            True if ancestor_sha is an ancestor of descendant_sha
+
+        Raises:
+            git.GitCommandError: If either commit doesn't exist
+        """
+        # Use git merge-base --is-ancestor which returns 0 if true, 1 if false
+        try:
+            self._repo.git.merge_base("--is-ancestor", ancestor_sha, descendant_sha)
+            return True  # git command succeeded, so it is an ancestor
+        except git.GitCommandError:
+            return False  # exit code 1 means not an ancestor
+
+    def commits_since(self, since: datetime | None = None) -> Iterator[Commit]:
+        """Get commits since a given datetime.
+
+        Args:
+            since: Optional datetime to filter commits from. If None, returns all commits.
+
+        Yields:
+            Commit objects in reverse chronological order
+        """
+        kwargs: dict[str, object] = {"reverse": False}  # newest first
+
+        if since is not None:
+            # Ensure we have timezone-aware datetime
+            if since.tzinfo is None:
+                since = since.replace(tzinfo=timezone.utc)
+            kwargs["since"] = since
+
+        for commit in self._repo.iter_commits(**kwargs):
+            yield Commit.from_gitpython(commit)

gitrelevance/issues/__init__.py

@@ -0,0 +1,5 @@
+"""Issue and Pull Request data models package."""
+
+from gitrelevance.issues.models import Issue, PullRequest
+
+__all__ = ["Issue", "PullRequest"]

gitrelevance/issues/models.py

@@ -0,0 +1,53 @@
+"""Issue and Pull Request data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """Represents a GitHub issue.
+
+    Attributes:
+        number: Issue number
+        title: Issue title
+        body: Issue body text
+        state: State of issue ("open" or "closed")
+        created_at: Datetime issue was created
+        closed_at: Datetime issue was closed, or None if open
+        labels: Tuple of label names attached to the issue
+        linked_pr_numbers: Tuple of PR numbers linked to this issue
+    """
+
+    number: int
+    title: str
+    body: str
+    state: Literal["open", "closed"]
+    created_at: datetime
+    closed_at: datetime | None
+    labels: tuple[str, ...]
+    linked_pr_numbers: tuple[int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class PullRequest:
+    """Represents a GitHub pull request.
+
+    Attributes:
+        number: Pull request number
+        title: Pull request title
+        merged: Whether the pull request was merged
+        merge_commit_sha: SHA of the merge commit, if merged
+        closes_issue_numbers: Tuple of issue numbers closed by this PR
+        files_changed: Tuple of file paths changed in this PR
+    """
+
+    number: int
+    title: str
+    merged: bool
+    merge_commit_sha: str | None
+    closes_issue_numbers: tuple[int, ...]
+    files_changed: tuple[str, ...]

gitrelevance/models.py

@@ -0,0 +1,60 @@
+"""Shared core data models for GitRelevance analysis and reporting."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from gitrelevance.issues.models import Issue
+
+
+class Classification(str, Enum):
+    """Classification of issue relevance relative to current Git repository state."""
+
+    RESOLVED = "RESOLVED"
+    PROBABLY_RESOLVED = "PROBABLY_RESOLVED"
+    STILL_RELEVANT = "STILL_RELEVANT"
+    OBSOLETE = "OBSOLETE"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass(frozen=True, slots=True)
+class EvidenceItem:
+    """Individual piece of evidence supporting or opposing issue relevance.
+
+    Attributes:
+        description: Human-readable explanation of the evidence.
+        weight: Signed integer weight indicating evidence strength (positive = resolved, negative = obsolete/unresolved).
+        category: Evidence category ("strong", "medium", or "obsolescence").
+        source_ref: Optional reference string (e.g. commit SHA or PR number).
+    """
+
+    description: str
+    weight: int
+    category: Literal["strong", "medium", "obsolescence"]
+    source_ref: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisResult:
+    """Complete analysis result for a single issue.
+
+    Attributes:
+        issue: The issue being analyzed.
+        classification: Final classification decision.
+        confidence: Evidence-strength score clamped to [0.05, 0.98].
+            This is a relative evidence-strength heuristic, NOT a calibrated
+            statistical probability. A higher value means more and stronger
+            evidence supports the classification, not that the classification
+            is more likely to be correct in a Bayesian sense.
+        evidence: Tuple of collected evidence items explaining the decision.
+            Each item carries a human-readable description, a signed weight,
+            a category, and an optional source_ref (short commit SHA or
+            "PR #N") so the result is self-contained for display.
+    """
+
+    issue: Issue
+    classification: Classification
+    confidence: float
+    evidence: tuple[EvidenceItem, ...]

gitrelevance/output/__init__.py

@@ -0,0 +1,8 @@
+"""Output rendering modules for terminal and JSON output."""
+
+from __future__ import annotations
+
+from gitrelevance.output.json import to_json
+from gitrelevance.output.terminal import TerminalRenderer
+
+__all__ = ["TerminalRenderer", "to_json"]