recce-nightly 1.9.0.20250623__py3-none-any.whl → 1.25.0.20251112a2066__py3-none-any.whl

recce_cloud/api/exceptions.py

@@ -0,0 +1,26 @@
+"""
+Exceptions for Recce Cloud API.
+"""
+
+import json
+
+
+class RecceCloudException(Exception):
+    """Exception raised when Recce Cloud API returns an error."""
+
+    def __init__(self, reason: str, status_code: int = None):
+        """
+        Initialize exception.
+
+        Args:
+            reason: Error reason/message
+            status_code: HTTP status code (optional)
+        """
+        try:
+            reason = json.loads(reason).get("detail", reason)
+        except (json.JSONDecodeError, AttributeError):
+            pass
+
+        super().__init__(reason)
+        self.reason = reason
+        self.status_code = status_code

recce_cloud/api/factory.py

@@ -0,0 +1,63 @@
+"""
+Factory for creating platform-specific API clients.
+"""
+
+import os
+from typing import Optional
+
+from recce_cloud.api.github import GitHubRecceCloudClient
+from recce_cloud.api.gitlab import GitLabRecceCloudClient
+from recce_cloud.ci_providers import CIDetector
+from recce_cloud.ci_providers.base import CIInfo
+
+
+def create_platform_client(
+    token: str,
+    ci_info: Optional[CIInfo] = None,
+    api_host: Optional[str] = None,
+):
+    """
+    Create a platform-specific Recce Cloud API client based on CI environment.
+
+    Args:
+        token: Authentication token (GITHUB_TOKEN, CI_JOB_TOKEN, or RECCE_API_TOKEN)
+        ci_info: CI information (auto-detected if not provided)
+        api_host: Recce Cloud API host (optional)
+
+    Returns:
+        GitHubRecceCloudClient or GitLabRecceCloudClient
+
+    Raises:
+        ValueError: If platform is not supported or required information is missing
+    """
+    # Auto-detect CI info if not provided
+    if ci_info is None:
+        ci_info = CIDetector.detect()
+
+    if ci_info.platform == "github-actions":
+        repository = ci_info.repository or os.getenv("GITHUB_REPOSITORY")
+        if not repository:
+            raise ValueError("GitHub repository information is required but not detected")
+
+        return GitHubRecceCloudClient(token=token, repository=repository, api_host=api_host)
+
+    elif ci_info.platform == "gitlab-ci":
+        project_path = ci_info.repository or os.getenv("CI_PROJECT_PATH")
+        repository_url = os.getenv("CI_PROJECT_URL")
+
+        if not project_path:
+            raise ValueError("GitLab project path is required but not detected")
+        if not repository_url:
+            raise ValueError("GitLab project URL is required but not detected")
+
+        return GitLabRecceCloudClient(
+            token=token,
+            project_path=project_path,
+            repository_url=repository_url,
+            api_host=api_host,
+        )
+
+    else:
+        raise ValueError(
+            f"Unsupported platform: {ci_info.platform}. " "Only GitHub Actions and GitLab CI are supported."
+        )

recce_cloud/api/github.py

@@ -0,0 +1,72 @@
+"""
+GitHub-specific API client for Recce Cloud.
+"""
+
+from typing import Dict, Optional
+
+from recce_cloud.api.base import BaseRecceCloudClient
+
+
+class GitHubRecceCloudClient(BaseRecceCloudClient):
+    """GitHub Actions-specific implementation of Recce Cloud API client."""
+
+    def __init__(self, token: str, repository: str, api_host: Optional[str] = None):
+        """
+        Initialize GitHub API client.
+
+        Args:
+            token: GitHub token (GITHUB_TOKEN or RECCE_API_TOKEN)
+            repository: Repository in format "owner/repo"
+            api_host: Recce Cloud API host
+        """
+        super().__init__(token, api_host)
+        self.repository = repository
+
+    def touch_recce_session(
+        self,
+        branch: str,
+        adapter_type: str,
+        cr_number: Optional[int] = None,
+    ) -> Dict:
+        """
+        Create or touch a Recce session for GitHub Actions.
+
+        Args:
+            branch: Branch name
+            adapter_type: DBT adapter type
+            cr_number: PR number for pull request sessions
+            commit_sha: Not used for GitHub (optional for compatibility)
+
+        Returns:
+            Dictionary containing session_id, manifest_upload_url, catalog_upload_url
+        """
+        url = f"{self.api_host}/api/v2/github/{self.repository}/touch-recce-session"
+
+        payload = {
+            "branch": branch,
+            "adapter_type": adapter_type,
+        }
+
+        if cr_number is not None:
+            payload["pr_number"] = cr_number
+
+        return self._make_request("POST", url, json=payload)
+
+    def upload_completed(self, session_id: str, commit_sha: Optional[str] = None) -> Dict:
+        """
+        Notify Recce Cloud that upload is complete for GitHub.
+
+        Args:
+            session_id: Session ID from touch_recce_session
+            commit_sha: Not used for GitHub (optional for compatibility)
+
+        Returns:
+            Empty dictionary or acknowledgement
+        """
+        url = f"{self.api_host}/api/v2/github/{self.repository}/upload-completed"
+
+        payload = {
+            "session_id": session_id,
+        }
+
+        return self._make_request("POST", url, json=payload)

recce_cloud/api/gitlab.py

@@ -0,0 +1,78 @@
+"""
+GitLab-specific API client for Recce Cloud.
+"""
+
+from typing import Dict, Optional
+
+from recce_cloud.api.base import BaseRecceCloudClient
+
+
+class GitLabRecceCloudClient(BaseRecceCloudClient):
+    """GitLab CI-specific implementation of Recce Cloud API client."""
+
+    def __init__(self, token: str, project_path: str, repository_url: str, api_host: Optional[str] = None):
+        """
+        Initialize GitLab API client.
+
+        Args:
+            token: GitLab token (CI_JOB_TOKEN or RECCE_API_TOKEN)
+            project_path: Project path in format "group/project"
+            repository_url: Full repository URL (e.g., https://gitlab.com/group/project)
+            api_host: Recce Cloud API host
+        """
+        super().__init__(token, api_host)
+        self.project_path = project_path
+        self.repository_url = repository_url
+
+    def touch_recce_session(
+        self,
+        branch: str,
+        adapter_type: str,
+        cr_number: Optional[int] = None,
+        commit_sha: Optional[str] = None,
+    ) -> Dict:
+        """
+        Create or touch a Recce session for GitLab CI.
+
+        Args:
+            branch: Branch name
+            adapter_type: DBT adapter type
+            cr_number: MR IID for merge request sessions
+            commit_sha: Commit SHA (required for GitLab)
+
+        Returns:
+            Dictionary containing session_id, manifest_upload_url, catalog_upload_url
+        """
+        url = f"{self.api_host}/api/v2/gitlab/{self.project_path}/touch-recce-session"
+
+        payload = {
+            "branch": branch,
+            "adapter_type": adapter_type,
+            "commit_sha": commit_sha,
+            "repository_url": self.repository_url,
+        }
+
+        if cr_number is not None:
+            payload["mr_iid"] = cr_number
+
+        return self._make_request("POST", url, json=payload)
+
+    def upload_completed(self, session_id: str, commit_sha: Optional[str] = None) -> Dict:
+        """
+        Notify Recce Cloud that upload is complete for GitLab.
+
+        Args:
+            session_id: Session ID from touch_recce_session
+            commit_sha: Commit SHA (required for GitLab)
+
+        Returns:
+            Empty dictionary or acknowledgement
+        """
+        url = f"{self.api_host}/api/v2/gitlab/{self.project_path}/upload-completed"
+
+        payload = {
+            "session_id": session_id,
+            "commit_sha": commit_sha,
+        }
+
+        return self._make_request("POST", url, json=payload)

recce_cloud/artifact.py

@@ -0,0 +1,57 @@
+"""
+Artifact utilities for recce-cloud.
+
+Simplified version of recce.artifact with only the functions needed
+for upload-session functionality.
+"""
+
+import json
+import os
+
+
+def verify_artifacts_path(target_path: str) -> bool:
+    """
+    Verify if the target path contains valid dbt artifacts.
+
+    Args:
+        target_path: Path to the directory containing artifacts
+
+    Returns:
+        True if the target path contains manifest.json and catalog.json
+    """
+    if not target_path:
+        return False
+
+    if not os.path.exists(target_path):
+        return False
+
+    if not os.path.isdir(target_path):
+        return False
+
+    required_artifacts_files = ["manifest.json", "catalog.json"]
+
+    if all(f in os.listdir(target_path) for f in required_artifacts_files):
+        return True
+
+    return False
+
+
+def get_adapter_type(manifest_path: str) -> str:
+    """
+    Extract adapter type from manifest.json.
+
+    Args:
+        manifest_path: Path to manifest.json file
+
+    Returns:
+        Adapter type string (e.g., "postgres", "snowflake", "bigquery")
+
+    Raises:
+        Exception: If adapter type cannot be found in manifest
+    """
+    with open(manifest_path, "r", encoding="utf-8") as f:
+        manifest_data = json.load(f)
+        adapter_type = manifest_data.get("metadata", {}).get("adapter_type")
+        if adapter_type is None:
+            raise Exception("Failed to parse adapter type from manifest.json")
+        return adapter_type

recce_cloud/ci_providers/__init__.py

@@ -0,0 +1,9 @@
+"""
+CI/CD Provider detection and information extraction.
+"""
+
+from recce_cloud.ci_providers.detector import CIDetector
+from recce_cloud.ci_providers.github_actions import GitHubActionsProvider
+from recce_cloud.ci_providers.gitlab_ci import GitLabCIProvider
+
+__all__ = ["CIDetector", "GitHubActionsProvider", "GitLabCIProvider"]

recce_cloud/ci_providers/base.py

@@ -0,0 +1,82 @@
+"""
+Base CI provider interface.
+"""
+
+import subprocess
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class CIInfo:
+    """Information extracted from CI environment."""
+
+    platform: Optional[str] = None  # "github-actions", "gitlab-ci", etc.
+    cr_number: Optional[int] = None  # Change request number (PR/MR)
+    cr_url: Optional[str] = None  # Change request URL (for session linking)
+    session_type: Optional[str] = None  # "cr", "prod", "dev"
+    commit_sha: Optional[str] = None  # Full commit SHA
+    base_branch: Optional[str] = None  # Target/base branch
+    source_branch: Optional[str] = None  # Source/head branch
+    repository: Optional[str] = None  # Repository path (owner/repo or group/project)
+    access_token: Optional[str] = None  # CI-provided access token (GITHUB_TOKEN, CI_JOB_TOKEN)
+
+
+class BaseCIProvider(ABC):
+    """Abstract base class for CI provider detection and info extraction."""
+
+    @abstractmethod
+    def can_handle(self) -> bool:
+        """
+        Check if this provider can handle the current environment.
+
+        Returns:
+            True if the provider's CI platform is detected
+        """
+        pass
+
+    @abstractmethod
+    def extract_ci_info(self) -> CIInfo:
+        """
+        Extract CI information from environment variables.
+
+        Returns:
+            CIInfo object with extracted information
+        """
+        pass
+
+    @staticmethod
+    def run_git_command(command: list[str]) -> Optional[str]:
+        """
+        Run a git command and return output.
+
+        Args:
+            command: Git command as list (e.g., ['git', 'rev-parse', 'HEAD'])
+
+        Returns:
+            Command output stripped of whitespace, or None if command fails
+        """
+        try:
+            result = subprocess.run(command, capture_output=True, text=True, check=True, timeout=5)
+            return result.stdout.strip()
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+            return None
+
+    @staticmethod
+    def determine_session_type(cr_number: Optional[int], source_branch: Optional[str]) -> str:
+        """
+        Determine session type based on context.
+
+        Args:
+            cr_number: Change request number (PR/MR)
+            source_branch: Source branch name
+
+        Returns:
+            Session type: "cr", "prod", or "dev"
+        """
+        if cr_number is not None:
+            return "cr"
+        if source_branch in ["main", "master"]:
+            return "prod"
+        return "dev"

recce_cloud/ci_providers/detector.py

@@ -0,0 +1,147 @@
+"""
+CI provider detection and orchestration.
+"""
+
+import logging
+import os
+from typing import Optional
+
+from recce_cloud.ci_providers.base import BaseCIProvider, CIInfo
+from recce_cloud.ci_providers.github_actions import GitHubActionsProvider
+from recce_cloud.ci_providers.gitlab_ci import GitLabCIProvider
+
+logger = logging.getLogger(__name__)
+
+
+class CIDetector:
+    """
+    Detects CI platform and extracts information.
+
+    Supports:
+    - GitHub Actions
+    - GitLab CI/CD
+    - Generic fallback (git commands)
+    """
+
+    # Order matters: check in priority order
+    PROVIDERS = [
+        GitHubActionsProvider,
+        GitLabCIProvider,
+    ]
+
+    @classmethod
+    def detect(cls) -> CIInfo:
+        """
+        Detect CI platform and extract information.
+
+        Returns:
+            CIInfo object with detected information
+        """
+        # Try each provider in order
+        for provider_class in cls.PROVIDERS:
+            provider = provider_class()
+            if provider.can_handle():
+                logger.info(f"CI Platform: {provider_class.__name__.replace('Provider', '')}")
+                ci_info = provider.extract_ci_info()
+                cls._log_detected_values(ci_info)
+                return ci_info
+
+        # No CI platform detected, use generic fallback
+        logger.info("No CI platform detected, using git fallback")
+        ci_info = cls._fallback_detection()
+        cls._log_detected_values(ci_info)
+        return ci_info
+
+    @classmethod
+    def apply_overrides(
+        cls,
+        ci_info: CIInfo,
+        cr: Optional[int] = None,
+        session_type: Optional[str] = None,
+    ) -> CIInfo:
+        """
+        Apply manual overrides to detected CI information.
+
+        Args:
+            ci_info: Detected CI information
+            cr: Manual change request number override
+            session_type: Manual session type override
+
+        Returns:
+            CIInfo with overrides applied
+        """
+        # Log overrides
+        if cr is not None and cr != ci_info.cr_number:
+            logger.info(f"Using manual override: --cr {cr} (detected: {ci_info.cr_number})")
+            ci_info.cr_number = cr
+            # Rebuild CR URL if we have repository info
+            if ci_info.repository:
+                if ci_info.platform == "github-actions":
+                    ci_info.cr_url = f"https://github.com/{ci_info.repository}/pull/{cr}"
+                elif ci_info.platform == "gitlab-ci":
+                    server_url = os.getenv("CI_SERVER_URL", "https://gitlab.com")
+                    ci_info.cr_url = f"{server_url}/{ci_info.repository}/-/merge_requests/{cr}"
+
+        if session_type is not None and session_type != ci_info.session_type:
+            logger.info(f"Using manual override: --type {session_type} (detected: {ci_info.session_type})")
+            ci_info.session_type = session_type
+
+        # Re-determine session type if CR was overridden
+        if cr is not None:
+            if session_type is None:  # Only if not manually overridden
+                ci_info.session_type = BaseCIProvider.determine_session_type(ci_info.cr_number, ci_info.source_branch)
+
+        return ci_info
+
+    @classmethod
+    def _fallback_detection(cls) -> CIInfo:
+        """
+        Fallback detection using git commands when no CI platform is detected.
+
+        Returns:
+            CIInfo with basic git information
+        """
+        commit_sha = BaseCIProvider.run_git_command(["git", "rev-parse", "HEAD"])
+        source_branch = BaseCIProvider.run_git_command(["git", "branch", "--show-current"])
+
+        session_type = BaseCIProvider.determine_session_type(None, source_branch)
+
+        return CIInfo(
+            platform=None,
+            cr_number=None,
+            session_type=session_type,
+            commit_sha=commit_sha,
+            base_branch="main",  # Default
+            source_branch=source_branch,
+            repository=None,
+        )
+
+    @classmethod
+    def _log_detected_values(cls, ci_info: CIInfo) -> None:
+        """
+        Log detected values for transparency.
+
+        Args:
+            ci_info: Detected CI information
+        """
+        if ci_info.cr_number is not None:
+            if ci_info.platform == "github-actions":
+                logger.info(f"Detected PR number: {ci_info.cr_number}")
+            elif ci_info.platform == "gitlab-ci":
+                logger.info(f"Detected MR number: {ci_info.cr_number}")
+            else:
+                logger.info(f"Detected CR number: {ci_info.cr_number}")
+        else:
+            logger.info("No CR number detected")
+
+        if ci_info.commit_sha:
+            logger.info(f"Detected commit SHA: {ci_info.commit_sha[:8]}...")
+        else:
+            logger.warning("Could not detect commit SHA")
+
+        logger.info(f"Detected base branch: {ci_info.base_branch}")
+        logger.info(f"Detected source branch: {ci_info.source_branch}")
+        logger.info(f"Session type: {ci_info.session_type}")
+
+        if ci_info.repository:
+            logger.info(f"Repository: {ci_info.repository}")

recce_cloud/ci_providers/github_actions.py

@@ -0,0 +1,136 @@
+"""
+GitHub Actions CI provider.
+"""
+
+import json
+import os
+from typing import Optional
+
+from recce_cloud.ci_providers.base import BaseCIProvider, CIInfo
+
+
+class GitHubActionsProvider(BaseCIProvider):
+    """GitHub Actions CI provider implementation."""
+
+    def can_handle(self) -> bool:
+        """
+        Check if running in GitHub Actions.
+
+        Returns:
+            True if GITHUB_ACTIONS environment variable is 'true'
+        """
+        return os.getenv("GITHUB_ACTIONS") == "true"
+
+    def extract_ci_info(self) -> CIInfo:
+        """
+        Extract CI information from GitHub Actions environment.
+
+        Environment variables used:
+        - GITHUB_EVENT_PATH: Path to event payload JSON (for PR number)
+        - GITHUB_SHA: Commit SHA
+        - GITHUB_BASE_REF: Base/target branch (PR only)
+        - GITHUB_HEAD_REF: Source/head branch (PR only)
+        - GITHUB_REF_NAME: Branch name (fallback)
+        - GITHUB_REPOSITORY: Repository (owner/repo)
+        - GITHUB_TOKEN: Default access token (automatically provided by GitHub Actions)
+
+        Returns:
+            CIInfo object with extracted information
+        """
+        cr_number = self._extract_pr_number()
+        commit_sha = self._extract_commit_sha()
+        base_branch = self._extract_base_branch()
+        source_branch = self._extract_source_branch()
+        repository = os.getenv("GITHUB_REPOSITORY")
+        access_token = os.getenv("GITHUB_TOKEN")
+
+        # Build CR URL (PR URL) if we have the necessary information
+        cr_url = None
+        if cr_number is not None and repository:
+            cr_url = f"https://github.com/{repository}/pull/{cr_number}"
+
+        session_type = self.determine_session_type(cr_number, source_branch)
+
+        return CIInfo(
+            platform="github-actions",
+            cr_number=cr_number,
+            cr_url=cr_url,
+            session_type=session_type,
+            commit_sha=commit_sha,
+            base_branch=base_branch,
+            source_branch=source_branch,
+            repository=repository,
+            access_token=access_token,
+        )
+
+    def _extract_pr_number(self) -> Optional[int]:
+        """
+        Extract PR number from GitHub event payload.
+
+        Returns:
+            PR number if detected, None otherwise
+        """
+        event_path = os.getenv("GITHUB_EVENT_PATH")
+        if not event_path or not os.path.exists(event_path):
+            return None
+
+        try:
+            with open(event_path, "r") as f:
+                event_data = json.load(f)
+                pr_data = event_data.get("pull_request", {})
+                pr_number = pr_data.get("number")
+                if pr_number is not None:
+                    return int(pr_number)
+        except (json.JSONDecodeError, ValueError, OSError):
+            pass
+
+        return None
+
+    def _extract_commit_sha(self) -> Optional[str]:
+        """
+        Extract commit SHA from GitHub Actions environment.
+
+        Returns:
+            Commit SHA if detected, falls back to git command
+        """
+        commit_sha = os.getenv("GITHUB_SHA")
+        if commit_sha:
+            return commit_sha
+
+        # Fallback to git command
+        return self.run_git_command(["git", "rev-parse", "HEAD"])
+
+    def _extract_base_branch(self) -> str:
+        """
+        Extract base/target branch from GitHub Actions environment.
+
+        Returns:
+            Base branch name, defaults to 'main' if not detected
+        """
+        # GITHUB_BASE_REF is only set for pull_request events
+        base_branch = os.getenv("GITHUB_BASE_REF")
+        if base_branch:
+            return base_branch
+
+        # Default to main
+        return "main"
+
+    def _extract_source_branch(self) -> Optional[str]:
+        """
+        Extract source/head branch from GitHub Actions environment.
+
+        Returns:
+            Source branch name if detected
+        """
+        # GITHUB_HEAD_REF is only set for pull_request events
+        source_branch = os.getenv("GITHUB_HEAD_REF")
+        if source_branch:
+            return source_branch
+
+        # Fallback to GITHUB_REF_NAME
+        source_branch = os.getenv("GITHUB_REF_NAME")
+        if source_branch:
+            return source_branch
+
+        # Fallback to git command
+        return self.run_git_command(["git", "branch", "--show-current"])