codetour-cli 0.1.0__py3-none-any.whl

codetour_cli/tour/schema.py

@@ -0,0 +1,255 @@
+"""
+CodeTour schema definitions using Pydantic.
+
+Based on the CodeTour specification:
+https://github.com/microsoft/codetour
+
+A tour is a JSON file (.tour) containing:
+- Metadata (title, description, ref commit)
+- Steps (file, line, description, optional pattern)
+"""
+
+from typing import Optional, List, Literal
+from pydantic import BaseModel, Field, ConfigDict
+from pathlib import Path
+import json
+import re
+
+
+class TourStep(BaseModel):
+    """
+    A single step in a CodeTour.
+
+    Steps can reference code by:
+    - file + line (most common)
+    - file + pattern (regex, mutually exclusive with line)
+    - Just description (no code reference)
+    """
+
+    model_config = ConfigDict(extra='allow')  # Allow extra fields for future compatibility
+
+    # Core fields
+    file: Optional[str] = None  # Relative path from workspace root
+    line: Optional[int] = None  # Line number (1-indexed)
+    description: str  # Markdown description shown to user
+
+    # Optional fields
+    pattern: Optional[str] = None  # Regex pattern (mutually exclusive with line)
+    title: Optional[str] = None  # Optional step title
+    directory: Optional[str] = None  # For directory-only steps
+    uri: Optional[str] = None  # Full URI (for non-file resources)
+
+    # Selection range (for highlighting multiple lines)
+    selection: Optional[dict] = None  # {start: {line, character}, end: {line, character}}
+
+    # Commands to execute
+    commands: Optional[List[str]] = None
+
+    def has_line_reference(self) -> bool:
+        """Does this step reference a specific line?"""
+        return self.file is not None and self.line is not None
+
+    def has_pattern_reference(self) -> bool:
+        """Does this step use a regex pattern?"""
+        return self.file is not None and self.pattern is not None
+
+    def has_code_reference(self) -> bool:
+        """Does this step reference any code location?"""
+        return self.has_line_reference() or self.has_pattern_reference()
+
+    def validate_line_content(self, content: str) -> bool:
+        """
+        Validate that line content matches the step's pattern.
+
+        Used for confidence validation - if a step has a pattern,
+        we can check that the migrated line still matches it.
+
+        Args:
+            content: The actual line content from the file
+
+        Returns:
+            True if no pattern, or pattern matches content
+        """
+        if not self.pattern:
+            return True  # No pattern = always valid
+
+        try:
+            return bool(re.search(self.pattern, content))
+        except re.error:
+            # Invalid regex pattern - treat as no match
+            return False
+
+
+class Tour(BaseModel):
+    """
+    A complete CodeTour.
+
+    Contains metadata and a sequence of steps guiding through code.
+    """
+
+    model_config = ConfigDict(extra='allow')
+
+    # Schema reference (optional, used by VS Code)
+    schema_: Optional[str] = Field(None, alias='$schema')
+
+    # Required fields
+    title: str  # Tour title
+    steps: List[TourStep]  # Ordered list of steps
+
+    # Optional metadata
+    description: Optional[str] = None  # Tour description
+    ref: Optional[str] = None  # Git commit SHA this tour targets
+    isPrimary: Optional[bool] = None  # Is this the primary tour for the repo?
+    nextTour: Optional[str] = None  # Path to next tour in sequence
+
+    # Migration metadata (our additions for tracking tour migrations)
+    original_ref: Optional[str] = Field(None, alias='originalRef')  # Original commit before migration
+    migration_log: Optional[List[dict]] = Field(None, alias='migrationLog')  # Migration history
+
+    @property
+    def num_steps(self) -> int:
+        """Number of steps in this tour."""
+        return len(self.steps)
+
+    @property
+    def has_ref(self) -> bool:
+        """Does this tour have a target commit?"""
+        return self.ref is not None
+
+    def steps_with_line_refs(self) -> List[tuple]:
+        """
+        Get all steps that have line references.
+
+        Returns:
+            List of (index, step) tuples for steps with file+line
+        """
+        return [
+            (idx, step)
+            for idx, step in enumerate(self.steps)
+            if step.has_line_reference()
+        ]
+
+    def to_json(self, **kwargs) -> str:
+        """Serialize tour to JSON string."""
+        return self.model_dump_json(
+            exclude_none=True,
+            by_alias=True,
+            indent=2,
+            **kwargs
+        )
+
+    def to_dict(self) -> dict:
+        """Convert tour to dictionary."""
+        return self.model_dump(exclude_none=True, by_alias=True)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "Tour":
+        """Parse tour from JSON string."""
+        return cls.model_validate_json(json_str)
+
+    @classmethod
+    def from_file(cls, path: Path) -> "Tour":
+        """Load tour from .tour file."""
+        return cls.model_validate_json(path.read_text())
+
+    def save(self, path: Path) -> None:
+        """Save tour to .tour file."""
+        path.write_text(self.to_json())
+
+
+class TourCollection(BaseModel):
+    """
+    Collection of tours in a workspace.
+
+    The .tours directory contains multiple .tour files.
+    """
+
+    tours: List[tuple]  # List of (filename, Tour) pairs
+    workspace_path: Path
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @classmethod
+    def from_directory(cls, tours_dir: Path) -> "TourCollection":
+        """
+        Load all tours from a .tours directory.
+
+        Args:
+            tours_dir: Path to .tours directory
+
+        Returns:
+            TourCollection with all loaded tours
+        """
+        tours = []
+        for tour_file in sorted(tours_dir.glob("*.tour")):
+            try:
+                tour = Tour.from_file(tour_file)
+                tours.append((tour_file.name, tour))
+            except Exception as e:
+                # Log error but continue loading other tours
+                print(f"Warning: Failed to load {tour_file.name}: {e}")
+
+        return cls(
+            tours=tours,
+            workspace_path=tours_dir.parent
+        )
+
+    def save_all(self, tours_dir: Path) -> None:
+        """
+        Save all tours back to directory.
+
+        Args:
+            tours_dir: Path to .tours directory
+        """
+        tours_dir.mkdir(exist_ok=True)
+
+        for filename, tour in self.tours:
+            tour_path = tours_dir / filename
+            tour.save(tour_path)
+
+    def get_tour(self, filename: str) -> Optional[Tour]:
+        """Get a tour by filename."""
+        for name, tour in self.tours:
+            if name == filename:
+                return tour
+        return None
+
+
+def create_example_tour() -> Tour:
+    """
+    Create an example tour for testing/documentation.
+
+    Returns:
+        A sample Tour object
+    """
+    return Tour(
+        title="Introduction to the Codebase",
+        description="A guided tour through the main components",
+        ref="abc123def456",  # Git commit SHA
+        steps=[
+            TourStep(
+                file="src/main.py",
+                line=1,
+                description="# Welcome!\n\nThis is the main entry point."
+            ),
+            TourStep(
+                file="src/core/engine.py",
+                line=42,
+                description="The core processing engine starts here."
+            ),
+            TourStep(
+                file="src/utils/helpers.py",
+                pattern=r"def process_data\(",
+                description="Helper functions for data processing"
+            ),
+            TourStep(
+                description="# That's it!\n\nYou've completed the tour."
+            )
+        ]
+    )
+
+
+if __name__ == "__main__":
+    # Example usage
+    tour = create_example_tour()
+    print(tour.to_json())

codetour_cli/tour/updater.py

@@ -0,0 +1,428 @@
+"""
+Tour updater - applies migrations to CodeTour files.
+
+This module connects the migration engine to actual .tour files,
+updating step locations when code changes.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional
+from pathlib import Path
+from datetime import datetime
+
+import git
+import structlog
+
+from codetour_cli.tour.schema import Tour, TourStep
+from codetour_cli.migration.direct import DirectMigrator, MigrationResult
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class StepUpdate:
+    """
+    Record of a single step update.
+
+    Tracks what changed for each tour step during migration.
+    """
+
+    step_index: int
+    old_location: str  # "file.py:42"
+    new_location: Optional[str]  # "file.py:45" or None if deprecated
+
+    migration_result: MigrationResult
+
+    @property
+    def was_updated(self) -> bool:
+        """Did the location change?"""
+        return self.old_location != self.new_location
+
+    @property
+    def needs_review(self) -> bool:
+        """Should this update be reviewed by user?"""
+        return self.migration_result.needs_review
+
+    @property
+    def deprecated(self) -> bool:
+        """Was this step deprecated (file deleted)?"""
+        return self.migration_result.deprecated
+
+
+@dataclass
+class TourUpdateResult:
+    """
+    Result of updating an entire tour.
+
+    Contains the updated tour and metadata about changes.
+    """
+
+    tour: Tour
+    updates: List[StepUpdate]
+
+    source_commit: str
+    target_commit: str
+    timestamp: datetime
+
+    @property
+    def num_updated(self) -> int:
+        """Number of steps that changed location."""
+        return sum(1 for u in self.updates if u.was_updated)
+
+    @property
+    def num_deprecated(self) -> int:
+        """Number of steps marked as deprecated."""
+        return sum(1 for u in self.updates if u.deprecated)
+
+    @property
+    def num_needs_review(self) -> int:
+        """Number of steps that need manual review."""
+        return sum(1 for u in self.updates if u.needs_review)
+
+    @property
+    def all_successful(self) -> bool:
+        """Were all migrations successful (no deprecated steps)?"""
+        return self.num_deprecated == 0
+
+
+class TourUpdater:
+    """
+    Updates CodeTour files by migrating steps through git commits.
+
+    Uses DirectMigrator to track line movements, then updates
+    the tour file with new locations.
+    """
+
+    def __init__(
+        self,
+        repo: git.Repo,
+        diff_algorithm: str = "histogram",
+        threshold: float = 0.7
+    ):
+        """
+        Initialize the tour updater.
+
+        Args:
+            repo: GitPython repository object
+            diff_algorithm: Git diff algorithm to use
+            threshold: confidence cutoff passed through to DirectMigrator
+                (ADR-0016 QST-CONF-2 -- previously never reached the scorer)
+        """
+        self.repo = repo
+        self.diff_algorithm = diff_algorithm
+        self.threshold = threshold
+        self.log = logger.bind(repo=str(repo.working_dir))
+
+    def update_tour(
+        self,
+        tour: Tour,
+        target_commit: str,
+        source_commit: Optional[str] = None
+    ) -> TourUpdateResult:
+        """
+        Update a tour to target commit.
+
+        Args:
+            tour: Tour object to update
+            target_commit: Commit SHA to migrate to
+            source_commit: Source commit (defaults to tour.ref)
+
+        Returns:
+            TourUpdateResult with updated tour and metadata
+        """
+        # Use tour.ref if no source specified
+        if source_commit is None:
+            if tour.ref is None:
+                raise ValueError(
+                    "Tour has no ref commit and no source_commit provided"
+                )
+            source_commit = tour.ref
+
+        # Resolve commit refs to actual SHAs (HEAD, branch names, etc.)
+        # This ensures we store concrete commit IDs, not moving targets
+        source_commit = self.repo.commit(source_commit).hexsha
+        target_commit = self.repo.commit(target_commit).hexsha
+
+        log = self.log.bind(
+            source=source_commit[:8],
+            target=target_commit[:8],
+            tour_title=tour.title
+        )
+
+        log.info("updating_tour")
+
+        # Create migrator
+        migrator = DirectMigrator(
+            self.repo,
+            source_commit,
+            target_commit,
+            self.diff_algorithm,
+            self.threshold
+        )
+
+        # Migrate each step with line reference
+        updates = []
+        for idx, step in enumerate(tour.steps):
+            if step.has_line_reference():
+                update = self._migrate_step(migrator, idx, step, log)
+                updates.append(update)
+
+                # Apply update to step
+                if update.migration_result.file_renamed:
+                    step.file = update.migration_result.new_file
+                if update.migration_result.new_line is not None:
+                    step.line = update.migration_result.new_line
+            else:
+                log.debug(
+                    "step_skipped",
+                    step_index=idx,
+                    reason="no_line_reference"
+                )
+
+        # Update tour metadata
+        self._update_tour_metadata(
+            tour,
+            source_commit,
+            target_commit,
+            updates
+        )
+
+        # Create result
+        result = TourUpdateResult(
+            tour=tour,
+            updates=updates,
+            source_commit=source_commit,
+            target_commit=target_commit,
+            timestamp=datetime.now()
+        )
+
+        log.info(
+            "tour_updated",
+            num_steps=len(tour.steps),
+            num_updated=result.num_updated,
+            num_deprecated=result.num_deprecated,
+            num_needs_review=result.num_needs_review
+        )
+
+        return result
+
+    def _migrate_step(
+        self,
+        migrator: DirectMigrator,
+        step_index: int,
+        step: TourStep,
+        log: structlog.BoundLogger
+    ) -> StepUpdate:
+        """
+        Migrate a single tour step.
+
+        Args:
+            migrator: DirectMigrator instance
+            step_index: Index of step in tour
+            step: TourStep to migrate
+            log: Structured logger
+
+        Returns:
+            StepUpdate with migration result
+        """
+        old_location = f"{step.file}:{step.line}"
+
+        # Perform migration (pass step for pattern validation)
+        result = migrator.migrate_step(
+            step.file,
+            step.line,
+            step_id=step_index,
+            step=step  # Pass full step for pattern validation
+        )
+
+        # Determine new location (`is not None`, not bare truthiness -- line 0
+        # is a real, if invalid, int that Python's truthiness treats as falsy;
+        # ADR-0016 QST-CONF-1 found this exact bug caused this display logic
+        # to report "deprecated" while the mutation below -- which already
+        # correctly used `is not None` -- wrote a real line into the tour)
+        if result.new_file and result.new_line is not None:
+            new_location = f"{result.new_file}:{result.new_line}"
+        else:
+            new_location = None  # Deprecated
+
+        log.debug(
+            "step_migrated",
+            step_index=step_index,
+            old=old_location,
+            new=new_location,
+            method=result.method,
+            confidence=result.confidence
+        )
+
+        return StepUpdate(
+            step_index=step_index,
+            old_location=old_location,
+            new_location=new_location,
+            migration_result=result
+        )
+
+    def _update_tour_metadata(
+        self,
+        tour: Tour,
+        source_commit: str,
+        target_commit: str,
+        updates: List[StepUpdate]
+    ) -> None:
+        """
+        Update tour metadata to reflect migration.
+
+        Args:
+            tour: Tour object to update (modified in-place)
+            source_commit: Source commit SHA
+            target_commit: Target commit SHA
+            updates: List of step updates
+        """
+        # Store original ref if this is first migration
+        if tour.original_ref is None:
+            tour.original_ref = source_commit
+
+        # Update current ref to target
+        tour.ref = target_commit
+
+        # Add migration log entry
+        if tour.migration_log is None:
+            tour.migration_log = []
+
+        tour.migration_log.append({
+            "from": source_commit,
+            "to": target_commit,
+            "date": datetime.now().isoformat(),
+            "num_updated": sum(1 for u in updates if u.was_updated),
+            "num_deprecated": sum(1 for u in updates if u.deprecated),
+            "num_needs_review": sum(1 for u in updates if u.needs_review)
+        })
+
+
+def update_tour_file(
+    repo_path: Path,
+    tour_file: Path,
+    target_commit: str,
+    source_commit: Optional[str] = None,
+    diff_algorithm: str = "histogram",
+    save_backup: bool = True,
+    dry_run: bool = False,
+    threshold: float = 0.7
+) -> TourUpdateResult:
+    """
+    Convenience function to update a .tour file.
+
+    Args:
+        repo_path: Path to Git repository
+        tour_file: Path to .tour file
+        target_commit: Commit to migrate to
+        source_commit: Source commit (uses tour.ref if None)
+        diff_algorithm: Git diff algorithm
+        save_backup: Save .tour.backup before updating
+        dry_run: Preview changes without modifying files
+        threshold: confidence cutoff for needs_review, passed through to
+            DirectMigrator (ADR-0016 QST-CONF-2)
+
+    Returns:
+        TourUpdateResult with updated tour
+    """
+    log = logger.bind(
+        repo=str(repo_path),
+        tour=tour_file.name
+    )
+
+    if dry_run:
+        log.info("updating_tour_file_dry_run")
+    else:
+        log.info("updating_tour_file")
+
+    # Load tour
+    tour = Tour.from_file(tour_file)
+
+    # Create updater
+    repo = git.Repo(repo_path)
+    updater = TourUpdater(repo, diff_algorithm, threshold)
+
+    # Update tour
+    result = updater.update_tour(tour, target_commit, source_commit)
+
+    # Save files only if not dry-run
+    if not dry_run:
+        # Save backup if requested (use direct copy to preserve formatting)
+        if save_backup:
+            import shutil
+            backup_path = tour_file.with_suffix('.tour.backup')
+            shutil.copy2(tour_file, backup_path)
+            log.info("backup_saved", backup_path=str(backup_path))
+
+        # Save updated tour
+        result.tour.save(tour_file)
+        log.info("tour_file_updated")
+
+    return result
+
+
+def update_all_tours(
+    repo_path: Path,
+    tours_dir: Path,
+    target_commit: str,
+    diff_algorithm: str = "histogram",
+    save_backups: bool = True,
+    threshold: float = 0.7
+) -> List[TourUpdateResult]:
+    """
+    Update all .tour files in a directory.
+
+    Args:
+        repo_path: Path to Git repository
+        tours_dir: Path to .tours directory
+        target_commit: Commit to migrate to
+        diff_algorithm: Git diff algorithm
+        save_backups: Save .tour.backup files
+        threshold: confidence cutoff for needs_review (ADR-0016 QST-CONF-2)
+
+    Returns:
+        List of TourUpdateResult objects
+    """
+    log = logger.bind(
+        repo=str(repo_path),
+        tours_dir=str(tours_dir)
+    )
+
+    # Find all .tour files
+    tour_files = list(tours_dir.glob("*.tour"))
+    log.info("updating_all_tours", num_tours=len(tour_files))
+
+    # Update each tour
+    results = []
+    for tour_file in sorted(tour_files):
+        try:
+            result = update_tour_file(
+                repo_path,
+                tour_file,
+                target_commit,
+                diff_algorithm=diff_algorithm,
+                save_backup=save_backups,
+                threshold=threshold
+            )
+            results.append(result)
+        except Exception as e:
+            log.error(
+                "tour_update_failed",
+                tour=tour_file.name,
+                error=str(e)
+            )
+
+    # Summary
+    total_updated = sum(r.num_updated for r in results)
+    total_deprecated = sum(r.num_deprecated for r in results)
+    total_needs_review = sum(r.num_needs_review for r in results)
+
+    log.info(
+        "all_tours_updated",
+        num_tours=len(results),
+        total_updated=total_updated,
+        total_deprecated=total_deprecated,
+        total_needs_review=total_needs_review
+    )
+
+    return results