gitrelevance 0.1.0__py3-none-any.whl

gitrelevance/__init__.py

@@ -0,0 +1,6 @@
+from gitrelevance.models import AnalysisResult, Classification, EvidenceItem
+
+__version__ = "0.1.0"
+
+__all__ = ["Classification", "EvidenceItem", "AnalysisResult"]
+

gitrelevance/analysis/__init__.py

@@ -0,0 +1,20 @@
+from gitrelevance.analysis.classifier import classify
+from gitrelevance.analysis.confidence import compute_confidence
+from gitrelevance.analysis.current_state import CurrentStateFacts, analyze_current_state
+from gitrelevance.analysis.engine import AnalysisEngine
+from gitrelevance.analysis.evidence import collect_evidence
+from gitrelevance.analysis.matcher import MatchSet, build_all_match_sets, build_match_set
+
+__all__ = [
+    "MatchSet",
+    "build_match_set",
+    "build_all_match_sets",
+    "CurrentStateFacts",
+    "analyze_current_state",
+    "collect_evidence",
+    "compute_confidence",
+    "classify",
+    "AnalysisEngine",
+]
+
+

gitrelevance/analysis/classifier.py

@@ -0,0 +1,59 @@
+"""Classification decision engine for correlating issue relevance."""
+
+from __future__ import annotations
+
+from gitrelevance.analysis.evidence import WEIGHT_FIX_LATER_REVERTED
+from gitrelevance.issues.models import Issue
+from gitrelevance.models import Classification, EvidenceItem
+
+# Threshold constants for classification decisions
+RESOLVED_THRESHOLD = 3
+PROBABLE_THRESHOLD = 2
+OBSOLETE_THRESHOLD = -3
+
+
+def classify(issue: Issue, evidence: tuple[EvidenceItem, ...]) -> Classification:
+    """Classify an issue's current relevance based on collected evidence items.
+
+    Decision Order:
+    1. Strong evidence >= RESOLVED_THRESHOLD and no unresolved revert evidence -> RESOLVED
+    2. Strong evidence >= PROBABLE_THRESHOLD and no unresolved revert evidence -> PROBABLY_RESOLVED
+    3. Obsolescence evidence <= OBSOLETE_THRESHOLD (and no strong fix) -> OBSOLETE
+    4. Open issue with any evidence present -> STILL_RELEVANT
+    5. Fallback -> UNKNOWN (covers no evidence or inconclusive evidence)
+
+    Args:
+        issue: The Issue being classified.
+        evidence: Tuple of collected EvidenceItem instances.
+
+    Returns:
+        Classification decision enum value.
+    """
+    strong_score = sum(item.weight for item in evidence if item.category == "strong")
+    obsolescence_score = sum(item.weight for item in evidence if item.category == "obsolescence")
+
+    has_unresolved_revert = any(
+        item.weight == WEIGHT_FIX_LATER_REVERTED or "reverted" in item.description.lower()
+        for item in evidence
+    )
+
+    # 1. Resolved: Strong evidence threshold met and no fix-revert detected
+    if strong_score >= RESOLVED_THRESHOLD and not has_unresolved_revert:
+        return Classification.RESOLVED
+
+    # 2. Probably Resolved: Moderate strong evidence threshold met and no fix-revert detected
+    if strong_score >= PROBABLE_THRESHOLD and not has_unresolved_revert:
+        return Classification.PROBABLY_RESOLVED
+
+    # 3. Obsolete: Obsolescence evidence threshold met (e.g. deleted files without replacement)
+    # Note: If a fix commit was reverted, it invalidates strong fix evidence. If the issue is closed
+    # and feature code was deleted, it falls into OBSOLETE; otherwise if open, into STILL_RELEVANT.
+    if obsolescence_score <= OBSOLETE_THRESHOLD and not (issue.state == "open" and has_unresolved_revert):
+        return Classification.OBSOLETE
+
+    # 4. Still Relevant: Open issue with active related code or unresolved evidence
+    if issue.state == "open" and len(evidence) > 0:
+        return Classification.STILL_RELEVANT
+
+    # 5. Fallback: Closed issue without fix commits or inconclusive evidence
+    return Classification.UNKNOWN

gitrelevance/analysis/confidence.py

@@ -0,0 +1,41 @@
+"""Confidence score calculation for evidence sets.
+
+Calculates an evidence-strength heuristic score between 0.05 and 0.98.
+Note: This score is a relative evidence-strength heuristic, NOT a calibrated
+statistical probability.
+"""
+
+from __future__ import annotations
+
+from gitrelevance.models import EvidenceItem
+
+# Named constants for normalization and clamping
+MAX_ABS_WEIGHT = 20.0
+MIN_CONFIDENCE = 0.05
+MAX_CONFIDENCE = 0.98
+DEFAULT_CONFIDENCE = 0.50
+
+
+def compute_confidence(evidence: tuple[EvidenceItem, ...]) -> float:
+    """Compute an evidence-strength score normalized and clamped to [0.05, 0.98].
+
+    The formula maps evidence weight sums around a baseline of 0.50:
+        confidence = 0.5 + sum(weights) / (2 * MAX_ABS_WEIGHT)
+
+    If no evidence items exist, returns the default neutral score (0.50).
+
+    Args:
+        evidence: Tuple of EvidenceItem instances.
+
+    Returns:
+        Float confidence score clamped to [MIN_CONFIDENCE, MAX_CONFIDENCE].
+    """
+    if not evidence:
+        return DEFAULT_CONFIDENCE
+
+    total_weight = sum(item.weight for item in evidence)
+    raw_score = 0.5 + (total_weight / (2.0 * MAX_ABS_WEIGHT))
+
+    # Clamp to [MIN_CONFIDENCE, MAX_CONFIDENCE]
+    clamped_score = max(MIN_CONFIDENCE, min(MAX_CONFIDENCE, raw_score))
+    return round(clamped_score, 4)

gitrelevance/analysis/current_state.py

@@ -0,0 +1,98 @@
+"""Current-state analysis helpers for evaluating Git repository status against MatchSets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from gitrelevance.analysis.matcher import MatchSet
+from gitrelevance.git.commits import Commit
+from gitrelevance.git.files import get_file_operations
+from gitrelevance.git.history import default_revert_detector
+from gitrelevance.git.repository import GitRepository
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentStateFacts:
+    """Summarizes current repository state facts for a MatchSet.
+
+    Attributes:
+        fix_commit_in_head: First referencing or PR commit present in HEAD history, or None.
+        all_related_files_exist: True if all related files exist at HEAD (False if empty).
+        deleted_files: Tuple of related file paths that were deleted and do not exist at HEAD.
+        renamed_files: Tuple of (old_path, new_path) rename pairs found for related files.
+        reverts_of_fix: Tuple of commits reverting fix_commit_in_head (empty if no fix commit).
+    """
+
+    fix_commit_in_head: Commit | None
+    all_related_files_exist: bool
+    deleted_files: tuple[str, ...]
+    renamed_files: tuple[tuple[str, str], ...]
+    reverts_of_fix: tuple[Commit, ...]
+
+
+def analyze_current_state(match_set: MatchSet, repo: GitRepository) -> CurrentStateFacts:
+    """Analyze current repository state relative to a MatchSet.
+
+    Args:
+        match_set: The MatchSet containing issue evidence.
+        repo: The local Git repository wrapper.
+
+    Returns:
+        CurrentStateFacts summarizing current HEAD state.
+    """
+    ops = get_file_operations(repo)
+
+    # 1. Determine fix_commit_in_head (ignoring revert commits)
+    fix_commit_in_head: Commit | None = None
+    try:
+        head = repo.head_commit()
+        head_sha = head.sha
+        candidate_commits = list(match_set.referencing_commits) + list(match_set.pr_commits)
+        for commit in candidate_commits:
+            # Skip revert commits when looking for the fix commit
+            if "This reverts commit " in commit.message:
+                continue
+            if repo.is_ancestor(commit.sha, head_sha):
+                fix_commit_in_head = commit
+                break
+    except Exception:
+        fix_commit_in_head = None
+
+    # 2. Renamed files and deleted files
+    renamed: list[tuple[str, str]] = []
+    seen_renames: set[tuple[str, str]] = set()
+
+    for path in match_set.related_files:
+        renames_for_path = ops.find_renames(path)
+        for pair in renames_for_path:
+            if pair not in seen_renames:
+                seen_renames.add(pair)
+                renamed.append(pair)
+
+    deleted: list[str] = []
+    for path in match_set.related_files:
+        if not ops.file_exists_at_head(path):
+            # A file is considered deleted only if it does not exist at HEAD,
+            # was marked as deleted/historical, and was NOT renamed.
+            if ops.was_file_deleted(path) and not ops.find_renames(path):
+                deleted.append(path)
+
+    # 3. all_related_files_exist
+    if not match_set.related_files:
+        all_exist = False
+    else:
+        all_exist = all(ops.file_exists_at_head(path) for path in match_set.related_files)
+
+    # 4. Reverts of fix commit
+    reverts: list[Commit] = []
+    if fix_commit_in_head is not None:
+        detector = default_revert_detector()
+        reverts = detector.find_reverts_of(repo, fix_commit_in_head.sha)
+
+    return CurrentStateFacts(
+        fix_commit_in_head=fix_commit_in_head,
+        all_related_files_exist=all_exist,
+        deleted_files=tuple(deleted),
+        renamed_files=tuple(renamed),
+        reverts_of_fix=tuple(reverts),
+    )

gitrelevance/analysis/engine.py

@@ -0,0 +1,181 @@
+"""AnalysisEngine for orchestrating Git and Provider analysis."""
+
+from __future__ import annotations
+
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Iterator, Literal
+
+from gitrelevance.analysis.confidence import compute_confidence
+from gitrelevance.analysis.current_state import analyze_current_state
+from gitrelevance.analysis.evidence import collect_evidence
+from gitrelevance.analysis.classifier import classify
+from gitrelevance.analysis.matcher import MatchSet, build_all_match_sets
+from gitrelevance.git.history import build_commit_reference_index
+from gitrelevance.git.repository import GitRepository
+from gitrelevance.models import AnalysisResult
+from gitrelevance.providers.base import Provider
+
+logger = logging.getLogger(__name__)
+
+# Default number of worker threads for parallel per-issue analysis.
+# Conservative to avoid overwhelming git subprocess and GitHub API.
+DEFAULT_MAX_WORKERS = 8
+
+
+class AnalysisEngine:
+    """Orchestrates end-to-end analysis of issues against Git repository state.
+
+    Attributes:
+        repo: Local Git repository wrapper.
+        provider: Issue tracker provider instance.
+    """
+
+    def __init__(self, repo: GitRepository, provider: Provider) -> None:
+        """Initialize the AnalysisEngine.
+
+        Args:
+            repo: GitRepository instance.
+            provider: Provider instance implementing the Provider protocol.
+        """
+        self.repo = repo
+        self.provider = provider
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _analyze_single_issue(
+        issue,  # Issue (avoiding import for circular reasons in staticmethod)
+        match_set: MatchSet,
+        repo: GitRepository,
+    ) -> AnalysisResult:
+        """Compute the AnalysisResult for a single issue (CPU/git-bound).
+
+        This is the per-issue hot path factored out so it can be called from
+        a worker thread.
+        """
+        facts = analyze_current_state(match_set, repo)
+        evidence = collect_evidence(match_set, facts)
+        confidence = compute_confidence(evidence)
+        classification = classify(issue, evidence)
+        return AnalysisResult(
+            issue=issue,
+            classification=classification,
+            confidence=confidence,
+            evidence=evidence,
+        )
+
+    def _prepare(
+        self, state: Literal["open", "closed", "all"]
+    ) -> tuple[list, dict[int, MatchSet], float]:
+        """Fetch issues & PRs and build match sets (I/O-bound phase).
+
+        Also ensures the commit-reference index is built once up-front so
+        every subsequent per-issue lookup is a dict hit.
+
+        Returns:
+            (issues_sorted, match_sets, elapsed_seconds)
+        """
+        t0 = time.perf_counter()
+
+        logger.info("Fetching issues (state=%s)...", state)
+        issues = self.provider.get_issues(state=state)
+        issues_sorted = sorted(issues, key=lambda i: i.number)
+        logger.info("Found %d issues to analyze.", len(issues_sorted))
+
+        logger.info("Fetching pull requests and building correlation match sets...")
+        match_sets = build_all_match_sets(issues_sorted, self.repo, self.provider)
+        logger.info("Correlation match sets built for %d issues.", len(match_sets))
+
+        # Build the commit-reference index once so per-issue lookups are instant
+        logger.info("Building commit-reference index...")
+        build_commit_reference_index(self.repo)
+
+        elapsed = time.perf_counter() - t0
+        logger.info("Preparation (issues + PRs + match sets) took %.2fs.", elapsed)
+        return issues_sorted, match_sets, elapsed
+
+    # ------------------------------------------------------------------
+    # Streaming generator (Goal 1 + Goal 2)
+    # ------------------------------------------------------------------
+
+    def analyze_streaming(
+        self,
+        state: Literal["open", "closed", "all"] = "all",
+        max_workers: int = DEFAULT_MAX_WORKERS,
+    ) -> Iterator[AnalysisResult]:
+        """Yield AnalysisResult objects as each issue finishes processing.
+
+        Issues are analysed concurrently via a thread pool (git subprocess
+        calls release the GIL). Results are yielded in completion order
+        (not issue-number order) for minimum latency.
+
+        Args:
+            state: Issue state filter.
+            max_workers: Maximum concurrent worker threads.
+
+        Yields:
+            AnalysisResult for each issue, as soon as it is ready.
+        """
+        issues_sorted, match_sets, _prep_elapsed = self._prepare(state)
+        total = len(issues_sorted)
+
+        if total == 0:
+            logger.info("No issues to analyze.")
+            return
+
+        logger.info(
+            "Analyzing %d issues in parallel (max_workers=%d)...",
+            total,
+            max_workers,
+        )
+        t_analysis = time.perf_counter()
+
+        def _process(issue):
+            return self._analyze_single_issue(issue, match_sets[issue.number], self.repo)
+
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            future_to_issue = {
+                executor.submit(_process, issue): issue for issue in issues_sorted
+            }
+            completed = 0
+            for future in as_completed(future_to_issue):
+                result = future.result()  # propagates exceptions
+                completed += 1
+                logger.debug(
+                    "Completed issue #%d (%d/%d)",
+                    result.issue.number,
+                    completed,
+                    total,
+                )
+                yield result
+
+        elapsed_analysis = time.perf_counter() - t_analysis
+        logger.info(
+            "Analysis completed for %d issues in %.2fs.",
+            total,
+            elapsed_analysis,
+        )
+
+    # ------------------------------------------------------------------
+    # Legacy batch API (backward-compatible)
+    # ------------------------------------------------------------------
+
+    def analyze(self, state: Literal["open", "closed", "all"] = "all") -> list[AnalysisResult]:
+        """Analyze repository issues for relevance against local Git history.
+
+        Collects all results from the streaming generator and returns them
+        sorted by issue number for backward compatibility.
+
+        Args:
+            state: Issue state filter ("open", "closed", or "all").
+
+        Returns:
+            List of AnalysisResult objects sorted by issue number.
+        """
+        results = list(self.analyze_streaming(state=state))
+        results.sort(key=lambda r: r.issue.number)
+        return results

gitrelevance/analysis/evidence.py

@@ -0,0 +1,187 @@
+"""Evidence collection rules and weights for issue analysis."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from gitrelevance.analysis.current_state import CurrentStateFacts
+from gitrelevance.analysis.matcher import MatchSet
+from gitrelevance.models import EvidenceItem
+
+# Weight constants for scoring
+WEIGHT_ISSUE_REFERENCED_BY_FIX_COMMIT = 3
+WEIGHT_FIX_COMMIT_IN_HEAD = 3
+WEIGHT_FIXING_PR_MERGED = 2
+WEIGHT_FILES_STILL_EXIST = 2
+WEIGHT_NO_REVERT_DETECTED = 1
+WEIGHT_ISSUE_NUM_IN_COMMIT_MSG = 1
+WEIGHT_FILES_SUBSTANTIALLY_MODIFIED = 1
+WEIGHT_FILES_DELETED_NO_REPLACEMENT = -3
+WEIGHT_FEATURE_NO_LONGER_PRESENT = -2
+WEIGHT_FIX_LATER_REVERTED = -3
+
+
+def check_fix_in_head(match_set: MatchSet, facts: CurrentStateFacts) -> EvidenceItem | None:
+    """Check if the fix commit is present in HEAD ancestry."""
+    if facts.fix_commit_in_head is not None:
+        return EvidenceItem(
+            description="Fix commit is present in HEAD history",
+            weight=WEIGHT_FIX_COMMIT_IN_HEAD,
+            category="strong",
+            source_ref=facts.fix_commit_in_head.short_sha,
+        )
+    return None
+
+
+def check_pr_merged(match_set: MatchSet, facts: CurrentStateFacts) -> EvidenceItem | None:
+    """Check if any linked pull request was merged."""
+    for pr in match_set.linked_prs:
+        if pr.merged:
+            return EvidenceItem(
+                description=f"Fixing PR #{pr.number} merged",
+                weight=WEIGHT_FIXING_PR_MERGED,
+                category="strong",
+                source_ref=f"PR #{pr.number}",
+            )
+    return None
+
+
+def check_issue_referenced_by_fix_commit(
+    match_set: MatchSet, facts: CurrentStateFacts
+) -> EvidenceItem | None:
+    """Check if commits directly reference the issue."""
+    if match_set.referencing_commits:
+        commit = match_set.referencing_commits[0]
+        return EvidenceItem(
+            description="Issue referenced in commit message",
+            weight=WEIGHT_ISSUE_REFERENCED_BY_FIX_COMMIT,
+            category="strong",
+            source_ref=commit.short_sha,
+        )
+    return None
+
+
+def check_files_exist(match_set: MatchSet, facts: CurrentStateFacts) -> EvidenceItem | None:
+    """Check if all related files exist at HEAD."""
+    if facts.all_related_files_exist and match_set.related_files:
+        return EvidenceItem(
+            description="All related files exist at HEAD",
+            weight=WEIGHT_FILES_STILL_EXIST,
+            category="medium",
+            source_ref=None,
+        )
+    return None
+
+
+def check_no_revert(match_set: MatchSet, facts: CurrentStateFacts) -> EvidenceItem | None:
+    """Check if no revert commit was detected for the fix commit."""
+    if facts.fix_commit_in_head is not None and not facts.reverts_of_fix:
+        return EvidenceItem(
+            description="No revert of fix commit detected",
+            weight=WEIGHT_NO_REVERT_DETECTED,
+            category="medium",
+            source_ref=facts.fix_commit_in_head.short_sha,
+        )
+    return None
+
+
+def check_issue_num_in_commit_msg(
+    match_set: MatchSet, facts: CurrentStateFacts
+) -> EvidenceItem | None:
+    """Check if issue number is mentioned in commit message."""
+    if match_set.referencing_commits:
+        commit = match_set.referencing_commits[0]
+        return EvidenceItem(
+            description="Issue number mentioned in commit message",
+            weight=WEIGHT_ISSUE_NUM_IN_COMMIT_MSG,
+            category="medium",
+            source_ref=commit.short_sha,
+        )
+    return None
+
+
+def check_files_substantially_modified(
+    match_set: MatchSet, facts: CurrentStateFacts
+) -> EvidenceItem | None:
+    """Check if related files were renamed or substantially modified."""
+    if facts.renamed_files:
+        return EvidenceItem(
+            description=f"Files modified or renamed ({len(facts.renamed_files)} renamed)",
+            weight=WEIGHT_FILES_SUBSTANTIALLY_MODIFIED,
+            category="medium",
+            source_ref=None,
+        )
+    return None
+
+
+def check_files_deleted(match_set: MatchSet, facts: CurrentStateFacts) -> EvidenceItem | None:
+    """Check if related files were deleted without replacement."""
+    if facts.deleted_files:
+        files_str = ", ".join(facts.deleted_files)
+        return EvidenceItem(
+            description=f"Related files deleted without replacement: {files_str}",
+            weight=WEIGHT_FILES_DELETED_NO_REPLACEMENT,
+            category="obsolescence",
+            source_ref=None,
+        )
+    return None
+
+
+def check_feature_no_longer_present(
+    match_set: MatchSet, facts: CurrentStateFacts
+) -> EvidenceItem | None:
+    """Check if feature code was deleted and issue closed without a fix commit."""
+    if match_set.issue.state == "closed" and facts.fix_commit_in_head is None and facts.deleted_files:
+        return EvidenceItem(
+            description="Feature files deleted and issue closed without fix commit",
+            weight=WEIGHT_FEATURE_NO_LONGER_PRESENT,
+            category="obsolescence",
+            source_ref=None,
+        )
+    return None
+
+
+def check_revert_of_fix(match_set: MatchSet, facts: CurrentStateFacts) -> EvidenceItem | None:
+    """Check if the fix commit was later reverted."""
+    if facts.reverts_of_fix:
+        revert_commit = facts.reverts_of_fix[0]
+        return EvidenceItem(
+            description=f"Fix commit was reverted by {revert_commit.short_sha}",
+            weight=WEIGHT_FIX_LATER_REVERTED,
+            category="obsolescence",
+            source_ref=revert_commit.short_sha,
+        )
+    return None
+
+
+# Registered list of evidence rules
+ALL_RULES: list[Callable[[MatchSet, CurrentStateFacts], EvidenceItem | None]] = [
+    check_fix_in_head,
+    check_pr_merged,
+    check_issue_referenced_by_fix_commit,
+    check_files_exist,
+    check_no_revert,
+    check_issue_num_in_commit_msg,
+    check_files_substantially_modified,
+    check_files_deleted,
+    check_feature_no_longer_present,
+    check_revert_of_fix,
+]
+
+
+def collect_evidence(match_set: MatchSet, facts: CurrentStateFacts) -> tuple[EvidenceItem, ...]:
+    """Collect all applicable evidence items for a given MatchSet and CurrentStateFacts.
+
+    Args:
+        match_set: The MatchSet containing issue correlation data.
+        facts: CurrentStateFacts describing repository state.
+
+    Returns:
+        Tuple of collected EvidenceItem instances.
+    """
+    items: list[EvidenceItem] = []
+    for rule in ALL_RULES:
+        item = rule(match_set, facts)
+        if item is not None:
+            items.append(item)
+    return tuple(items)