@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/collectors/completeness/bitbucket_probe.py

@@ -1,443 +0,0 @@
-"""Bitbucket remote signal probe for freshness detection.
-
-Phase 126 Package B - TSK-126.6
-Implements remote probe for Bitbucket repository freshness using latest
-commit SHA comparison (default_branch_ref:commit_id).
-"""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Any
-
-from structlog import get_logger
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.clients.bitbucket_cli_client import BitbucketCliClient
-
-logger = get_logger()
-
-
-class BitbucketProbe:
-    """Remote probe for checking Bitbucket repository freshness.
-
-    Uses the Bitbucket API to fetch the latest commit SHA for the default
-    branch and compare against cached commit information to determine if
-    a repository has changed.
-
-    Freshness levels (per AC-126.2.5):
-    - fresh: < 24 hours since last commit
-    - aging: 24-48 hours since last commit
-    - stale: > 48 hours OR remote signal mismatch
-    - unknown: probe failed
-
-    Example:
-        client = BitbucketCliClient()
-        probe = BitbucketProbe(client)
-
-        # Get latest commit SHA
-        sha = await probe.get_latest_commit_sha("PAR", "merchant-report")
-
-        # Check if repo changed since cached commit
-        changed, new_sha = await probe.check_changed("PAR", "merchant-report", "abc123")
-    """
-
-    # Freshness thresholds in hours (AC-126.2.5)
-    FRESH_THRESHOLD_HOURS = 24
-    AGING_THRESHOLD_HOURS = 48
-
-    def __init__(self, client: BitbucketCliClient) -> None:
-        """Initialize the probe with a Bitbucket client.
-
-        Args:
-            client: BitbucketCliClient instance for API calls
-        """
-        self.client = client
-
-    async def get_latest_commit_sha(
-        self,
-        project_key: str,
-        repo_slug: str,
-        branch: str = "main",
-    ) -> str | None:
-        """Get latest commit SHA for default branch.
-
-        Queries the Bitbucket API for the latest commit on the specified
-        branch. Uses the commits endpoint which returns commit id/hash.
-
-        Args:
-            project_key: Bitbucket project key (e.g., "PAR", "CEP")
-            repo_slug: Repository slug (e.g., "merchant-report")
-            branch: Branch name to query (default: "main")
-
-        Returns:
-            Latest commit SHA/hash string, or None if unavailable
-
-        Raises:
-            DataSourceError: If the API call fails
-        """
-        try:
-            commits = await self.client.get_commits(
-                project_key=str(project_key),
-                repo_slug=str(repo_slug),
-                limit=1,
-            )
-
-            if not commits or not isinstance(commits, list):
-                logger.warning(
-                    "bitbucket_probe_no_commits",
-                    project=project_key,
-                    repo=repo_slug,
-                    branch=branch,
-                    reason="empty_or_invalid_response",
-                )
-                return None
-
-            latest = commits[0]
-            if not isinstance(latest, dict):
-                logger.warning(
-                    "bitbucket_probe_invalid_commit",
-                    project=project_key,
-                    repo=repo_slug,
-                    reason="commit_not_dict",
-                )
-                return None
-
-            # Extract commit ID/hash - try multiple keys
-            commit_id = (
-                latest.get("id") or latest.get("hash") or latest.get("commitId") or latest.get("commit", {}).get("id")
-            )
-
-            if not commit_id or not isinstance(commit_id, str):
-                logger.warning(
-                    "bitbucket_probe_no_commit_id",
-                    project=project_key,
-                    repo=repo_slug,
-                    reason="id_missing",
-                )
-                return None
-
-            return commit_id.strip()
-
-        except Exception as e:
-            logger.exception(
-                "bitbucket_probe_get_commit_sha_failed",
-                project=project_key,
-                repo=repo_slug,
-                branch=branch,
-                error=str(e),
-            )
-            return None
-
-    async def get_default_branch(self, project_key: str, repo_slug: str) -> str | None:
-        """Get the default branch name for a repository.
-
-        Args:
-            project_key: Bitbucket project key
-            repo_slug: Repository slug
-
-        Returns:
-            Default branch name (e.g., "main", "master"), or None if unavailable
-        """
-        try:
-            branch_info = await self.client.get_default_branch(
-                project_key=str(project_key),
-                repo_slug=str(repo_slug),
-            )
-
-            if not isinstance(branch_info, dict):
-                return None
-
-            # Try multiple possible response structures
-            branch = (
-                branch_info.get("displayId")
-                or branch_info.get("id")
-                or branch_info.get("name")
-                or branch_info.get("value")
-                or branch_info.get("defaultBranch", {}).get("id")
-            )
-
-            if isinstance(branch, str) and branch.strip():
-                return branch.strip()
-
-            return None
-
-        except Exception as e:
-            logger.exception(
-                "bitbucket_probe_get_default_branch_failed",
-                project=project_key,
-                repo=repo_slug,
-                error=str(e),
-            )
-            return None
-
-    async def get_last_commit_timestamp(
-        self,
-        project_key: str,
-        repo_slug: str,
-    ) -> datetime | None:
-        """Get the timestamp of the most recent commit.
-
-        Args:
-            project_key: Bitbucket project key
-            repo_slug: Repository slug
-
-        Returns:
-            Datetime of last commit in UTC, or None if unavailable
-        """
-        try:
-            commits = await self.client.get_commits(
-                project_key=str(project_key),
-                repo_slug=str(repo_slug),
-                limit=1,
-            )
-
-            if not commits or not isinstance(commits, list):
-                return None
-
-            latest = commits[0]
-            if not isinstance(latest, dict):
-                return None
-
-            # Try multiple timestamp fields
-            timestamp_str = (
-                latest.get("authorTimestamp")
-                or latest.get("date")
-                or latest.get("timestamp")
-                or latest.get("author", {}).get("timestamp")
-            )
-
-            if not timestamp_str:
-                return None
-
-            # Parse ISO 8601 or Unix timestamp (milliseconds)
-            try:
-                # Try Unix timestamp in milliseconds first
-                if isinstance(timestamp_str, (int, float)) or str(timestamp_str).isdigit():
-                    millis = int(timestamp_str)
-                    return datetime.fromtimestamp(millis / 1000, tz=UTC).replace(tzinfo=None)
-                # Try ISO 8601 format
-                parsed = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
-                if parsed.tzinfo is not None:
-                    return parsed.astimezone(UTC).replace(tzinfo=None)
-                return parsed
-            except (ValueError, OSError):
-                return None
-
-        except Exception as e:
-            logger.exception(
-                "bitbucket_probe_get_timestamp_failed",
-                project=project_key,
-                repo=repo_slug,
-                error=str(e),
-            )
-            return None
-
-    def calculate_freshness(
-        self,
-        last_commit: datetime | None,
-    ) -> tuple[str, int | None]:
-        """Calculate freshness level from last commit timestamp.
-
-        Args:
-            last_commit: Datetime of last commit, or None if unknown
-                Can be timezone-aware or naive (assumed UTC).
-
-        Returns:
-            Tuple of (freshness_level, hours_since_commit)
-            - freshness_level: "fresh", "aging", "stale", or "unknown"
-            - hours_since_commit: Hours since last commit, or None
-        """
-        if last_commit is None:
-            return "unknown", None
-
-        now = datetime.now(UTC)
-        # Ensure both datetimes are timezone-aware for comparison
-        if last_commit.tzinfo is None:
-            # Assume naive datetimes are UTC
-            last_commit = last_commit.replace(tzinfo=UTC)
-
-        # Convert to UTC and remove tzinfo for calculation
-        now_utc = now.replace(tzinfo=None)
-        last_utc = last_commit.astimezone(UTC).replace(tzinfo=None)
-        hours_ago = (now_utc - last_utc).total_seconds() / 3600
-
-        if hours_ago < self.FRESH_THRESHOLD_HOURS:
-            return "fresh", int(hours_ago)
-        elif hours_ago < self.AGING_THRESHOLD_HOURS:
-            return "aging", int(hours_ago)
-        else:
-            return "stale", int(hours_ago)
-
-    async def check_changed(
-        self,
-        project_key: str,
-        repo_slug: str,
-        cached_commit_sha: str | None,
-    ) -> tuple[bool, str | None]:
-        """Check if repo changed since cached commit.
-
-        Compares the current latest commit SHA from the remote API against
-        the cached commit SHA to determine if the repository has been modified.
-
-        Args:
-            project_key: Bitbucket project key (e.g., "PAR", "CEP")
-            repo_slug: Repository slug (e.g., "merchant-report")
-            cached_commit_sha: Previously cached commit SHA
-
-        Returns:
-            Tuple of (changed, new_commit_sha):
-            - changed: True if commit SHA differs from cache
-            - new_commit_sha: Current commit SHA, or None if probe failed
-
-        Example:
-            >>> probe = BitbucketProbe(client)
-            >>> changed, new_sha = await probe.check_changed("PAR", "merchant-report", "abc123")
-            >>> if changed:
-            ...     print(f"Repo updated to commit {new_sha}")
-        """
-        current_sha = await self.get_latest_commit_sha(str(project_key), str(repo_slug))
-
-        if current_sha is None:
-            logger.warning(
-                "bitbucket_probe_check_changed_failed",
-                project=project_key,
-                repo=repo_slug,
-                cached_commit_sha=cached_commit_sha,
-                reason="current_sha_unavailable",
-            )
-            return False, None
-
-        # Normalize cached SHA for comparison
-        cached_normalized: str | None = None
-        if cached_commit_sha:
-            cached_normalized = str(cached_commit_sha).strip()
-
-        changed = cached_normalized is None or current_sha != cached_normalized
-
-        logger.debug(
-            "bitbucket_probe_check_changed",
-            project=project_key,
-            repo=repo_slug,
-            cached_sha=cached_normalized[:8] if cached_normalized else None,
-            current_sha=current_sha[:8],
-            changed=changed,
-        )
-
-        return changed, current_sha
-
-    async def get_repo_metadata(
-        self,
-        project_key: str,
-        repo_slug: str,
-    ) -> dict[str, Any] | None:
-        """Get comprehensive repository metadata for freshness checking.
-
-        Fetches latest commit and default branch information for
-        completeness assessment.
-
-        Args:
-            project_key: Bitbucket project key
-            repo_slug: Repository slug
-
-        Returns:
-            Dictionary containing:
-            - project_key: The project key
-            - repo_slug: The repository slug
-            - default_branch: Default branch name
-            - latest_commit_sha: Latest commit SHA
-            - last_commit_timestamp: ISO timestamp of last commit
-            - freshness: "fresh", "aging", "stale", or "unknown"
-            - hours_since_commit: Hours since last commit or None
-            Or None if the probe fails
-        """
-        try:
-            latest_sha = await self.get_latest_commit_sha(str(project_key), str(repo_slug))
-            default_branch = await self.get_default_branch(str(project_key), str(repo_slug))
-            last_commit = await self.get_last_commit_timestamp(str(project_key), str(repo_slug))
-
-            freshness, hours_ago = self.calculate_freshness(last_commit)
-
-            # Format timestamp for output
-            timestamp_str: str | None = None
-            if last_commit:
-                timestamp_str = last_commit.isoformat()
-
-            return {
-                "project_key": str(project_key),
-                "repo_slug": str(repo_slug),
-                "default_branch": default_branch,
-                "latest_commit_sha": latest_sha,
-                "last_commit_timestamp": timestamp_str,
-                "freshness": freshness,
-                "hours_since_commit": hours_ago,
-            }
-
-        except Exception as e:
-            logger.exception(
-                "bitbucket_probe_get_metadata_failed",
-                project=project_key,
-                repo=repo_slug,
-                error=str(e),
-            )
-            return None
-
-    async def check_changed_with_branch(
-        self,
-        project_key: str,
-        repo_slug: str,
-        cached_commit_sha: str | None,
-        cached_branch: str | None = None,
-    ) -> tuple[bool, str | None, str | None]:
-        """Check if repo changed, considering both commit SHA and branch.
-
-        Extended version that also checks if the default branch has changed,
-        which could indicate a repository reconfiguration.
-
-        Args:
-            project_key: Bitbucket project key
-            repo_slug: Repository slug
-            cached_commit_sha: Previously cached commit SHA
-            cached_branch: Previously cached default branch name
-
-        Returns:
-            Tuple of (changed, new_commit_sha, new_branch):
-            - changed: True if commit SHA or branch differs from cache
-            - new_commit_sha: Current commit SHA, or None if probe failed
-            - new_branch: Current default branch, or None if probe failed
-        """
-        current_sha = await self.get_latest_commit_sha(str(project_key), str(repo_slug))
-        current_branch = await self.get_default_branch(str(project_key), str(repo_slug))
-
-        if current_sha is None:
-            logger.warning(
-                "bitbucket_probe_check_changed_with_branch_failed",
-                project=project_key,
-                repo=repo_slug,
-                cached_commit_sha=cached_commit_sha,
-                cached_branch=cached_branch,
-                reason="current_data_unavailable",
-            )
-            return False, None, None
-
-        cached_sha_normalized = str(cached_commit_sha).strip() if cached_commit_sha else None
-        cached_branch_normalized = str(cached_branch).strip() if cached_branch else None
-
-        sha_changed = cached_sha_normalized is None or current_sha != cached_sha_normalized
-        branch_changed = cached_branch_normalized is not None and current_branch != cached_branch_normalized
-        changed = sha_changed or branch_changed
-
-        logger.debug(
-            "bitbucket_probe_check_changed_with_branch",
-            project=project_key,
-            repo=repo_slug,
-            cached_sha=cached_sha_normalized[:8] if cached_sha_normalized else None,
-            current_sha=current_sha[:8],
-            cached_branch=cached_branch_normalized,
-            current_branch=current_branch,
-            sha_changed=sha_changed,
-            branch_changed=branch_changed,
-            changed=changed,
-        )
-
-        return changed, current_sha, current_branch