certora-prover-cli 0.1.0__py3-none-any.whl

prover_output_utility/api/base_data_fetcher.py

@@ -0,0 +1,176 @@
+# SPDX-FileCopyrightText: 2026 Certora Ltd.
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+"""
+Abstract base class for data fetchers.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+
+
+class BaseDataFetcher(ABC):
+    """Abstract base class for fetching prover data from different sources."""
+
+    @abstractmethod
+    def fetch_raw_output(self, job_identifier: str) -> Dict[str, Any]:
+        """
+        Fetch raw output data.
+
+        Args:
+            job_identifier: Job identifier (job ID for remote, emv path for local)
+
+        Returns:
+            Raw job data
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def fetch_tree_view_data(self, job_identifier: str, path: str = "treeViewStatus.json") -> Dict[str, Any]:
+        """
+        Fetch tree-view data.
+
+        Args:
+            job_identifier: Job identifier (job ID for remote, emv path for local)
+            path: Optional path within the tree-view
+
+        Returns:
+            Tree-view data
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def list_recent_jobs(
+        self,
+        created_after: str,
+        limit: int = 100,
+        all_users: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """
+        List recent jobs from the data API.
+
+        The data API's /v1/domain/jobs endpoint requires createdAfter to be set
+        explicitly so this is required.
+
+        Args:
+            created_after: ISO datetime string for range start (lower bound on createdAt)
+            limit: Maximum number of jobs to return (the API caps page size at 100)
+            all_users: If True, include jobs from all users; if False, only the authenticated user's
+
+        Returns:
+            List of raw job dicts as returned by the API
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def fetch_outputs(self, job_identifier: str) -> bytes:
+        """
+        Fetch outputs archive (tar.gz) for a job.
+
+        Args:
+            job_identifier: Job identifier (job ID for remote, emv path for local)
+
+        Returns:
+            Raw tar.gz content as bytes
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def cancel_jobs(self, job_ids: List[str]) -> Dict[str, Any]:
+        """
+        Cancel multiple jobs.
+
+        Args:
+            job_ids: List of job IDs to cancel
+
+        Returns:
+            API response data
+
+        Raises:
+            ProverAPIError: If cancellation fails
+        """
+        pass
+
+    @abstractmethod
+    def fetch_group_jobs(
+        self, group_id: str, created_after: str, created_before: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Fetch all jobs in a group.
+
+        The data API requires createdAfter/createdBefore params for the groupIds filter to work.
+
+        Args:
+            group_id: Group UUID
+            created_after: ISO datetime string for range start
+            created_before: ISO datetime string for range end
+
+        Returns:
+            List of job dicts
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def fetch_source_files_list(self, job_identifier: str) -> List[Dict[str, Any]]:
+        """
+        Fetch the source file tree for a job.
+
+        Args:
+            job_identifier: Job identifier (job ID for remote, emv path for local)
+
+        Returns:
+            List of source file tree nodes
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def fetch_source_file_content(self, job_identifier: str, path: str) -> str:
+        """
+        Fetch the content of a specific source file for a job.
+
+        Args:
+            job_identifier: Job identifier (job ID for remote, emv path for local)
+            path: Path to the source file (e.g. ".certora_sources/src/Contract.sol")
+
+        Returns:
+            Raw file content as a string
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass
+
+    @abstractmethod
+    def fetch_alert_report(self, job_identifier: str) -> List[Dict[str, Any]]:
+        """
+        Fetch alert report (alertReport.json) for a job.
+
+        Args:
+            job_identifier: Job identifier (job ID for remote, emv path for local)
+
+        Returns:
+            Alert report data as a list of alert objects
+
+        Raises:
+            ProverAPIError: If fetch fails
+        """
+        pass

prover_output_utility/api/cache.py

@@ -0,0 +1,149 @@
+# SPDX-FileCopyrightText: 2026 Certora Ltd.
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+"""
+Persistent cache for API responses to avoid repeated expensive API calls.
+"""
+
+import hashlib
+import json
+import logging
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class APICache:
+    """
+    Persistent file-based cache for API responses.
+    Caches breadcrumb data and other expensive API calls to disk.
+    Job data is immutable, so cached data never expires.
+    """
+    
+    def __init__(self, cache_dir: Optional[str] = None):
+        """
+        Initialize the API cache.
+        
+        Args:
+            cache_dir: Directory to store cache files. Defaults to .certora_internal/api_cache in current directory
+        """
+        self.logger = logging.getLogger(__name__)
+        
+        # Set cache directory - use current working directory by default
+        if cache_dir:
+            self.cache_dir = Path(cache_dir)
+        else:
+            self.cache_dir = Path.cwd() / ".certora_internal" / "api_cache"
+        
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Track cache statistics
+        self.hits = 0
+        self.misses = 0
+        
+        self.logger.debug(f"API cache initialized at {self.cache_dir}")
+    
+    def _get_cache_key(self, method: str, *args) -> str:
+        """Generate a cache key from method name and arguments."""
+        # Create a unique key from method and args
+        key_parts = [method] + [str(arg) for arg in args]
+        key_str = "|".join(key_parts)
+        
+        # Hash for filename safety
+        key_hash = hashlib.md5(key_str.encode()).hexdigest()
+        
+        return f"{method}_{key_hash[:16]}"
+    
+    def _get_cache_file(self, cache_key: str) -> Path:
+        """Get the cache file path for a given key."""
+        return self.cache_dir / f"{cache_key}.json"
+    
+    def _is_cache_valid(self, cache_file: Path) -> bool:
+        """Check if a cache file exists and is valid. Since job data is immutable, cache never expires."""
+        return cache_file.exists()
+    
+    def get(self, method: str, *args) -> Optional[Dict[str, Any]]:
+        """
+        Get cached data for a method call.
+        
+        Args:
+            method: Method name (e.g., 'get_breadcrumbs')
+            *args: Arguments to the method
+        
+        Returns:
+            Cached data if available and valid, None otherwise
+        """
+        cache_key = self._get_cache_key(method, *args)
+        cache_file = self._get_cache_file(cache_key)
+        
+        if self._is_cache_valid(cache_file):
+            try:
+                with open(cache_file, 'r') as f:
+                    data = json.load(f)
+                
+                self.hits += 1
+                self.logger.debug(f"Cache hit for {method} (key: {cache_key})")
+                return data.get('result')
+                
+            except Exception as e:
+                self.logger.warning(f"Failed to read cache file {cache_file}: {e}")
+                # Remove corrupted cache file
+                cache_file.unlink(missing_ok=True)
+        
+        self.misses += 1
+        self.logger.debug(f"Cache miss for {method} (key: {cache_key})")
+        return None
+    
+    def set(self, method: str, result: Any, *args) -> None:
+        """
+        Store data in cache.
+        
+        Args:
+            method: Method name
+            result: Result to cache
+            *args: Arguments to the method
+        """
+        cache_key = self._get_cache_key(method, *args)
+        cache_file = self._get_cache_file(cache_key)
+        
+        cache_data = {
+            'method': method,
+            'args': [str(arg) for arg in args],
+            'result': result,
+            'cached_at': datetime.now().isoformat()
+        }
+        
+        try:
+            with open(cache_file, 'w') as f:
+                json.dump(cache_data, f, indent=2, default=str)
+            
+            self.logger.debug(f"Cached result for {method} (key: {cache_key})")
+            
+        except Exception as e:
+            self.logger.warning(f"Failed to write cache file {cache_file}: {e}")
+    
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        for cache_file in self.cache_dir.glob("*.json"):
+            cache_file.unlink()
+        
+        self.logger.info(f"Cleared cache directory: {self.cache_dir}")
+        self.hits = 0
+        self.misses = 0
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        cache_files = list(self.cache_dir.glob("*.json"))
+        total_size = sum(f.stat().st_size for f in cache_files)
+        
+        return {
+            'cache_dir': str(self.cache_dir),
+            'total_files': len(cache_files),
+            'total_size_bytes': total_size,
+            'total_size_mb': total_size / (1024 * 1024),
+            'hits': self.hits,
+            'misses': self.misses,
+            'hit_rate': self.hits / (self.hits + self.misses) if (self.hits + self.misses) > 0 else 0
+        }