codetour-cli 0.1.0__py3-none-any.whl

codetour_cli/migration/stepwise.py

@@ -0,0 +1,400 @@
+"""
+Step-by-step migration mode: A → B → C (sequential).
+
+Migrates CodeTour steps by replaying commits sequentially, applying
+each commit's changes one at a time. More accurate than direct mode
+for complex refactorings, but slower for long commit histories.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, List, Tuple
+from pathlib import Path
+
+import git
+import structlog
+
+from codetour_cli.migration.direct import DirectMigrator, MigrationResult
+from codetour_cli.migration.git_diff import GitDiffParser
+from codetour_cli.tour.schema import TourStep
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class StepwiseResult:
+    """
+    Result of step-by-step migration with full trace.
+
+    Contains the final migration result plus intermediate steps
+    and comparison with direct mode.
+    """
+
+    # Final result
+    final_result: MigrationResult
+
+    # Intermediate migrations (one per commit)
+    intermediate_results: List[MigrationResult] = field(default_factory=list)
+
+    # Direct mode comparison (for data collection)
+    direct_result: Optional[MigrationResult] = None
+    methods_disagree: bool = False
+
+    # Commit path taken
+    commit_path: List[str] = field(default_factory=list)
+
+    @property
+    def num_steps(self) -> int:
+        """Number of intermediate steps taken."""
+        return len(self.intermediate_results)
+
+    @property
+    def confidence_history(self) -> List[float]:
+        """Confidence at each step."""
+        return [r.confidence for r in self.intermediate_results]
+
+    @property
+    def min_confidence(self) -> float:
+        """Minimum confidence across all steps."""
+        if not self.intermediate_results:
+            return 1.0
+        return min(self.confidence_history)
+
+
+class StepwiseMigrator:
+    """
+    Step-by-step migration engine: A → B → C.
+
+    Migrates tour steps by replaying commits sequentially, tracking
+    line movements through each intermediate state.
+    """
+
+    def __init__(
+        self,
+        repo: git.Repo,
+        source_commit,  # str or git.Commit
+        target_commit,  # str or git.Commit
+        diff_algorithm: str = "histogram",
+        compute_direct_comparison: bool = True
+    ):
+        """
+        Initialize the step-by-step 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')
+            compute_direct_comparison: Also compute direct mode for comparison
+        """
+        self.repo = repo
+
+        # 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.diff_algorithm = diff_algorithm
+        self.compute_direct = compute_direct_comparison
+
+        self.log = logger.bind(
+            source=self.source_commit[:8],
+            target=self.target_commit[:8],
+            mode="stepwise"
+        )
+
+    def _get_commit_path(self) -> List[str]:
+        """
+        Get the sequential path of commits from source to target.
+
+        Returns:
+            List of commit SHAs from source to target (inclusive)
+        """
+        try:
+            # Use git rev-list to get commit path
+            # This gives us A, B1, B2, ..., C in order
+            commits = list(self.repo.iter_commits(
+                f"{self.source_commit}..{self.target_commit}"
+            ))
+
+            # Reverse to get chronological order (oldest to newest)
+            commits.reverse()
+
+            # Convert to SHAs and include source
+            commit_path = [self.source_commit] + [c.hexsha for c in commits]
+
+            self.log.info(
+                "computed_commit_path",
+                num_commits=len(commit_path),
+                path_length=len(commit_path) - 1  # Number of steps
+            )
+
+            return commit_path
+
+        except Exception as e:
+            self.log.error(
+                "failed_to_get_commit_path",
+                error=str(e)
+            )
+            # Fall back to direct path
+            return [self.source_commit, self.target_commit]
+
+    def migrate_step(
+        self,
+        file_path: str,
+        line_number: int,
+        step_id: Optional[int] = None,
+        step: Optional[TourStep] = None
+    ) -> StepwiseResult:
+        """
+        Migrate a single tour step through sequential commits.
+
+        Args:
+            file_path: File path in source commit
+            line_number: Line number in source commit (1-indexed)
+            step_id: Optional step ID for logging
+            step: Optional TourStep for pattern validation
+
+        Returns:
+            StepwiseResult with final location and full trace
+        """
+        log = self.log.bind(
+            file=file_path,
+            line=line_number,
+            step_id=step_id
+        )
+
+        log.info("starting_stepwise_migration")
+
+        # Get commit path
+        commit_path = self._get_commit_path()
+
+        if len(commit_path) < 2:
+            log.warning("commit_path_too_short", path_length=len(commit_path))
+            # Fall back to single direct migration
+            migrator = DirectMigrator(
+                self.repo,
+                self.source_commit,
+                self.target_commit,
+                self.diff_algorithm
+            )
+            final_result = migrator.migrate_step(file_path, line_number, step_id, step)
+            return StepwiseResult(
+                final_result=final_result,
+                commit_path=commit_path
+            )
+
+        # Track current location as we migrate through commits
+        current_file = file_path
+        current_line = line_number
+        intermediate_results = []
+        ever_renamed = False  # Track if file was renamed at any point
+
+        # Migrate through each consecutive pair of commits
+        for i in range(len(commit_path) - 1):
+            commit_a = commit_path[i]
+            commit_b = commit_path[i + 1]
+
+            log.debug(
+                "migrating_step",
+                step=i + 1,
+                total_steps=len(commit_path) - 1,
+                from_commit=commit_a[:8],
+                to_commit=commit_b[:8],
+                current_location=f"{current_file}:{current_line}"
+            )
+
+            # Migrate this single step
+            migrator = DirectMigrator(
+                self.repo,
+                commit_a,
+                commit_b,
+                self.diff_algorithm
+            )
+
+            result = migrator.migrate_step(
+                current_file,
+                current_line,
+                step_id=step_id,
+                step=step
+            )
+
+            intermediate_results.append(result)
+
+            # Track if file was renamed at any point
+            if result.file_renamed:
+                ever_renamed = True
+
+            # Check if migration failed (file deleted, etc.)
+            if not result.success:
+                log.warning(
+                    "migration_failed_at_intermediate_step",
+                    step=i + 1,
+                    reason=result.method,
+                    commit=commit_b[:8]
+                )
+                # Can't continue - return current state
+                return StepwiseResult(
+                    final_result=result,
+                    intermediate_results=intermediate_results,
+                    commit_path=commit_path[:i + 2]  # Up to failure point
+                )
+
+            # Update current location for next iteration
+            current_file = result.new_file
+            current_line = result.new_line
+
+            log.debug(
+                "step_migrated",
+                step=i + 1,
+                new_location=f"{current_file}:{current_line}",
+                confidence=result.confidence,
+                method=result.method
+            )
+
+        # Final result is the last intermediate result
+        final_result = intermediate_results[-1]
+
+        # Compute aggregate confidence (minimum across all steps)
+        min_confidence = min(r.confidence for r in intermediate_results)
+        avg_confidence = sum(r.confidence for r in intermediate_results) / len(intermediate_results)
+
+        # Adjust final confidence based on journey
+        # Use average but flag if any step had low confidence
+        final_result.confidence = avg_confidence
+        if min_confidence < 0.7:
+            final_result.needs_review = True
+            final_result.explanation += f" (min confidence {min_confidence:.2f})"
+
+        # Set file_renamed flag if file was renamed at any point in the journey
+        if ever_renamed:
+            final_result.file_renamed = True
+
+        log.info(
+            "stepwise_migration_complete",
+            final_location=f"{final_result.new_file}:{final_result.new_line}",
+            num_steps=len(intermediate_results),
+            min_confidence=min_confidence,
+            avg_confidence=avg_confidence
+        )
+
+        # Optionally compute direct mode for comparison
+        direct_result = None
+        methods_disagree = False
+
+        if self.compute_direct:
+            direct_migrator = DirectMigrator(
+                self.repo,
+                self.source_commit,
+                self.target_commit,
+                self.diff_algorithm
+            )
+            direct_result = direct_migrator.migrate_step(
+                file_path,
+                line_number,
+                step_id,
+                step
+            )
+
+            # Check if methods disagree
+            if (final_result.new_file != direct_result.new_file or
+                final_result.new_line != direct_result.new_line):
+                methods_disagree = True
+
+                log.warning(
+                    "methods_disagree",
+                    stepwise_result=f"{final_result.new_file}:{final_result.new_line}",
+                    direct_result=f"{direct_result.new_file}:{direct_result.new_line}",
+                    stepwise_confidence=final_result.confidence,
+                    direct_confidence=direct_result.confidence
+                )
+
+                # Lower confidence when methods disagree (per ADR-0001)
+                final_result.confidence *= 0.9
+                final_result.explanation += " (methods disagree)"
+                final_result.needs_review = True
+
+        return StepwiseResult(
+            final_result=final_result,
+            intermediate_results=intermediate_results,
+            direct_result=direct_result,
+            methods_disagree=methods_disagree,
+            commit_path=commit_path
+        )
+
+    def migrate_steps(
+        self,
+        steps: List[Tuple[str, int, int]]
+    ) -> List[StepwiseResult]:
+        """
+        Migrate multiple tour steps through sequential commits.
+
+        Args:
+            steps: List of (file_path, line_number, step_id) tuples
+
+        Returns:
+            List of StepwiseResult objects
+        """
+        self.log.info("migrating_steps_stepwise", 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.final_result.success)
+        disagreements = sum(1 for r in results if r.methods_disagree)
+
+        self.log.info(
+            "stepwise_migration_summary",
+            total=len(results),
+            successful=successful,
+            methods_disagree=disagreements
+        )
+
+        return results
+
+
+def should_use_stepwise(
+    repo: git.Repo,
+    source_commit: str,
+    target_commit: str,
+    threshold: int = 10
+) -> bool:
+    """
+    Determine if step-by-step mode should be used.
+
+    Per ADR-0001, use stepwise if:
+    - Number of commits is small (< threshold, default 10)
+
+    Args:
+        repo: GitPython repository
+        source_commit: Source commit SHA
+        target_commit: Target commit SHA
+        threshold: Commit count threshold (default 10)
+
+    Returns:
+        True if stepwise should be used, False for direct mode
+    """
+    try:
+        # Count commits between source and target
+        commits = list(repo.iter_commits(f"{source_commit}..{target_commit}"))
+        num_commits = len(commits)
+
+        logger.info(
+            "evaluating_migration_mode",
+            num_commits=num_commits,
+            threshold=threshold,
+            recommendation="stepwise" if num_commits < threshold else "direct"
+        )
+
+        return num_commits < threshold
+
+    except Exception as e:
+        logger.error(
+            "failed_to_count_commits",
+            error=str(e)
+        )
+        # Default to direct mode on error
+        return False