codeshift 0.2.0__py3-none-any.whl

codeshift/knowledge/sources.py

@@ -0,0 +1,388 @@
+"""Source fetchers for changelog and migration guide discovery."""
+
+import re
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+import httpx
+
+from codeshift.knowledge.models import ChangelogSource
+
+
+@dataclass
+class PackageInfo:
+    """Package information from PyPI."""
+
+    name: str
+    version: str
+    home_page: str | None = None
+    project_url: str | None = None
+    repository_url: str | None = None
+    documentation_url: str | None = None
+
+    @property
+    def github_url(self) -> str | None:
+        """Extract GitHub repository URL."""
+        for url in [self.repository_url, self.project_url, self.home_page]:
+            if url and "github.com" in url:
+                # Normalize to https://github.com/owner/repo format
+                parsed = urlparse(url)
+                if parsed.netloc == "github.com":
+                    path_parts = parsed.path.strip("/").split("/")
+                    if len(path_parts) >= 2:
+                        return f"https://github.com/{path_parts[0]}/{path_parts[1]}"
+        return None
+
+
+class SourceFetcher:
+    """Fetches changelog and migration guide sources from various locations."""
+
+    CHANGELOG_FILENAMES = [
+        "CHANGELOG.md",
+        "CHANGELOG.rst",
+        "CHANGELOG.txt",
+        "CHANGELOG",
+        "CHANGES.md",
+        "CHANGES.rst",
+        "CHANGES.txt",
+        "CHANGES",
+        "HISTORY.md",
+        "HISTORY.rst",
+        "NEWS.md",
+        "NEWS.rst",
+        "NEWS",
+    ]
+
+    MIGRATION_GUIDE_PATTERNS = [
+        "docs/migration",
+        "docs/upgrading",
+        "docs/upgrade",
+        "migration",
+        "MIGRATION.md",
+        "UPGRADING.md",
+    ]
+
+    def __init__(self, timeout: float = 30.0):
+        """Initialize the fetcher.
+
+        Args:
+            timeout: HTTP request timeout in seconds.
+        """
+        self.timeout = timeout
+        self._client: httpx.Client | None = None
+
+    @property
+    def client(self) -> httpx.Client:
+        """Get or create HTTP client."""
+        if self._client is None:
+            self._client = httpx.Client(
+                timeout=self.timeout,
+                follow_redirects=True,
+                headers={"Accept": "application/vnd.github.v3.raw"},
+            )
+        return self._client
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client:
+            self._client.close()
+            self._client = None
+
+    def get_package_info(self, package: str) -> PackageInfo | None:
+        """Fetch package information from PyPI.
+
+        Args:
+            package: Package name.
+
+        Returns:
+            PackageInfo or None if not found.
+        """
+        try:
+            response = self.client.get(f"https://pypi.org/pypi/{package}/json")
+            response.raise_for_status()
+            data = response.json()
+
+            info = data.get("info", {})
+            project_urls = info.get("project_urls") or {}
+
+            return PackageInfo(
+                name=info.get("name", package),
+                version=info.get("version", ""),
+                home_page=info.get("home_page"),
+                project_url=info.get("project_url"),
+                repository_url=project_urls.get("Repository")
+                or project_urls.get("Source")
+                or project_urls.get("GitHub"),
+                documentation_url=project_urls.get("Documentation") or project_urls.get("Docs"),
+            )
+        except Exception:
+            return None
+
+    def fetch_github_file(self, repo_url: str, file_path: str, branch: str = "main") -> str | None:
+        """Fetch a file from a GitHub repository.
+
+        Args:
+            repo_url: GitHub repository URL (https://github.com/owner/repo).
+            file_path: Path to the file within the repo.
+            branch: Branch to fetch from.
+
+        Returns:
+            File content or None if not found.
+        """
+        # Extract owner/repo from URL
+        parsed = urlparse(repo_url)
+        path_parts = parsed.path.strip("/").split("/")
+        if len(path_parts) < 2:
+            return None
+
+        owner, repo = path_parts[0], path_parts[1]
+
+        # Try raw GitHub content URL
+        raw_url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{file_path}"
+
+        try:
+            response = self.client.get(raw_url)
+            if response.status_code == 200:
+                return str(response.text)
+        except Exception:
+            pass
+
+        # Try master branch if main failed
+        if branch == "main":
+            return self.fetch_github_file(repo_url, file_path, branch="master")
+
+        return None
+
+    def fetch_changelog(self, repo_url: str) -> ChangelogSource | None:
+        """Fetch changelog from a GitHub repository.
+
+        Args:
+            repo_url: GitHub repository URL.
+
+        Returns:
+            ChangelogSource or None if not found.
+        """
+        for filename in self.CHANGELOG_FILENAMES:
+            content = self.fetch_github_file(repo_url, filename)
+            if content:
+                return ChangelogSource(
+                    url=f"{repo_url}/blob/main/{filename}",
+                    source_type="changelog",
+                    content=content,
+                )
+        return None
+
+    def fetch_migration_guide(self, repo_url: str) -> ChangelogSource | None:
+        """Fetch migration guide from a GitHub repository.
+
+        Args:
+            repo_url: GitHub repository URL.
+
+        Returns:
+            ChangelogSource or None if not found.
+        """
+        for pattern in self.MIGRATION_GUIDE_PATTERNS:
+            # Try common file extensions
+            for ext in [".md", ".rst", ".txt", ""]:
+                path = (
+                    f"{pattern}{ext}" if not pattern.endswith((".md", ".rst", ".txt")) else pattern
+                )
+                content = self.fetch_github_file(repo_url, path)
+                if content:
+                    return ChangelogSource(
+                        url=f"{repo_url}/blob/main/{path}",
+                        source_type="migration_guide",
+                        content=content,
+                    )
+        return None
+
+    def fetch_release_notes(self, repo_url: str, version: str) -> ChangelogSource | None:
+        """Fetch release notes for a specific version from GitHub releases.
+
+        Args:
+            repo_url: GitHub repository URL.
+            version: Version to fetch release notes for.
+
+        Returns:
+            ChangelogSource or None if not found.
+        """
+        parsed = urlparse(repo_url)
+        path_parts = parsed.path.strip("/").split("/")
+        if len(path_parts) < 2:
+            return None
+
+        owner, repo = path_parts[0], path_parts[1]
+
+        # Try GitHub API for releases
+        api_url = f"https://api.github.com/repos/{owner}/{repo}/releases"
+
+        try:
+            response = self.client.get(api_url)
+            if response.status_code != 200:
+                return None
+
+            releases = response.json()
+
+            # Find matching release
+            version_patterns = [
+                f"v{version}",
+                version,
+                f"release-{version}",
+            ]
+
+            for release in releases:
+                tag = release.get("tag_name", "")
+                for pattern in version_patterns:
+                    if tag == pattern or tag.startswith(pattern):
+                        body = release.get("body", "")
+                        if body:
+                            return ChangelogSource(
+                                url=release.get("html_url", repo_url),
+                                source_type="release_notes",
+                                content=body,
+                                version_range=(version, version),
+                            )
+                        break
+
+        except Exception:
+            pass
+
+        return None
+
+    async def discover_sources(
+        self, package: str, target_version: str | None = None
+    ) -> list[ChangelogSource]:
+        """Discover all available changelog sources for a package.
+
+        Args:
+            package: Package name.
+            target_version: Optional target version for release notes.
+
+        Returns:
+            List of discovered ChangelogSources.
+        """
+        # This is a sync wrapper - the async signature matches the architecture doc
+        return self.discover_sources_sync(package, target_version)
+
+    def discover_sources_sync(
+        self, package: str, target_version: str | None = None
+    ) -> list[ChangelogSource]:
+        """Synchronously discover all available changelog sources for a package.
+
+        Args:
+            package: Package name.
+            target_version: Optional target version for release notes.
+
+        Returns:
+            List of discovered ChangelogSources.
+        """
+        sources: list[ChangelogSource] = []
+
+        # Get package info from PyPI
+        pkg_info = self.get_package_info(package)
+        if not pkg_info:
+            return sources
+
+        github_url = pkg_info.github_url
+        if not github_url:
+            return sources
+
+        # Fetch changelog
+        changelog = self.fetch_changelog(github_url)
+        if changelog:
+            sources.append(changelog)
+
+        # Fetch migration guide
+        migration_guide = self.fetch_migration_guide(github_url)
+        if migration_guide:
+            sources.append(migration_guide)
+
+        # Fetch release notes for target version
+        if target_version:
+            release_notes = self.fetch_release_notes(github_url, target_version)
+            if release_notes:
+                sources.append(release_notes)
+
+        return sources
+
+    def extract_version_changelog(
+        self,
+        changelog_content: str,
+        from_version: str,
+        to_version: str,
+    ) -> str:
+        """Extract the relevant portion of a changelog between two versions.
+
+        Args:
+            changelog_content: Full changelog content.
+            from_version: Starting version.
+            to_version: Target version.
+
+        Returns:
+            Extracted changelog content for the version range.
+        """
+        lines = changelog_content.split("\n")
+        result_lines = []
+        in_range = False
+        found_start = False
+
+        # Common version header patterns
+        version_pattern = re.compile(
+            r"^#+\s*\[?v?(\d+\.\d+(?:\.\d+)?)\]?|"  # ## [1.0.0] or ## v1.0.0
+            r"^v?(\d+\.\d+(?:\.\d+)?)\s*[-–—]|"  # 1.0.0 - or v1.0.0 -
+            r"^v?(\d+\.\d+(?:\.\d+)?)\s*\(",  # 1.0.0 (date)
+            re.IGNORECASE,
+        )
+
+        for line in lines:
+            match = version_pattern.match(line)
+            if match:
+                # Extract version number
+                version = match.group(1) or match.group(2) or match.group(3)
+                if version:
+                    # Check if this is our target version or later
+                    if self._compare_versions(version, to_version) <= 0:
+                        if not found_start:
+                            in_range = True
+                            found_start = True
+
+                    # Check if we've gone past the from_version
+                    if self._compare_versions(version, from_version) < 0:
+                        in_range = False
+
+            if in_range:
+                result_lines.append(line)
+
+        return "\n".join(result_lines)
+
+    def _compare_versions(self, v1: str, v2: str) -> int:
+        """Compare two version strings.
+
+        Returns:
+            -1 if v1 < v2, 0 if v1 == v2, 1 if v1 > v2.
+        """
+        from packaging.version import Version
+
+        try:
+            ver1 = Version(v1)
+            ver2 = Version(v2)
+            if ver1 < ver2:
+                return -1
+            elif ver1 > ver2:
+                return 1
+            return 0
+        except Exception:
+            # Fallback to string comparison
+            return (v1 > v2) - (v1 < v2)
+
+
+# Singleton instance
+_default_fetcher: SourceFetcher | None = None
+
+
+def get_source_fetcher() -> SourceFetcher:
+    """Get the default source fetcher instance."""
+    global _default_fetcher
+    if _default_fetcher is None:
+        _default_fetcher = SourceFetcher()
+    return _default_fetcher

codeshift/knowledge_base/__init__.py

@@ -0,0 +1,17 @@
+"""Knowledge base module for breaking change definitions."""
+
+from codeshift.knowledge_base.loader import KnowledgeBaseLoader
+from codeshift.knowledge_base.models import (
+    BreakingChange,
+    ChangeType,
+    LibraryKnowledge,
+    Severity,
+)
+
+__all__ = [
+    "KnowledgeBaseLoader",
+    "BreakingChange",
+    "ChangeType",
+    "Severity",
+    "LibraryKnowledge",
+]

codeshift/knowledge_base/loader.py

@@ -0,0 +1,102 @@
+"""Loader for the knowledge base YAML files."""
+
+from pathlib import Path
+
+import yaml
+
+from codeshift.knowledge_base.models import LibraryKnowledge
+
+
+class KnowledgeBaseLoader:
+    """Loads and manages library knowledge bases."""
+
+    def __init__(self, knowledge_base_dir: Path | None = None):
+        """Initialize the loader.
+
+        Args:
+            knowledge_base_dir: Directory containing the YAML files.
+                              Defaults to the 'libraries' subdirectory.
+        """
+        if knowledge_base_dir is None:
+            knowledge_base_dir = Path(__file__).parent / "libraries"
+        self.knowledge_base_dir = knowledge_base_dir
+        self._cache: dict[str, LibraryKnowledge] = {}
+
+    def get_supported_libraries(self) -> list[str]:
+        """Get a list of all supported library names."""
+        libraries = []
+        if self.knowledge_base_dir.exists():
+            for yaml_file in self.knowledge_base_dir.glob("*.yaml"):
+                libraries.append(yaml_file.stem)
+        return sorted(libraries)
+
+    def load(self, library_name: str) -> LibraryKnowledge:
+        """Load the knowledge base for a specific library.
+
+        Args:
+            library_name: Name of the library (e.g., "pydantic")
+
+        Returns:
+            LibraryKnowledge object containing all breaking change info
+
+        Raises:
+            FileNotFoundError: If the knowledge base file doesn't exist
+            ValueError: If the YAML file is invalid
+        """
+        if library_name in self._cache:
+            return self._cache[library_name]
+
+        yaml_path = self.knowledge_base_dir / f"{library_name}.yaml"
+        if not yaml_path.exists():
+            raise FileNotFoundError(
+                f"No knowledge base found for library '{library_name}'. "
+                f"Available libraries: {', '.join(self.get_supported_libraries())}"
+            )
+
+        try:
+            with open(yaml_path) as f:
+                data = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML in knowledge base for '{library_name}': {e}") from e
+
+        if not isinstance(data, dict):
+            raise ValueError(f"Knowledge base for '{library_name}' must be a dictionary")
+
+        knowledge = LibraryKnowledge.from_dict(data)
+        self._cache[library_name] = knowledge
+        return knowledge
+
+    def is_migration_supported(self, library_name: str, from_version: str, to_version: str) -> bool:
+        """Check if a specific migration path is supported.
+
+        Args:
+            library_name: Name of the library
+            from_version: Starting version
+            to_version: Target version
+
+        Returns:
+            True if the migration path is supported
+        """
+        try:
+            knowledge = self.load(library_name)
+        except FileNotFoundError:
+            return False
+
+        from packaging.version import Version
+
+        from_v = Version(from_version)
+        to_v = Version(to_version)
+
+        for supported_from, supported_to in knowledge.supported_migrations:
+            supported_from_v = Version(supported_from)
+            supported_to_v = Version(supported_to)
+
+            # Check if requested migration falls within a supported range
+            if from_v >= supported_from_v and to_v <= supported_to_v:
+                return True
+
+        return False
+
+    def clear_cache(self) -> None:
+        """Clear the cached knowledge bases."""
+        self._cache.clear()

codeshift/knowledge_base/models.py

@@ -0,0 +1,110 @@
+"""Data models for the knowledge base."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ChangeType(Enum):
+    """Types of breaking changes."""
+
+    RENAMED = "renamed"
+    REMOVED = "removed"
+    SIGNATURE_CHANGED = "signature_changed"
+    BEHAVIOR_CHANGED = "behavior_changed"
+    DEPRECATED = "deprecated"
+    TYPE_CHANGED = "type_changed"
+
+
+class Severity(Enum):
+    """Severity levels for breaking changes."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass
+class BreakingChange:
+    """Represents a single breaking change in a library."""
+
+    symbol: str  # e.g., "BaseModel.Config", "@validator", ".dict()"
+    change_type: ChangeType
+    severity: Severity
+    from_version: str
+    to_version: str
+    description: str
+    replacement: str | None = None  # e.g., "model_config = ConfigDict(...)"
+    has_deterministic_transform: bool = False
+    transform_name: str | None = None  # e.g., "config_to_configdict"
+    migration_guide_url: str | None = None
+    notes: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BreakingChange":
+        """Create a BreakingChange from a dictionary."""
+        return cls(
+            symbol=data["symbol"],
+            change_type=ChangeType(data["change_type"]),
+            severity=Severity(data["severity"]),
+            from_version=data["from_version"],
+            to_version=data["to_version"],
+            description=data["description"],
+            replacement=data.get("replacement"),
+            has_deterministic_transform=data.get("has_deterministic_transform", False),
+            transform_name=data.get("transform_name"),
+            migration_guide_url=data.get("migration_guide_url"),
+            notes=data.get("notes"),
+        )
+
+
+@dataclass
+class LibraryKnowledge:
+    """Knowledge about a library's breaking changes."""
+
+    name: str
+    display_name: str
+    description: str
+    migration_guide_url: str | None
+    supported_migrations: list[tuple[str, str]]  # List of (from_version, to_version)
+    breaking_changes: list[BreakingChange] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "LibraryKnowledge":
+        """Create a LibraryKnowledge from a dictionary."""
+        breaking_changes = [BreakingChange.from_dict(bc) for bc in data.get("breaking_changes", [])]
+        supported_migrations = [(m["from"], m["to"]) for m in data.get("supported_migrations", [])]
+
+        return cls(
+            name=data["name"],
+            display_name=data["display_name"],
+            description=data.get("description", ""),
+            migration_guide_url=data.get("migration_guide_url"),
+            supported_migrations=supported_migrations,
+            breaking_changes=breaking_changes,
+        )
+
+    def get_changes_for_migration(self, from_version: str, to_version: str) -> list[BreakingChange]:
+        """Get all breaking changes relevant to a specific migration."""
+        from packaging.version import Version
+
+        from_v = Version(from_version)
+        to_v = Version(to_version)
+
+        relevant = []
+        for change in self.breaking_changes:
+            change_from = Version(change.from_version)
+            change_to = Version(change.to_version)
+
+            # Include if the change affects versions between from and to
+            if change_from >= from_v and change_to <= to_v:
+                relevant.append(change)
+
+        return relevant
+
+    def get_deterministic_transforms(
+        self, from_version: str, to_version: str
+    ) -> list[BreakingChange]:
+        """Get all breaking changes that have deterministic transforms."""
+        changes = self.get_changes_for_migration(from_version, to_version)
+        return [c for c in changes if c.has_deterministic_transform]

codeshift/migrator/__init__.py

@@ -0,0 +1,23 @@
+"""Migrator module for transforming code."""
+
+from codeshift.migrator.ast_transforms import (
+    BaseTransformer,
+    TransformChange,
+    TransformResult,
+    TransformStatus,
+)
+from codeshift.migrator.engine import (
+    MigrationEngine,
+    get_migration_engine,
+    run_migration,
+)
+
+__all__ = [
+    "BaseTransformer",
+    "TransformChange",
+    "TransformResult",
+    "TransformStatus",
+    "MigrationEngine",
+    "get_migration_engine",
+    "run_migration",
+]