codetour-cli 0.1.0__py3-none-any.whl

codetour_cli/config.py

@@ -0,0 +1,144 @@
+"""
+Configuration management for CodeTour CLI.
+
+Handles loading, merging, and saving configuration files.
+"""
+
+import structlog
+from pathlib import Path
+from typing import Optional, Dict, Any
+import yaml
+
+log = structlog.get_logger()
+
+# Default configuration
+DEFAULT_CONFIG = {
+    "tours_dir": ".tours",
+    "migration": {
+        "add_ref": True,
+        "backup": True,
+        "threshold": 0.7,
+        "diff_algorithm": "histogram",
+        "interactive": False,
+    },
+    "display": {
+        "color": True,
+        "verbosity": "normal",
+    }
+}
+
+CONFIG_TEMPLATE = """# CodeTour CLI Configuration
+# Generated: {date}
+
+# Tours location
+tours_dir: .tours
+
+# Migration behavior
+migration:
+  # Auto-inject 'ref' field after migration
+  add_ref: true
+
+  # Create backup files
+  backup: true
+
+  # Confidence threshold for auto-applying changes
+  threshold: 0.7
+
+  # Git diff algorithm (myers, minimal, patience, histogram)
+  diff_algorithm: histogram
+
+  # Interactive mode by default
+  interactive: false
+
+# Display preferences
+display:
+  # Use colors and emojis in output
+  color: true
+
+  # Verbosity level (quiet, normal, verbose)
+  verbosity: normal
+"""
+
+
+def generate_config_file(path: Path) -> None:
+    """
+    Generate a default configuration file.
+
+    Args:
+        path: Path where to save the config file
+    """
+    from datetime import datetime
+
+    config_content = CONFIG_TEMPLATE.format(date=datetime.now().strftime("%Y-%m-%d"))
+
+    path.write_text(config_content)
+    log.info("generated_config", path=str(path))
+
+
+def load_config(config_path: Optional[Path] = None) -> Dict[str, Any]:
+    """
+    Load configuration from file.
+
+    Args:
+        config_path: Path to config file (default: search for codetour.yaml)
+
+    Returns:
+        Configuration dictionary (merged with defaults)
+    """
+    config = DEFAULT_CONFIG.copy()
+
+    # Find config file if not specified
+    if config_path is None:
+        # Try .tours directory first (most discrete, project-specific)
+        tours_config = Path.cwd() / ".tours" / "codetour.yaml"
+        if tours_config.exists():
+            config_path = tours_config
+        else:
+            # Try current directory
+            config_path = Path.cwd() / "codetour.yaml"
+            if not config_path.exists():
+                # Try user config
+                user_config = Path.home() / ".config" / "codetour-cli" / "config.yaml"
+                if user_config.exists():
+                    config_path = user_config
+                else:
+                    # No config file found, use defaults
+                    return config
+
+    if not config_path.exists():
+        return config
+
+    try:
+        with open(config_path) as f:
+            user_config = yaml.safe_load(f) or {}
+
+        # Merge with defaults (user config takes precedence)
+        config = merge_config(config, user_config)
+
+        log.info("loaded_config", path=str(config_path))
+    except Exception as e:
+        log.warning("failed_to_load_config", path=str(config_path), error=str(e))
+
+    return config
+
+
+def merge_config(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Merge configuration dictionaries recursively.
+
+    Args:
+        base: Base configuration
+        override: Override configuration (takes precedence)
+
+    Returns:
+        Merged configuration
+    """
+    result = base.copy()
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = merge_config(result[key], value)
+        else:
+            result[key] = value
+
+    return result

codetour_cli/description_validator.py

@@ -0,0 +1,197 @@
+"""
+Description edit validation for review reports.
+
+Provides safety checks for edited descriptions to catch copy-paste errors,
+placeholder text, and suspicious changes.
+"""
+
+import re
+import difflib
+from typing import Tuple, List
+from dataclasses import dataclass
+
+
+@dataclass
+class ValidationResult:
+    """Result of description validation."""
+    is_valid: bool  # False if hard errors found
+    errors: List[str]  # Tier 1: Hard errors (prevent apply)
+    warnings: List[str]  # Tier 2: Warnings (prompt user, allow with --yes)
+    info: List[str]  # Tier 3: Info (just log)
+    similarity: float  # 0.0 to 1.0
+    len_ratio: float  # edited_len / original_len
+
+
+def calculate_similarity(text1: str, text2: str) -> float:
+    """
+    Calculate text similarity using SequenceMatcher.
+
+    Args:
+        text1: First text
+        text2: Second text
+
+    Returns:
+        Similarity ratio from 0.0 (completely different) to 1.0 (identical)
+    """
+    if not text1 and not text2:
+        return 1.0
+    if not text1 or not text2:
+        return 0.0
+
+    return difflib.SequenceMatcher(None, text1, text2).ratio()
+
+
+def check_structure_preserved(original: str, edited: str) -> List[str]:
+    """
+    Check if structural markdown elements are preserved.
+
+    Args:
+        original: Original description
+        edited: Edited description
+
+    Returns:
+        List of warning messages about missing structural elements
+    """
+    warnings = []
+
+    # Code blocks
+    orig_code = original.count('```')
+    edit_code = edited.count('```')
+    if orig_code > 0 and edit_code == 0:
+        warnings.append("Original had code blocks, edited version doesn't")
+
+    # Bullet lists (significant number) - handle indented bullets
+    orig_lists = len(re.findall(r'\n\s*[-*] ', original))
+    edit_lists = len(re.findall(r'\n\s*[-*] ', edited))
+    if orig_lists > 3 and edit_lists == 0:
+        warnings.append("Original had bullet lists, edited version doesn't")
+
+    # Markdown links
+    orig_links = original.count('](')
+    edit_links = edited.count('](')
+    if orig_links > 0 and edit_links == 0:
+        warnings.append("Original had markdown links, edited version doesn't")
+
+    # Headers - handle indented headers
+    orig_headers = len(re.findall(r'\n\s*##+ ', original))
+    edit_headers = len(re.findall(r'\n\s*##+ ', edited))
+    if orig_headers > 0 and edit_headers == 0:
+        warnings.append("Original had section headers, edited version doesn't")
+
+    return warnings
+
+
+def validate_edited_description(
+    edited_desc: str,
+    original_desc: str
+) -> ValidationResult:
+    """
+    Validate edited description for common errors and suspicious changes.
+
+    Implements 3-tier validation:
+    - Tier 1 (Errors): Hard failures that prevent apply
+    - Tier 2 (Warnings): Suspicious changes that prompt user
+    - Tier 3 (Info): Informational metrics (just logged)
+
+    Args:
+        edited_desc: User-edited description from review report
+        original_desc: Original tour step description
+
+    Returns:
+        ValidationResult with errors, warnings, and metrics
+    """
+    errors = []
+    warnings = []
+    info = []
+
+    # Calculate metrics
+    edited_clean = edited_desc.strip() if edited_desc else ""
+    original_clean = original_desc.strip() if original_desc else ""
+
+    similarity = calculate_similarity(original_clean, edited_clean)
+    len_ratio = len(edited_clean) / max(len(original_clean), 1)
+
+    # Tier 1: Hard errors (prevent apply)
+    if not edited_clean:
+        errors.append("Edited description is empty")
+
+    if "Edit the step description here" in edited_desc:
+        errors.append("Edited description contains placeholder text")
+
+    if "(Edit " in edited_desc and " above)" in edited_desc:
+        errors.append("Edited description contains template instructions")
+
+    if edited_clean and len(edited_clean) < 10:
+        errors.append(f"Edited description is too short ({len(edited_clean)} chars)")
+
+    # Tier 2: Warnings (prompt user, allow with --yes)
+    if similarity < 0.3:
+        warnings.append(
+            f"Description changed significantly ({similarity:.0%} similarity)\n"
+            f"      Original: {len(original_clean)} chars, Edited: {len(edited_clean)} chars\n"
+            f"      This might indicate a copy-paste error"
+        )
+
+    if len_ratio > 3.0:
+        warnings.append(
+            f"Edited description is 3x longer than original\n"
+            f"      This might indicate accidental content inclusion"
+        )
+    elif len_ratio < 0.3 and len(original_clean) > 50:
+        warnings.append(
+            f"Edited description is much shorter than original\n"
+            f"      This might indicate truncated content"
+        )
+
+    # Check structural elements
+    struct_warnings = check_structure_preserved(original_clean, edited_clean)
+    if struct_warnings:
+        warnings.append(
+            "Structural elements changed:\n      " +
+            "\n      ".join(struct_warnings)
+        )
+
+    # Tier 3: Info (moderate changes, just log)
+    if 0.3 <= similarity < 0.7:
+        info.append(f"Moderate change ({similarity:.0%} similarity)")
+
+    word_delta = len(edited_clean.split()) - len(original_clean.split())
+    if abs(word_delta) > 10:
+        info.append(f"Word count delta: {word_delta:+d}")
+
+    is_valid = len(errors) == 0
+
+    return ValidationResult(
+        is_valid=is_valid,
+        errors=errors,
+        warnings=warnings,
+        info=info,
+        similarity=similarity,
+        len_ratio=len_ratio
+    )
+
+
+def format_validation_message(step_num: int, result: ValidationResult) -> str:
+    """
+    Format validation result as user-friendly message.
+
+    Args:
+        step_num: Step number being validated
+        result: ValidationResult from validate_edited_description
+
+    Returns:
+        Formatted message string for display
+    """
+    lines = []
+
+    if result.errors:
+        lines.append(f"  ❌ Step {step_num}: Description edit failed validation:")
+        for error in result.errors:
+            lines.append(f"     - {error}")
+
+    if result.warnings:
+        lines.append(f"  ⚠️  Step {step_num}: Description edit warnings:")
+        for warning in result.warnings:
+            lines.append(f"     {warning}")
+
+    return "\n".join(lines)

codetour_cli/detection.py

@@ -0,0 +1,91 @@
+"""
+Tour source commit detection.
+
+Determines which commit a tour should be migrated from.
+"""
+
+import structlog
+from pathlib import Path
+from git import Repo, GitCommandError
+
+from codetour_cli.tour.schema import Tour
+
+log = structlog.get_logger()
+
+
+def detect_source_commit(repo: Repo, tour_path: str | Path) -> tuple[str, float, str]:
+    """
+    Detect the commit where this tour was last valid.
+
+    Strategy:
+    1. If tour has explicit 'ref' field → use it (user intent)
+    2. If tour file is in git → last commit that touched it
+    3. If file not committed → use HEAD (assume current)
+
+    Args:
+        repo: GitPython Repo object
+        tour_path: Path to .tour file (relative to repo root)
+
+    Returns:
+        tuple of (commit_sha, confidence, method)
+        - commit_sha: The detected source commit
+        - confidence: How confident we are (0.0-1.0)
+        - method: How we detected it ('explicit_ref', 'git_log', 'uncommitted')
+
+    Examples:
+        >>> detect_source_commit(repo, ".tours/main.tour")
+        ('abc123...', 0.95, 'git_log')
+    """
+    tour_path = Path(tour_path)
+
+    # Construct absolute path if relative (relative to repo root)
+    if not tour_path.is_absolute():
+        tour_path = Path(repo.working_dir) / tour_path
+
+    # Load tour to check for explicit ref field
+    try:
+        tour = Tour.from_file(tour_path)
+    except Exception as e:
+        log.error("failed_to_load_tour", path=str(tour_path), error=str(e))
+        # Fallback: assume current HEAD
+        return repo.head.commit.hexsha, 0.3, "load_failed"
+
+    # 1. Explicit ref takes priority (user intent)
+    if tour.ref:
+        log.info(
+            "using_explicit_ref",
+            path=str(tour_path),
+            ref=tour.ref[:8] if len(tour.ref) >= 8 else tour.ref
+        )
+        return tour.ref, 1.0, "explicit_ref"
+
+    # 2. Most recent commit that touched this file
+    try:
+        # Get the most recent commit for this file
+        # --follow tracks through renames
+        commits = list(repo.iter_commits(paths=str(tour_path), max_count=1))
+
+        if commits:
+            last_commit = commits[0]
+            log.info(
+                "detected_via_git_log",
+                path=str(tour_path),
+                commit=last_commit.hexsha[:8],
+                date=last_commit.committed_datetime.isoformat()
+            )
+            return last_commit.hexsha, 0.95, "git_log"
+
+    except GitCommandError as e:
+        log.warning(
+            "git_log_failed",
+            path=str(tour_path),
+            error=str(e)
+        )
+
+    # 3. File not in git (new/uncommitted)
+    log.warning(
+        "tour_not_in_git",
+        path=str(tour_path),
+        fallback="HEAD"
+    )
+    return repo.head.commit.hexsha, 0.5, "uncommitted"

codetour_cli/discovery.py

@@ -0,0 +1,226 @@
+"""
+Tour discovery and repository scanning.
+
+Auto-discovers tours in the current repository.
+"""
+
+import structlog
+from pathlib import Path
+from typing import List, Optional, Tuple
+from dataclasses import dataclass
+from datetime import datetime
+
+from git import Repo, InvalidGitRepositoryError, GitCommandError
+
+from codetour_cli.tour.schema import Tour
+from codetour_cli.detection import detect_source_commit
+
+log = structlog.get_logger()
+
+
+@dataclass
+class TourInfo:
+    """
+    Information about a discovered tour.
+    """
+    path: Path  # Absolute path to tour file
+    tour: Tour  # Loaded tour object
+    source_commit: str  # Detected source commit
+    source_confidence: float  # Confidence in source detection
+    source_method: str  # How source was detected
+    commits_behind: int  # Number of commits since source
+    last_modified: datetime  # When tour file was last modified in git
+
+
+@dataclass
+class RepositoryInfo:
+    """
+    Information about the repository containing tours.
+    """
+    repo_path: Path  # Repository root
+    tours_dir: Path  # Tours directory (.tours/)
+    tours: List[TourInfo]  # Discovered tours
+
+
+def find_repo_root(start_path: Optional[Path] = None) -> Path:
+    """
+    Find the git repository root, starting from start_path.
+
+    Args:
+        start_path: Directory to start searching from (default: current directory)
+
+    Returns:
+        Path to repository root
+
+    Raises:
+        InvalidGitRepositoryError: If not in a git repository
+    """
+    start_path = start_path or Path.cwd()
+
+    try:
+        repo = Repo(start_path, search_parent_directories=True)
+        repo_root = Path(repo.working_dir)
+        log.debug("found_repo_root", path=str(repo_root))
+        return repo_root
+    except InvalidGitRepositoryError as e:
+        log.error("not_a_git_repo", start_path=str(start_path))
+        raise InvalidGitRepositoryError(
+            f"Not a git repository (or any parent up to mount point)\n"
+            f"CodeTour CLI requires git to track tour drift.\n"
+            f"Initialize git with: git init"
+        ) from e
+
+
+def find_tours_directory(repo_root: Path) -> Optional[Path]:
+    """
+    Find the .tours directory in the repository.
+
+    Args:
+        repo_root: Repository root path
+
+    Returns:
+        Path to tours directory, or None if not found
+    """
+    tours_dir = repo_root / ".tours"
+
+    if tours_dir.exists() and tours_dir.is_dir():
+        log.debug("found_tours_directory", path=str(tours_dir))
+        return tours_dir
+
+    log.warning("tours_directory_not_found", repo_root=str(repo_root))
+    return None
+
+
+def scan_tours(tours_dir: Path) -> List[Path]:
+    """
+    Scan for .tour files in the tours directory.
+
+    Args:
+        tours_dir: Path to tours directory
+
+    Returns:
+        List of paths to tour files
+    """
+    tour_files = sorted(tours_dir.glob("*.tour"))
+    log.info("scanned_tours", num_tours=len(tour_files), tours_dir=str(tours_dir))
+    return tour_files
+
+
+def load_tour_info(repo: Repo, tour_path: Path) -> Optional[TourInfo]:
+    """
+    Load full information about a tour.
+
+    Args:
+        repo: GitPython Repo object
+        tour_path: Path to tour file
+
+    Returns:
+        TourInfo object, or None if tour couldn't be loaded
+    """
+    try:
+        # Load tour
+        tour = Tour.from_file(tour_path)
+
+        # Detect source commit
+        tour_path_rel = tour_path.relative_to(repo.working_dir)
+        source_commit, confidence, method = detect_source_commit(repo, tour_path_rel)
+
+        # Count commits since source
+        try:
+            commits = list(repo.iter_commits(f"{source_commit}..HEAD"))
+            commits_behind = len(commits)
+        except GitCommandError:
+            # Source commit might not be reachable
+            commits_behind = 0
+
+        # Get last modified time from git
+        try:
+            last_commit = list(repo.iter_commits(paths=str(tour_path_rel), max_count=1))
+            if last_commit:
+                last_modified = last_commit[0].committed_datetime
+            else:
+                # File not in git, use filesystem mtime
+                last_modified = datetime.fromtimestamp(tour_path.stat().st_mtime)
+        except (GitCommandError, OSError):
+            last_modified = datetime.now()
+
+        return TourInfo(
+            path=tour_path,
+            tour=tour,
+            source_commit=source_commit,
+            source_confidence=confidence,
+            source_method=method,
+            commits_behind=commits_behind,
+            last_modified=last_modified
+        )
+
+    except Exception as e:
+        log.error("failed_to_load_tour", path=str(tour_path), error=str(e))
+        return None
+
+
+def discover_repository(start_path: Optional[Path] = None) -> RepositoryInfo:
+    """
+    Discover repository and all tours within it.
+
+    Args:
+        start_path: Directory to start searching from (default: current directory)
+
+    Returns:
+        RepositoryInfo with all discovered tours
+
+    Raises:
+        InvalidGitRepositoryError: If not in a git repository
+        ValueError: If no .tours directory found
+    """
+    # Find repo root
+    repo_root = find_repo_root(start_path)
+    repo = Repo(repo_root)
+
+    # Find tours directory
+    tours_dir = find_tours_directory(repo_root)
+    if tours_dir is None:
+        raise ValueError(
+            f"No .tours directory found in {repo_root}\n"
+            f"Create it with: mkdir .tours\n"
+            f"Or run: codetour init"
+        )
+
+    # Scan for tours
+    tour_paths = scan_tours(tours_dir)
+    if not tour_paths:
+        log.warning("no_tours_found", tours_dir=str(tours_dir))
+
+    # Load tour information
+    tours = []
+    for tour_path in tour_paths:
+        tour_info = load_tour_info(repo, tour_path)
+        if tour_info:
+            tours.append(tour_info)
+
+    log.info(
+        "discovered_repository",
+        repo_root=str(repo_root),
+        tours_dir=str(tours_dir),
+        num_tours=len(tours)
+    )
+
+    return RepositoryInfo(
+        repo_path=repo_root,
+        tours_dir=tours_dir,
+        tours=tours
+    )
+
+
+def is_tour_up_to_date(tour_info: TourInfo, threshold: int = 0) -> bool:
+    """
+    Check if a tour is up to date.
+
+    Args:
+        tour_info: Tour information
+        threshold: Maximum commits behind to be considered up to date
+
+    Returns:
+        True if tour is up to date
+    """
+    return tour_info.commits_behind <= threshold