gitrelevance 0.1.0__py3-none-any.whl

gitrelevance/analysis/matcher.py

@@ -0,0 +1,200 @@
+"""Matcher for correlating Git history data with issue tracker data."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from gitrelevance.git.commits import Commit
+from gitrelevance.git.history import commits_referencing
+from gitrelevance.git.repository import GitRepository
+from gitrelevance.issues.models import Issue, PullRequest
+
+if TYPE_CHECKING:
+    from gitrelevance.providers.base import Provider
+
+logger = logging.getLogger(__name__)
+
+# Temporary debug: issue numbers to trace in detail
+_TRACE_ISSUES: set[int] = {34}
+
+
+@dataclass(frozen=True, slots=True)
+class MatchSet:
+    """Encapsulates all Git and PR evidence related to a specific Issue.
+
+    Attributes:
+        issue: The issue being analyzed.
+        referencing_commits: Commits directly referencing the issue (e.g., #123, GH-123).
+        linked_prs: Pull requests connected or closing the issue.
+        pr_commits: Resolved merge commits from linked PRs present in local Git history.
+        related_files: Deterministic sorted tuple of all files touched by referencing commits,
+                       PR merge commits, or linked PR file changes.
+    """
+
+    issue: Issue
+    referencing_commits: tuple[Commit, ...]
+    linked_prs: tuple[PullRequest, ...]
+    pr_commits: tuple[Commit, ...]
+    related_files: tuple[str, ...]
+
+
+def build_match_set(
+    issue: Issue,
+    repo: GitRepository,
+    provider_prs: list[PullRequest],
+) -> MatchSet:
+    """Build a MatchSet describing everything in Git history related to an issue.
+
+    Args:
+        issue: The issue to build the match set for.
+        repo: The local Git repository wrapper.
+        provider_prs: List of pull requests fetched from the provider.
+
+    Returns:
+        A MatchSet containing referencing commits, linked PRs, PR merge commits,
+        and affected file paths.
+    """
+    _trace = issue.number in _TRACE_ISSUES
+
+    # 1. Referencing commits using the cached single-pass commit index
+    ref_commits = commits_referencing(repo, issue.number)
+
+    if _trace:
+        logger.warning(
+            "[TRACE] === build_match_set for issue #%d (title=%r) ===",
+            issue.number, issue.title,
+        )
+        logger.warning("[TRACE]   issue.state=%s, issue.linked_pr_numbers=%s",
+                        issue.state, issue.linked_pr_numbers)
+        if ref_commits:
+            logger.warning("[TRACE]   (a) commits_referencing(%d) found %d commit(s):",
+                           issue.number, len(ref_commits))
+            for c in ref_commits:
+                logger.warning("[TRACE]       sha=%s  message=%r  files_changed=%s",
+                               c.short_sha, c.message, c.files_changed)
+        else:
+            logger.warning("[TRACE]   (a) commits_referencing(%d) found 0 commits.", issue.number)
+
+    # 2. Linked PRs: union of PRs closing this issue or linked in the issue model
+    matched_prs: list[PullRequest] = []
+    seen_pr_numbers: set[int] = set()
+    for pr in provider_prs:
+        closes_match = issue.number in pr.closes_issue_numbers
+        linked_match = pr.number in issue.linked_pr_numbers
+        if closes_match or linked_match:
+            if pr.number not in seen_pr_numbers:
+                seen_pr_numbers.add(pr.number)
+                matched_prs.append(pr)
+                if _trace:
+                    reason = []
+                    if closes_match:
+                        reason.append(f"closes_issue_numbers={pr.closes_issue_numbers}")
+                    if linked_match:
+                        reason.append(f"linked_pr_numbers match (PR#{pr.number} in issue.linked_pr_numbers)")
+                    logger.warning(
+                        "[TRACE]   (b) matched PR #%d (title=%r, merged=%s, files_changed=%d items):",
+                        pr.number, pr.title, pr.merged, len(pr.files_changed),
+                    )
+                    logger.warning("[TRACE]       reason: %s", " + ".join(reason))
+                    logger.warning("[TRACE]       files_changed=%s", pr.files_changed)
+
+    if _trace and not matched_prs:
+        logger.warning("[TRACE]   (b) No PRs matched for issue #%d.", issue.number)
+
+    # 3. Resolve merge commits for linked PRs in local git history (skip if not found)
+    resolved_pr_commits: list[Commit] = []
+    seen_commit_shas: set[str] = set()
+    # Track which PRs had their merge commit resolved locally, so we can
+    # skip their pr.files_changed in step 4.  When the merge commit IS
+    # in the local repo, its files_changed (from the actual git diff) is
+    # already included via resolved_pr_commits and is more accurate than
+    # the GitHub API file list, which may reflect a huge bundled changeset
+    # unrelated to the specific issue.
+    prs_with_resolved_commits: set[int] = set()
+    for pr in matched_prs:
+        if pr.merge_commit_sha:
+            commit = repo.get_commit(pr.merge_commit_sha)
+            if commit is not None and commit.sha not in seen_commit_shas:
+                seen_commit_shas.add(commit.sha)
+                resolved_pr_commits.append(commit)
+                prs_with_resolved_commits.add(pr.number)
+                if _trace:
+                    logger.warning(
+                        "[TRACE]   (c) resolved merge commit for PR #%d: sha=%s  files_changed=%s",
+                        pr.number, commit.short_sha, commit.files_changed,
+                    )
+            elif _trace:
+                logger.warning(
+                    "[TRACE]   (c) PR #%d merge_commit_sha=%s NOT found in local repo",
+                    pr.number, pr.merge_commit_sha,
+                )
+
+    # 4. Related files: union across referencing_commits, pr_commits, and linked_prs
+    files: set[str] = set()
+    for c in ref_commits:
+        files.update(c.files_changed)
+    for c in resolved_pr_commits:
+        files.update(c.files_changed)
+    # Add pr.files_changed only for PRs where it's safe:
+    #
+    #  - Unmerged PRs (WIP / review): always include — pr.files_changed
+    #    is the only source of file info and drives the STILL_RELEVANT signal.
+    #
+    #  - Merged PRs whose merge commit IS in the local repo: skip — the
+    #    merge commit's actual git diff (already added above) is more
+    #    accurate than the GitHub API file list.
+    #
+    #  - Merged PRs whose merge commit is NOT in the local repo (shallow
+    #    clone): skip — pr.files_changed may reflect a huge bundled
+    #    squashed changeset (e.g. 27 files for a CODE_OF_CONDUCT PR)
+    #    that injects unrelated server/ files into related_files,
+    #    causing false OBSOLETE evidence when those files are deleted.
+    for pr in matched_prs:
+        if pr.number in prs_with_resolved_commits:
+            # Merge commit found locally — its files are already included above
+            continue
+        if pr.merged:
+            # Merged but merge commit missing (shallow clone) — skip
+            # pr.files_changed to avoid cross-contamination from broad
+            # bundled changesets that are unrelated to the specific issue.
+            continue
+        # Unmerged PR — include files_changed for STILL_RELEVANT detection
+        files.update(pr.files_changed)
+
+    if _trace:
+        server_files = [f for f in files if f.startswith("server/")]
+        logger.warning(
+            "[TRACE]   (d) final related_files: %d total files, %d server/* files",
+            len(files), len(server_files),
+        )
+        if server_files:
+            logger.warning("[TRACE]       server files: %s", server_files)
+
+    return MatchSet(
+        issue=issue,
+        referencing_commits=tuple(ref_commits),
+        linked_prs=tuple(matched_prs),
+        pr_commits=tuple(resolved_pr_commits),
+        related_files=tuple(sorted(files)),
+    )
+
+
+def build_all_match_sets(
+    issues: list[Issue],
+    repo: GitRepository,
+    provider: Provider,
+) -> dict[int, MatchSet]:
+    """Build match sets for all given issues, fetching pull requests only once.
+
+    Args:
+        issues: List of issues to correlate.
+        repo: The local Git repository wrapper.
+        provider: Issue tracker provider implementing Provider protocol.
+
+    Returns:
+        Dictionary mapping issue number to its corresponding MatchSet.
+    """
+    prs = provider.get_pull_requests(state="all")
+    return {issue.number: build_match_set(issue, repo, prs) for issue in issues}

gitrelevance/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI module for GitRelevance."""
+
+from __future__ import annotations
+
+from gitrelevance.cli.commands import app
+
+__all__ = ["app"]

gitrelevance/cli/commands.py

@@ -0,0 +1,262 @@
+"""CLI commands implementation for GitRelevance using Typer."""
+
+from __future__ import annotations
+
+import logging
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Callable, Literal, Optional
+
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
+
+from gitrelevance import config
+from gitrelevance.analysis.engine import AnalysisEngine
+from gitrelevance.git.repository import GitRepository, NotAGitRepositoryError
+from gitrelevance.output.json import to_json
+from gitrelevance.output.terminal import TerminalRenderer
+from gitrelevance.providers.base import Provider, RateLimitExceededError
+from gitrelevance.providers.github import GitHubProvider
+
+app = typer.Typer(
+    name="gitrelevance",
+    help="Analyze whether historical GitHub issues are still relevant using Git history as evidence.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def callback(
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose debug logging.",
+    ),
+) -> None:
+    """GitRelevance: Analyze historical GitHub issues using Git history."""
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+# Optional seam for dependency injection in tests
+_provider_override: Provider | None = None
+_provider_factory: Callable[[str, str, str | None], Provider] | None = None
+
+
+def set_provider_override(provider: Provider | None) -> None:
+    """Set a global provider override for testing."""
+    global _provider_override
+    _provider_override = provider
+
+
+def set_provider_factory(factory: Callable[[str, str, str | None], Provider] | None) -> None:
+    """Set a global provider factory for testing."""
+    global _provider_factory
+    _provider_factory = factory
+
+
+@app.command()
+def analyze(
+    state: str = typer.Option(
+        "all",
+        "--state",
+        "-s",
+        help="Filter issue state: open, closed, or all.",
+    ),
+    since: Optional[str] = typer.Option(
+        None,
+        "--since",
+        help="Filter issues created on or after date (YYYY-MM-DD).",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output raw JSON instead of formatted terminal tables.",
+    ),
+    path: str = typer.Option(
+        ".",
+        "--path",
+        "-p",
+        help="Path to local Git repository (defaults to current directory).",
+        hidden=True,
+    ),
+) -> None:
+    """Analyze repository issues against local Git history."""
+    err_console = Console(stderr=True)
+
+    # 1. Detect local Git repository
+    try:
+        repo = GitRepository(path)
+    except NotAGitRepositoryError:
+        err_console.print(
+            f"[bold red]Error:[/bold red] Directory '{path}' is not a Git repository. "
+            "Please run gitrelevance from within a git repository or pass a valid repository path."
+        )
+        raise typer.Exit(code=1)
+
+    # 2. Detect remote URL and parse owner/repo
+    remote_url = repo.remote_url("origin")
+    if not remote_url:
+        err_console.print(
+            "[bold red]Error:[/bold red] No 'origin' remote found in the repository. "
+            "GitRelevance requires a GitHub remote to correlate issues."
+        )
+        raise typer.Exit(code=1)
+
+    # Parse GitHub owner/repo
+    parsed = GitHubProvider.parse_remote(remote_url)
+    if not parsed:
+        err_console.print(
+            f"[bold red]Error:[/bold red] Remote URL '{remote_url}' is not a recognized GitHub URL. "
+            "Currently only GitHub-hosted repositories are supported."
+        )
+        raise typer.Exit(code=1)
+
+    owner, repo_name = parsed
+
+    # 3. Construct provider
+    token = config.load_github_token()
+    if _provider_override is not None:
+        provider = _provider_override
+    elif _provider_factory is not None:
+        provider = _provider_factory(owner, repo_name, token)
+    else:
+        if not token and not json_output:
+            err_console.print(
+                "[yellow]Note:[/yellow] Running in unauthenticated mode (GITHUB_TOKEN not set). "
+                "GitHub API rate limit is 60 requests/hour."
+            )
+        provider = GitHubProvider(owner=owner, repo=repo_name, token=token)
+
+    # Validate state option
+    state_normalized = state.lower()
+    if state_normalized not in ("open", "closed", "all"):
+        err_console.print(
+            f"[bold red]Error:[/bold red] Invalid state '{state}'. Must be 'open', 'closed', or 'all'."
+        )
+        raise typer.Exit(code=1)
+
+    # 4. Parse --since filter if supplied
+    since_dt: datetime | None = None
+    if since:
+        try:
+            parsed_date = datetime.strptime(since.strip(), "%Y-%m-%d")
+            since_dt = parsed_date.replace(tzinfo=timezone.utc)
+        except ValueError:
+            err_console.print(
+                f"[bold red]Error:[/bold red] Invalid date format for --since: '{since}'. "
+                "Expected format: YYYY-MM-DD (e.g. 2024-01-01)."
+            )
+            raise typer.Exit(code=1)
+
+    # 5. Run AnalysisEngine
+    engine = AnalysisEngine(repo, provider)
+
+    # Gather repository summary information (needed for both output modes)
+    try:
+        branch = repo.current_branch()
+    except Exception:
+        branch = "detached"
+
+    try:
+        head_commit = repo.head_commit()
+        short_sha = head_commit.short_sha
+    except Exception:
+        short_sha = "unknown"
+
+    repo_info = {
+        "branch": branch,
+        "owner": owner,
+        "remote_url": remote_url,
+        "repo": repo_name,
+        "short_sha": short_sha,
+    }
+
+    t_start = time.perf_counter()
+
+    try:
+        if json_output:
+            # ---- JSON mode: collect all results, serialize at the end ----
+            results = list(engine.analyze_streaming(state=state_normalized))  # type: ignore[arg-type]
+
+            # Apply client-side --since filter
+            if since_dt is not None:
+                results = [r for r in results if r.issue.created_at >= since_dt]
+
+            results.sort(key=lambda r: r.issue.number)
+
+            json_str = to_json(results, repo_info)
+            typer.echo(json_str)
+
+        else:
+            # ---- Terminal mode: stream results with live progress ----
+            out_console = Console()
+            renderer = TerminalRenderer(out_console)
+
+            # Pre-fetch issue count for progress bar (cached after first call)
+            all_issues = provider.get_issues(state=state_normalized)  # type: ignore[arg-type]
+            if since_dt is not None:
+                visible_issues = [i for i in all_issues if i.created_at >= since_dt]
+            else:
+                visible_issues = all_issues
+            total = len(visible_issues)
+
+            renderer.render_header(repo_info, total)
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                TaskProgressColumn(),
+                console=err_console,
+                transient=True,
+            ) as progress:
+                task = progress.add_task("Analyzing issues...", total=total)
+
+                for result in engine.analyze_streaming(state=state_normalized):  # type: ignore[arg-type]
+                    # Apply client-side --since filter
+                    if since_dt is not None and result.issue.created_at < since_dt:
+                        progress.advance(task)
+                        continue
+
+                    progress.advance(task)
+                    renderer.render_result(result)
+
+            renderer.render_footer()
+
+            elapsed = time.perf_counter() - t_start
+            err_console.print(
+                f"[dim]Analysis completed in {elapsed:.1f}s ({len(visible_issues)} issues shown).[/dim]"
+            )
+
+    except RateLimitExceededError as e:
+        reset_info = f" Reset time: {e.reset_at}" if getattr(e, "reset_at", None) else ""
+        err_console.print(
+            f"\n[bold red]GitHub API Rate Limit Exceeded:[/bold red]{reset_info}\n"
+            "To resolve this, set your GitHub personal access token:\n"
+            "  [bold]export GITHUB_TOKEN='ghp_yourTokenHere'[/bold]\n"
+            "Authenticated requests receive 5,000 requests/hour."
+        )
+        raise typer.Exit(code=1)
+    except KeyboardInterrupt:
+        err_console.print("\n[yellow]Analysis interrupted by user.[/yellow]")
+        raise typer.Exit(code=130)
+    except Exception as e:
+        err_console.print(f"[bold red]Analysis failed:[/bold red] {e}")
+        raise typer.Exit(code=1)
+
+
+def main() -> None:
+    """CLI entry point function."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

gitrelevance/config.py

@@ -0,0 +1,27 @@
+"""Configuration and environment loading."""
+
+from __future__ import annotations
+
+import os
+
+try:
+    from dotenv import load_dotenv  # type: ignore[import-not-found]
+
+    # Try loading .env if python-dotenv is installed
+    load_dotenv()
+except ImportError:
+    pass
+
+
+def load_github_token() -> str | None:
+    """Load GitHub Personal Access Token from environment.
+
+    Reads GITHUB_TOKEN environment variable. Returns None if not set.
+
+    Returns:
+        The token string if set in environment, None otherwise.
+    """
+    token = os.getenv("GITHUB_TOKEN")
+    if not token or not token.strip():
+        return None
+    return token.strip()

gitrelevance/git/__init__.py

@@ -0,0 +1,23 @@
+"""Git analysis modules for GitRelevance."""
+
+from gitrelevance.git.commits import Commit
+from gitrelevance.git.files import FileChange
+from gitrelevance.git.repository import GitRepository
+from gitrelevance.git.history import (
+    build_commit_reference_index,
+    commits_referencing,
+    RevertDetector,
+    GitNativeRevertDetector,
+    default_revert_detector,
+)
+
+__all__ = [
+    "Commit",
+    "FileChange",
+    "GitRepository",
+    "build_commit_reference_index",
+    "commits_referencing",
+    "RevertDetector",
+    "GitNativeRevertDetector",
+    "default_revert_detector",
+]

gitrelevance/git/commits.py

@@ -0,0 +1,62 @@
+"""Commit dataclass representing a Git commit."""
+
+from datetime import datetime, timezone
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Commit:
+    """Represents a Git commit with its metadata.
+
+    Attributes:
+        sha: Full commit SHA hash
+        short_sha: Abbreviated SHA (first 7 characters)
+        message: Full commit message
+        author: Author name
+        date: Commit date as timezone-aware datetime
+        files_changed: Tuple of file paths changed in this commit
+    """
+
+    sha: str
+    short_sha: str
+    message: str
+    author: str
+    date: datetime
+    files_changed: tuple[str, ...]
+
+    @classmethod
+    def from_gitpython(cls, git_commit: object) -> "Commit":
+        """Create a Commit from a GitPython Commit object.
+
+        Args:
+            git_commit: A GitPython commit object
+
+        Returns:
+            Commit instance with converted data
+        """
+        # Ensure timezone-aware datetime
+        commit_date = git_commit.committed_date
+        if isinstance(commit_date, (int, float)):
+            dt = datetime.fromtimestamp(commit_date, tz=timezone.utc)
+        elif hasattr(commit_date, "tzinfo"):
+            if commit_date.tzinfo is None:
+                dt = commit_date.replace(tzinfo=timezone.utc)
+            else:
+                dt = commit_date
+        else:
+            dt = datetime.now(tz=timezone.utc)
+
+        # Get files changed via commit stats (works for all commits without extra diff walk)
+        try:
+            files_changed: tuple[str, ...] = tuple(git_commit.stats.files.keys())
+        except Exception:
+            files_changed = ()
+
+        return cls(
+            sha=git_commit.hexsha,
+            short_sha=git_commit.hexsha[:7],
+            message=git_commit.message.rstrip("\n"),
+            author=str(git_commit.author),
+            date=dt,
+            files_changed=files_changed,
+        )