recce-nightly 1.2.0.20250506__py3-none-any.whl → 1.26.0.20251124__py3-none-any.whl

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"])

recce_cloud/ci_providers/gitlab_ci.py

@@ -0,0 +1,130 @@
+"""
+GitLab CI/CD provider.
+"""
+
+import os
+from typing import Optional
+
+from recce_cloud.ci_providers.base import BaseCIProvider, CIInfo
+
+
+class GitLabCIProvider(BaseCIProvider):
+    """GitLab CI/CD provider implementation."""
+
+    def can_handle(self) -> bool:
+        """
+        Check if running in GitLab CI.
+
+        Returns:
+            True if GITLAB_CI environment variable is 'true'
+        """
+        return os.getenv("GITLAB_CI") == "true"
+
+    def extract_ci_info(self) -> CIInfo:
+        """
+        Extract CI information from GitLab CI environment.
+
+        Environment variables used:
+        - CI_MERGE_REQUEST_IID: Merge request number
+        - CI_COMMIT_SHA: Commit SHA
+        - CI_MERGE_REQUEST_TARGET_BRANCH_NAME: Target branch (MR only)
+        - CI_MERGE_REQUEST_SOURCE_BRANCH_NAME: Source branch (MR only)
+        - CI_COMMIT_REF_NAME: Branch name (fallback)
+        - CI_PROJECT_PATH: Repository path (group/project)
+        - CI_SERVER_URL: GitLab instance URL (defaults to https://gitlab.com)
+        - CI_JOB_TOKEN: Default access token (automatically provided by GitLab CI)
+
+        Returns:
+            CIInfo object with extracted information
+        """
+        cr_number = self._extract_mr_number()
+        commit_sha = self._extract_commit_sha()
+        base_branch = self._extract_base_branch()
+        source_branch = self._extract_source_branch()
+        repository = os.getenv("CI_PROJECT_PATH")
+        access_token = os.getenv("CI_JOB_TOKEN")
+
+        # Build CR URL (MR URL) if we have the necessary information
+        cr_url = None
+        if cr_number is not None and repository:
+            server_url = os.getenv("CI_SERVER_URL", "https://gitlab.com")
+            cr_url = f"{server_url}/{repository}/-/merge_requests/{cr_number}"
+
+        session_type = self.determine_session_type(cr_number, source_branch)
+
+        return CIInfo(
+            platform="gitlab-ci",
+            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_mr_number(self) -> Optional[int]:
+        """
+        Extract MR number from GitLab CI environment.
+
+        Returns:
+            MR number if detected, None otherwise
+        """
+        mr_iid = os.getenv("CI_MERGE_REQUEST_IID")
+        if mr_iid:
+            try:
+                return int(mr_iid)
+            except ValueError:
+                pass
+
+        return None
+
+    def _extract_commit_sha(self) -> Optional[str]:
+        """
+        Extract commit SHA from GitLab CI environment.
+
+        Returns:
+            Commit SHA if detected, falls back to git command
+        """
+        commit_sha = os.getenv("CI_COMMIT_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 GitLab CI environment.
+
+        Returns:
+            Base branch name, defaults to 'main' if not detected
+        """
+        # CI_MERGE_REQUEST_TARGET_BRANCH_NAME is only set for merge request pipelines
+        base_branch = os.getenv("CI_MERGE_REQUEST_TARGET_BRANCH_NAME")
+        if base_branch:
+            return base_branch
+
+        # Default to main
+        return "main"
+
+    def _extract_source_branch(self) -> Optional[str]:
+        """
+        Extract source branch from GitLab CI environment.
+
+        Returns:
+            Source branch name if detected
+        """
+        # CI_MERGE_REQUEST_SOURCE_BRANCH_NAME is only set for merge request pipelines
+        source_branch = os.getenv("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME")
+        if source_branch:
+            return source_branch
+
+        # Fallback to CI_COMMIT_REF_NAME
+        source_branch = os.getenv("CI_COMMIT_REF_NAME")
+        if source_branch:
+            return source_branch
+
+        # Fallback to git command
+        return self.run_git_command(["git", "branch", "--show-current"])

recce_cloud/cli.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python
+"""
+Recce Cloud CLI - Lightweight command for managing Recce Cloud operations.
+"""
+
+import logging
+import os
+import sys
+
+import click
+from rich.console import Console
+from rich.logging import RichHandler
+
+from recce_cloud import __version__
+from recce_cloud.artifact import get_adapter_type, verify_artifacts_path
+from recce_cloud.ci_providers import CIDetector
+from recce_cloud.upload import upload_to_existing_session, upload_with_platform_apis
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    handlers=[RichHandler(console=Console(stderr=True), show_time=False, show_path=False)],
+)
+logger = logging.getLogger(__name__)
+
+# Suppress CI detector logs since we display formatted output in the CLI
+logging.getLogger("recce_cloud.ci_providers.detector").setLevel(logging.WARNING)
+
+
+@click.group()
+def cloud_cli():
+    """
+    Recce Cloud CLI - Manage Recce Cloud sessions and state files.
+
+    A lightweight tool for CI/CD environments to interact with Recce Cloud
+    without the heavy dependencies of the full recce package.
+    """
+    pass
+
+
+@cloud_cli.command()
+def version():
+    """Show the version of recce-cloud."""
+    click.echo(__version__)
+
+
+@cloud_cli.command()
+@click.option(
+    "--target-path",
+    type=click.Path(exists=True),
+    default="target",
+    help="Path to dbt target directory containing manifest.json and catalog.json",
+)
+@click.option(
+    "--session-id",
+    envvar="RECCE_SESSION_ID",
+    help="Recce Cloud session ID to upload artifacts to (or use RECCE_SESSION_ID env var). "
+    "If not provided, session will be created automatically using platform-specific APIs (GitHub/GitLab).",
+)
+@click.option(
+    "--cr",
+    type=int,
+    help="Change request number (PR/MR) (overrides auto-detection)",
+)
+@click.option(
+    "--type",
+    "session_type",
+    type=click.Choice(["cr", "prod", "dev"]),
+    help="Session type (overrides auto-detection)",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be uploaded without actually uploading",
+)
+def upload(target_path, session_id, cr, session_type, dry_run):
+    """
+    Upload dbt artifacts (manifest.json, catalog.json) to Recce Cloud.
+
+    \b
+    Authentication (auto-detected):
+    - RECCE_API_TOKEN (for --session-id workflow)
+    - GITHUB_TOKEN (GitHub Actions)
+    - CI_JOB_TOKEN (GitLab CI)
+
+    \b
+    Common Examples:
+      # Auto-create session in PR/MR
+      recce-cloud upload
+
+      # Upload production metadata from main branch
+      recce-cloud upload --type prod
+
+      # Upload to specific session
+      recce-cloud upload --session-id abc123
+
+      # Custom target path
+      recce-cloud upload --target-path custom-target
+    """
+    console = Console()
+
+    # 1. Auto-detect CI environment information
+    console.rule("CI Environment Detection", style="blue")
+    try:
+        ci_info = CIDetector.detect()
+        ci_info = CIDetector.apply_overrides(ci_info, cr=cr, session_type=session_type)
+
+        # Display detected CI information immediately
+        if ci_info:
+            info_table = []
+            if ci_info.platform:
+                info_table.append(f"[cyan]Platform:[/cyan] {ci_info.platform}")
+
+            # Display CR number as PR or MR based on platform
+            if ci_info.cr_number is not None:
+                if ci_info.platform == "github-actions":
+                    info_table.append(f"[cyan]PR Number:[/cyan] {ci_info.cr_number}")
+                elif ci_info.platform == "gitlab-ci":
+                    info_table.append(f"[cyan]MR Number:[/cyan] {ci_info.cr_number}")
+                else:
+                    info_table.append(f"[cyan]CR Number:[/cyan] {ci_info.cr_number}")
+
+            # Display CR URL as PR URL or MR URL based on platform
+            if ci_info.cr_url:
+                if ci_info.platform == "github-actions":
+                    info_table.append(f"[cyan]PR URL:[/cyan] {ci_info.cr_url}")
+                elif ci_info.platform == "gitlab-ci":
+                    info_table.append(f"[cyan]MR URL:[/cyan] {ci_info.cr_url}")
+                else:
+                    info_table.append(f"[cyan]CR URL:[/cyan] {ci_info.cr_url}")
+
+            if ci_info.session_type:
+                info_table.append(f"[cyan]Session Type:[/cyan] {ci_info.session_type}")
+            if ci_info.commit_sha:
+                info_table.append(f"[cyan]Commit SHA:[/cyan] {ci_info.commit_sha[:8]}...")
+            if ci_info.base_branch:
+                info_table.append(f"[cyan]Base Branch:[/cyan] {ci_info.base_branch}")
+            if ci_info.source_branch:
+                info_table.append(f"[cyan]Source Branch:[/cyan] {ci_info.source_branch}")
+            if ci_info.repository:
+                info_table.append(f"[cyan]Repository:[/cyan] {ci_info.repository}")
+
+            for line in info_table:
+                console.print(line)
+        else:
+            console.print("[yellow]No CI environment detected[/yellow]")
+    except Exception as e:
+        console.print(f"[yellow]Warning:[/yellow] Failed to detect CI environment: {e}")
+        console.print("Continuing without CI metadata...")
+        ci_info = None
+
+    # 2. Validate artifacts exist
+    if not verify_artifacts_path(target_path):
+        console.print(f"[red]Error:[/red] Invalid target path: {target_path}")
+        console.print("Please provide a valid target path containing manifest.json and catalog.json.")
+        sys.exit(3)
+
+    manifest_path = os.path.join(target_path, "manifest.json")
+    catalog_path = os.path.join(target_path, "catalog.json")
+
+    # 3. Extract adapter type from manifest
+    try:
+        adapter_type = get_adapter_type(manifest_path)
+    except Exception as e:
+        console.print("[red]Error:[/red] Failed to parse adapter type from manifest.json")
+        console.print(f"Reason: {e}")
+        sys.exit(3)
+
+    # 4. Handle dry-run mode (before authentication or API calls)
+    if dry_run:
+        console.rule("Dry Run Summary", style="yellow")
+        console.print("[yellow]Dry run mode enabled - no actual upload will be performed[/yellow]")
+        console.print()
+
+        # Display platform information if detected
+        if ci_info and ci_info.platform:
+            console.print("[cyan]Platform Information:[/cyan]")
+            console.print(f"  • Platform: {ci_info.platform}")
+            if ci_info.repository:
+                console.print(f"  • Repository: {ci_info.repository}")
+            if ci_info.cr_number is not None:
+                console.print(f"  • CR Number: {ci_info.cr_number}")
+            if ci_info.commit_sha:
+                console.print(f"  • Commit SHA: {ci_info.commit_sha[:8]}")
+            if ci_info.source_branch:
+                console.print(f"  • Source Branch: {ci_info.source_branch}")
+            if ci_info.base_branch:
+                console.print(f"  • Base Branch: {ci_info.base_branch}")
+            if ci_info.session_type:
+                console.print(f"  • Session Type: {ci_info.session_type}")
+            console.print()
+
+        # Display upload summary
+        console.print("[cyan]Upload Workflow:[/cyan]")
+        if session_id:
+            console.print("  • Upload to existing session")
+            console.print(f"  • Session ID: {session_id}")
+        else:
+            console.print("  • Auto-create session and upload")
+            if ci_info and ci_info.platform in ["github-actions", "gitlab-ci"]:
+                console.print("  • Platform-specific APIs will be used")
+            else:
+                console.print("  • [yellow]Warning: Platform not supported for auto-session creation[/yellow]")
+
+        console.print()
+        console.print("[cyan]Files to upload:[/cyan]")
+        console.print(f"  • manifest.json: {os.path.abspath(manifest_path)}")
+        console.print(f"  • catalog.json: {os.path.abspath(catalog_path)}")
+        console.print(f"  • Adapter type: {adapter_type}")
+
+        console.print()
+        console.print("[green]✓[/green] Dry run completed successfully")
+        sys.exit(0)
+
+    # 5. Choose upload workflow based on whether session_id is provided
+    if session_id:
+        # Generic workflow: Upload to existing session using session ID
+        # This workflow requires RECCE_API_TOKEN
+        token = os.getenv("RECCE_API_TOKEN")
+        if not token:
+            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided")
+            console.print("Set RECCE_API_TOKEN environment variable for session-based upload")
+            sys.exit(2)
+
+        upload_to_existing_session(console, token, session_id, manifest_path, catalog_path, adapter_type, target_path)
+    else:
+        # Platform-specific workflow: Use platform APIs to create session and upload
+        # This workflow MUST use CI job tokens (CI_JOB_TOKEN or GITHUB_TOKEN)
+        if not ci_info or not ci_info.access_token:
+            console.print("[red]Error:[/red] Platform-specific upload requires CI environment")
+            console.print("Either run in GitHub Actions/GitLab CI or provide --session-id for generic upload")
+            sys.exit(2)
+
+        token = ci_info.access_token
+        if ci_info.platform == "github-actions":
+            console.print("[cyan]Info:[/cyan] Using GITHUB_TOKEN for platform-specific authentication")
+        elif ci_info.platform == "gitlab-ci":
+            console.print("[cyan]Info:[/cyan] Using CI_JOB_TOKEN for platform-specific authentication")
+
+        upload_with_platform_apis(console, token, ci_info, manifest_path, catalog_path, adapter_type, target_path)
+
+
+if __name__ == "__main__":
+    cloud_cli()