codetour-cli 0.1.0__py3-none-any.whl

codetour_cli/migration/direct.py

@@ -0,0 +1,385 @@
+"""
+Direct migration mode: A → C (single jump).
+
+Migrates CodeTour steps directly from source commit to target commit
+without replaying intermediate commits.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Dict, List
+from pathlib import Path
+
+import git
+import structlog
+
+from codetour_cli.migration.git_diff import (
+    GitDiffParser,
+    FileDiff,
+    HunkHeader,
+    LineMapping
+)
+from codetour_cli.tour.schema import TourStep
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class MigrationResult:
+    """
+    Result of migrating a single tour step.
+
+    Contains the updated location and metadata about the migration.
+    """
+
+    # Original location
+    old_file: str
+    old_line: int
+
+    # New location (None if file deleted)
+    new_file: Optional[str]
+    new_line: Optional[int]
+
+    # Migration metadata
+    confidence: float  # 0.0-1.0
+    method: str  # 'hunk_offset', 'hunk_interior', 'file_renamed', 'file_deleted', etc.
+    explanation: str
+
+    # Flags
+    file_renamed: bool = False
+    file_deleted: bool = False
+    needs_review: bool = False
+
+    @property
+    def success(self) -> bool:
+        """Was the migration successful?"""
+        return not self.file_deleted and self.new_line is not None
+
+    @property
+    def deprecated(self) -> bool:
+        """Should this step be marked as deprecated?"""
+        return self.file_deleted or self.new_line is None
+
+
+class DirectMigrator:
+    """
+    Direct migration engine: A → C.
+
+    Migrates tour steps from source commit to target commit in a single jump.
+    Uses Git diff analysis to track line movements.
+    """
+
+    def __init__(
+        self,
+        repo: git.Repo,
+        source_commit,  # str or git.Commit
+        target_commit,  # str or git.Commit
+        diff_algorithm: str = "histogram",
+        threshold: float = 0.7
+    ):
+        """
+        Initialize the direct migrator.
+
+        Args:
+            repo: GitPython repository object
+            source_commit: Source commit SHA or Commit object
+            target_commit: Target commit SHA or Commit object
+            diff_algorithm: Git diff algorithm ('myers', 'patience', 'histogram')
+            threshold: confidence cutoff for needs_review. Previously hardcoded
+                and disconnected from config/--threshold (ADR-0016 QST-CONF-2);
+                now the real configured value flows here. Per ADR-0016's own
+                finding, only values <=0.5 or >0.95 change anything, since
+                confidence never takes any other value -- this is a discrete
+                classifier, not a continuous score.
+        """
+        self.repo = repo
+        self.threshold = threshold
+
+        # Convert Commit objects to strings
+        self.source_commit = (source_commit.hexsha if hasattr(source_commit, 'hexsha')
+                             else source_commit)
+        self.target_commit = (target_commit.hexsha if hasattr(target_commit, 'hexsha')
+                             else target_commit)
+
+        self.parser = GitDiffParser(repo, algorithm=diff_algorithm)
+        self.log = logger.bind(
+            source=self.source_commit[:8],
+            target=self.target_commit[:8]
+        )
+
+        # Cache file diffs (computed once for all steps)
+        self._file_diffs: Optional[Dict[str, FileDiff]] = None
+
+    def _get_file_diffs(self) -> Dict[str, FileDiff]:
+        """Get all file diffs (cached)."""
+        if self._file_diffs is None:
+            self.log.info("computing_file_diffs")
+            self._file_diffs = self.parser.get_all_file_diffs(
+                self.source_commit,
+                self.target_commit
+            )
+            self.log.info(
+                "file_diffs_computed",
+                num_files=len(self._file_diffs)
+            )
+        return self._file_diffs
+
+    def _get_line_content(
+        self,
+        file_path: str,
+        line_number: int,
+        commit
+    ) -> Optional[str]:
+        """
+        Get the content of a specific line at a given commit.
+
+        Args:
+            file_path: File path relative to repo root
+            line_number: Line number (1-indexed)
+            commit: Commit SHA or object
+
+        Returns:
+            Line content (without newline), or None if error
+        """
+        try:
+            commit_obj = self.repo.commit(commit)
+            blob = commit_obj.tree / file_path
+            content = blob.data_stream.read().decode('utf-8')
+            lines = content.splitlines()
+
+            if 1 <= line_number <= len(lines):
+                return lines[line_number - 1]  # Convert to 0-indexed
+            return None
+        except Exception as e:
+            self.log.debug(
+                "failed_to_get_line_content",
+                file=file_path,
+                line=line_number,
+                error=str(e)
+            )
+            return None
+
+    def migrate_step(
+        self,
+        file_path: str,
+        line_number: int,
+        step_id: Optional[int] = None,
+        step: Optional[TourStep] = None
+    ) -> MigrationResult:
+        """
+        Migrate a single tour step from source to target commit.
+
+        Args:
+            file_path: File path in source commit
+            line_number: Line number in source commit (1-indexed)
+            step_id: Optional step ID for logging
+
+        Returns:
+            MigrationResult with new location and metadata
+        """
+        log = self.log.bind(
+            file=file_path,
+            line=line_number,
+            step_id=step_id
+        )
+
+        log.debug("migrating_step")
+
+        # Get all file diffs
+        all_diffs = self._get_file_diffs()
+
+        # Check if file was renamed or deleted
+        file_diff = None
+        new_file_path = file_path
+
+        # Look for the file in the diffs
+        # Could be under new path (if renamed) or old path
+        if file_path in all_diffs:
+            file_diff = all_diffs[file_path]
+
+            # If renamed, update the path
+            if file_diff.is_renamed and file_diff.new_path:
+                new_file_path = file_diff.new_path
+                log.info(
+                    "file_renamed",
+                    old_path=file_path,
+                    new_path=new_file_path
+                )
+        else:
+            # File might have been renamed - check all diffs for old_path match
+            for path, diff in all_diffs.items():
+                if diff.is_renamed and diff.old_path == file_path:
+                    file_diff = diff
+                    new_file_path = diff.new_path or file_path
+                    log.info(
+                        "file_renamed_found",
+                        old_path=file_path,
+                        new_path=new_file_path
+                    )
+                    break
+
+        # Handle file deletion
+        if file_diff and file_diff.is_deleted:
+            log.warning("file_deleted")
+            return MigrationResult(
+                old_file=file_path,
+                old_line=line_number,
+                new_file=None,
+                new_line=None,
+                confidence=0.0,
+                method='file_deleted',
+                explanation=f'File {file_path} was deleted',
+                file_deleted=True,
+                needs_review=True
+            )
+
+        # If no diff found, file is unchanged
+        if file_diff is None:
+            log.debug("file_unchanged")
+            return MigrationResult(
+                old_file=file_path,
+                old_line=line_number,
+                new_file=file_path,
+                new_line=line_number,
+                confidence=1.0,
+                method='no_changes',
+                explanation='File unchanged between commits',
+                file_renamed=False
+            )
+
+        # Map the line through hunks
+        mapping = self.parser.map_line_through_hunks(line_number, file_diff.hunks)
+
+        log.info(
+            "line_mapped",
+            new_line=mapping.new_line,
+            confidence=mapping.confidence,
+            method=mapping.method
+        )
+
+        # Pattern validation (if step provided with pattern)
+        confidence = mapping.confidence
+        method = mapping.method
+        explanation = mapping.explanation
+
+        if step and step.pattern and mapping.new_line is not None and new_file_path:
+            # Get actual content at new location
+            actual_content = self._get_line_content(
+                new_file_path,
+                mapping.new_line,
+                self.target_commit
+            )
+
+            if actual_content is not None:
+                pattern_matches = step.validate_line_content(actual_content)
+
+                if pattern_matches:
+                    # Pattern validates the migration!
+                    if confidence == 0.5:  # hunk_interior
+                        confidence = 0.95  # Boost to high confidence
+                        method += "_pattern_validated"
+                        explanation += " (pattern validated)"
+                        log.info(
+                            "pattern_validated",
+                            file=new_file_path,
+                            line=mapping.new_line,
+                            pattern=step.pattern,
+                            confidence_boost="0.5 → 0.95"
+                        )
+                else:
+                    # Pattern doesn't match - lower confidence
+                    confidence = min(confidence, 0.4)
+                    explanation += " (pattern mismatch)"
+                    log.warning(
+                        "pattern_mismatch",
+                        file=new_file_path,
+                        line=mapping.new_line,
+                        pattern=step.pattern,
+                        actual_content=actual_content[:50]  # First 50 chars
+                    )
+
+        # Determine if needs review
+        needs_review = (
+            confidence < self.threshold or  # Low confidence (ADR-0016 QST-CONF-2:
+                                             # now the real configured value, not
+                                             # a hardcoded 0.7 disconnected from it)
+            method == 'hunk_interior'  # Inside changed region (unless validated)
+        )
+
+        return MigrationResult(
+            old_file=file_path,
+            old_line=line_number,
+            new_file=new_file_path,
+            new_line=mapping.new_line,
+            confidence=confidence,
+            method=method,
+            explanation=explanation,
+            file_renamed=file_diff.is_renamed,
+            needs_review=needs_review
+        )
+
+    def migrate_steps(
+        self,
+        steps: List[tuple]
+    ) -> List[MigrationResult]:
+        """
+        Migrate multiple tour steps.
+
+        Args:
+            steps: List of (file_path, line_number, step_id) tuples
+
+        Returns:
+            List of MigrationResult objects
+        """
+        self.log.info("migrating_steps", num_steps=len(steps))
+
+        results = []
+        for file_path, line_number, step_id in steps:
+            result = self.migrate_step(file_path, line_number, step_id)
+            results.append(result)
+
+        # Log summary
+        successful = sum(1 for r in results if r.success)
+        deprecated = sum(1 for r in results if r.deprecated)
+        needs_review = sum(1 for r in results if r.needs_review)
+
+        self.log.info(
+            "migration_summary",
+            total=len(results),
+            successful=successful,
+            deprecated=deprecated,
+            needs_review=needs_review
+        )
+
+        return results
+
+
+def migrate_tour(
+    repo_path: Path,
+    source_commit: str,
+    target_commit: str,
+    tour_steps: List[Dict],
+    diff_algorithm: str = "histogram"
+) -> List[MigrationResult]:
+    """
+    Convenience function to migrate a full tour.
+
+    Args:
+        repo_path: Path to Git repository
+        source_commit: Source commit SHA
+        target_commit: Target commit SHA
+        tour_steps: List of tour step dicts with 'file' and 'line' keys
+        diff_algorithm: Git diff algorithm to use
+
+    Returns:
+        List of MigrationResult objects
+    """
+    repo = git.Repo(repo_path)
+    migrator = DirectMigrator(repo, source_commit, target_commit, diff_algorithm)
+
+    # Convert tour steps to tuples
+    steps = [
+        (step.get('file'), step.get('line'), step.get('id', idx))
+        for idx, step in enumerate(tour_steps)
+    ]
+
+    return migrator.migrate_steps(steps)