aws-inventory-manager 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

src/models/report.py

@@ -0,0 +1,276 @@
+"""
+Data models for snapshot resource reporting.
+
+This module defines the data structures used for generating and displaying
+snapshot resource reports, including metadata, summaries, filtered views,
+and detailed resource information.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, List, Literal, Optional, Tuple
+
+
+@dataclass
+class SnapshotMetadata:
+    """
+    Snapshot identification information for report header.
+
+    Attributes:
+        name: Snapshot name (e.g., "baseline-2025-01-29")
+        created_at: Snapshot creation timestamp
+        account_id: AWS account ID
+        regions: List of AWS regions included in snapshot
+        inventory_name: Parent inventory name
+        total_resource_count: Total number of resources in snapshot
+    """
+
+    name: str
+    created_at: datetime
+    account_id: str
+    regions: List[str]
+    inventory_name: str
+    total_resource_count: int
+
+    @property
+    def region_summary(self) -> str:
+        """Human-readable region list (e.g., 'us-east-1, us-west-2 (2 regions)')."""
+        if len(self.regions) <= 3:
+            return ", ".join(self.regions)
+        else:
+            return f"{', '.join(self.regions[:3])} ... ({len(self.regions)} regions)"
+
+
+@dataclass
+class ResourceSummary:
+    """
+    Aggregated resource counts for summary view.
+
+    Attributes:
+        total_count: Total number of resources
+        by_service: Count per AWS service (e.g., {"EC2": 100, "S3": 50})
+        by_region: Count per AWS region (e.g., {"us-east-1": 80, "us-west-2": 70})
+        by_type: Count per resource type (e.g., {"AWS::EC2::Instance": 50})
+    """
+
+    total_count: int = 0
+    by_service: Dict[str, int] = field(default_factory=dict)
+    by_region: Dict[str, int] = field(default_factory=dict)
+    by_type: Dict[str, int] = field(default_factory=dict)
+
+    @property
+    def service_count(self) -> int:
+        """Number of distinct AWS services."""
+        return len(self.by_service)
+
+    @property
+    def region_count(self) -> int:
+        """Number of distinct AWS regions."""
+        return len(self.by_region)
+
+    @property
+    def type_count(self) -> int:
+        """Number of distinct resource types."""
+        return len(self.by_type)
+
+    def top_services(self, limit: int = 5) -> List[Tuple[str, int]]:
+        """Return top N services by resource count."""
+        return sorted(self.by_service.items(), key=lambda x: x[1], reverse=True)[:limit]
+
+    def top_regions(self, limit: int = 5) -> List[Tuple[str, int]]:
+        """Return top N regions by resource count."""
+        return sorted(self.by_region.items(), key=lambda x: x[1], reverse=True)[:limit]
+
+
+@dataclass
+class FilteredResource:
+    """
+    Minimal resource info for filtered view (non-detailed).
+
+    Attributes:
+        arn: AWS Resource Name (unique identifier)
+        resource_type: CloudFormation resource type (e.g., "AWS::EC2::Instance")
+        name: Resource name or identifier
+        region: AWS region (e.g., "us-east-1")
+    """
+
+    arn: str
+    resource_type: str
+    name: str
+    region: str
+
+    @property
+    def service(self) -> str:
+        """Extract service name from resource type (e.g., "EC2" from "AWS::EC2::Instance")."""
+        parts = self.resource_type.split("::")
+        return parts[1] if len(parts) >= 2 else "Unknown"
+
+    @property
+    def short_type(self) -> str:
+        """Short resource type (e.g., "Instance" from "AWS::EC2::Instance")."""
+        parts = self.resource_type.split("::")
+        return parts[-1] if parts else self.resource_type
+
+
+@dataclass
+class DetailedResource:
+    """
+    Full resource details for detailed view.
+
+    Attributes:
+        arn: AWS Resource Name
+        resource_type: CloudFormation resource type
+        name: Resource name or identifier
+        region: AWS region
+        tags: Key-value tag pairs
+        created_at: Resource creation timestamp (if available)
+        config_hash: Configuration hash for change detection
+    """
+
+    arn: str
+    resource_type: str
+    name: str
+    region: str
+    tags: Dict[str, str]
+    created_at: Optional[datetime]
+    config_hash: str
+
+    @property
+    def service(self) -> str:
+        """Extract service name from resource type."""
+        parts = self.resource_type.split("::")
+        return parts[1] if len(parts) >= 2 else "Unknown"
+
+    @property
+    def age_days(self) -> Optional[int]:
+        """Calculate resource age in days (if creation date available)."""
+        if self.created_at:
+            from datetime import timezone
+
+            # Ensure we're comparing timezone-aware datetimes
+            now_utc = datetime.now(timezone.utc)
+            created = self.created_at if self.created_at.tzinfo else self.created_at.replace(tzinfo=timezone.utc)
+            return (now_utc - created).days
+        return None
+
+    @property
+    def tag_count(self) -> int:
+        """Number of tags applied to resource."""
+        return len(self.tags)
+
+    def has_tag(self, key: str, value: Optional[str] = None) -> bool:
+        """Check if resource has specific tag (optionally with value)."""
+        if key not in self.tags:
+            return False
+        if value is not None:
+            return self.tags[key] == value
+        return True
+
+
+@dataclass
+class FilterCriteria:
+    """
+    Filter specification for narrowing report results.
+
+    Attributes:
+        resource_types: List of resource types to include (flexible matching)
+        regions: List of AWS regions to include (exact matching)
+        match_mode: Matching strategy ("flexible" or "exact")
+    """
+
+    resource_types: Optional[List[str]] = None
+    regions: Optional[List[str]] = None
+    match_mode: Literal["flexible", "exact"] = "flexible"
+
+    def __post_init__(self) -> None:
+        """Normalize filter values (lowercase for case-insensitive matching)."""
+        if self.resource_types:
+            self.resource_types = [rt.lower() for rt in self.resource_types]
+        if self.regions:
+            self.regions = [r.lower() for r in self.regions]
+
+    @property
+    def has_filters(self) -> bool:
+        """Check if any filters are applied."""
+        return bool(self.resource_types or self.regions)
+
+    @property
+    def filter_count(self) -> int:
+        """Total number of filter criteria."""
+        count = 0
+        if self.resource_types:
+            count += len(self.resource_types)
+        if self.regions:
+            count += len(self.regions)
+        return count
+
+    def matches_resource(self, resource: FilteredResource) -> bool:
+        """
+        Check if resource matches filter criteria.
+
+        Uses flexible matching for resource types (see research.md Task 2).
+        Uses exact matching for regions (case-insensitive).
+        """
+        # Region filter (exact match, case-insensitive)
+        if self.regions and resource.region.lower() not in self.regions:
+            return False
+
+        # Resource type filter (flexible matching)
+        if self.resource_types:
+            type_match = any(
+                self._match_resource_type(resource.resource_type, filter_type) for filter_type in self.resource_types
+            )
+            if not type_match:
+                return False
+
+        return True
+
+    def _match_resource_type(self, resource_type: str, filter_value: str) -> bool:
+        """Three-tier matching: exact → prefix → contains (see research.md)."""
+        resource_lower = resource_type.lower()
+        filter_lower = filter_value.lower()
+
+        # Tier 1: Exact match
+        if resource_lower == filter_lower:
+            return True
+
+        # Tier 2: Service prefix match
+        service_prefix = f"aws::{filter_lower}::"
+        if resource_lower.startswith(service_prefix):
+            return True
+
+        # Tier 3: Contains match
+        if filter_lower in resource_lower:
+            return True
+
+        return False
+
+
+@dataclass
+class ResourceReport:
+    """
+    Complete report data structure.
+
+    Attributes:
+        snapshot_metadata: Information about the snapshot being reported
+        summary: Aggregated resource counts by service/region/type
+        filtered_resources: Minimal resource list (if filtering applied)
+        detailed_resources: Full resource details (if detailed view requested)
+    """
+
+    snapshot_metadata: SnapshotMetadata
+    summary: ResourceSummary
+    filtered_resources: Optional[List[FilteredResource]] = None
+    detailed_resources: Optional[List[DetailedResource]] = None
+
+    @property
+    def has_filters(self) -> bool:
+        """Check if report includes filtered results."""
+        return self.filtered_resources is not None
+
+    @property
+    def has_details(self) -> bool:
+        """Check if report includes detailed resource info."""
+        return self.detailed_resources is not None

src/snapshot/report_formatter.py

@@ -0,0 +1,250 @@
+"""
+Report output formatting using Rich for terminal UI.
+
+This module contains the ReportFormatter class responsible for rendering
+reports to the terminal with Rich tables, progress bars, and formatted output.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+
+from src.models.report import DetailedResource, ResourceSummary, SnapshotMetadata
+from src.utils.pagination import paginate_resources
+
+
+class ReportFormatter:
+    """
+    Formats and renders reports using Rich terminal UI.
+
+    Handles rendering of headers, summaries, tables, and progress bars
+    for snapshot resource reports.
+    """
+
+    def __init__(self, console: Optional[Console] = None) -> None:
+        """
+        Initialize formatter with Rich Console.
+
+        Args:
+            console: Rich Console instance (creates default if not provided)
+        """
+        self.console = console or Console()
+
+    def format_summary(
+        self,
+        metadata: SnapshotMetadata,
+        summary: ResourceSummary,
+        has_filters: bool = False,
+    ) -> None:
+        """
+        Format and display complete summary report.
+
+        Orchestrates all render methods to display header, service breakdown,
+        region breakdown, and type breakdown.
+
+        Args:
+            metadata: Snapshot metadata for header
+            summary: Resource summary with aggregated counts
+            has_filters: Whether filters were applied (shows "Filtered" indicator)
+        """
+        # Render header
+        self._render_header(metadata, has_filters)
+
+        # Add spacing
+        self.console.print()
+
+        # Render summary sections
+        self.console.print("📊 [bold]Resource Summary[/bold]\n")
+        self.console.print(f"Total Resources: [bold cyan]{summary.total_count:,}[/bold cyan]\n")
+
+        if summary.total_count > 0:
+            # Render service breakdown
+            self._render_service_breakdown(summary)
+
+            # Render region breakdown
+            self._render_region_breakdown(summary)
+
+            # Render type breakdown (top 10)
+            self._render_type_breakdown(summary)
+
+    def _render_header(self, metadata: SnapshotMetadata, has_filters: bool = False) -> None:
+        """
+        Render report header with snapshot metadata.
+
+        Args:
+            metadata: Snapshot metadata
+            has_filters: Whether to show "Filtered" indicator
+        """
+        title = f"Snapshot Report: {metadata.name}"
+        if has_filters:
+            title += " (Filtered)"
+
+        # Create header panel
+        header_content = f"""[bold]Inventory:[/bold]     {metadata.inventory_name}
+[bold]Account ID:[/bold]    {metadata.account_id}
+[bold]Created:[/bold]       {metadata.created_at.strftime('%Y-%m-%d %H:%M:%S UTC')}
+[bold]Regions:[/bold]       {metadata.region_summary}"""
+
+        panel = Panel(
+            header_content,
+            title=title,
+            border_style="blue",
+            expand=False,
+        )
+
+        self.console.print(panel)
+
+    def _render_service_breakdown(self, summary: ResourceSummary) -> None:
+        """
+        Render service breakdown with progress bars.
+
+        Args:
+            summary: Resource summary with service counts
+        """
+        if not summary.by_service:
+            return
+
+        self.console.print("[bold]By Service:[/bold]")
+
+        # Get top services (sorted by count)
+        top_services = summary.top_services(limit=10)
+
+        for service, count in top_services:
+            percentage = (count / summary.total_count) * 100
+            bar_length = int((count / summary.total_count) * 30)
+            bar = "█" * bar_length + "░" * (30 - bar_length)
+
+            self.console.print(f"  {service:15} {count:5}  {bar}  ({percentage:.1f}%)")
+
+        self.console.print()
+
+    def _render_region_breakdown(self, summary: ResourceSummary) -> None:
+        """
+        Render region breakdown with progress bars.
+
+        Args:
+            summary: Resource summary with region counts
+        """
+        if not summary.by_region:
+            return
+
+        self.console.print("[bold]By Region:[/bold]")
+
+        # Get top regions (sorted by count)
+        top_regions = summary.top_regions(limit=10)
+
+        for region, count in top_regions:
+            percentage = (count / summary.total_count) * 100
+            bar_length = int((count / summary.total_count) * 30)
+            bar = "█" * bar_length + "░" * (30 - bar_length)
+
+            self.console.print(f"  {region:15} {count:5}  {bar}  ({percentage:.1f}%)")
+
+        self.console.print()
+
+    def _render_type_breakdown(self, summary: ResourceSummary) -> None:
+        """
+        Render resource type breakdown showing top 10 types.
+
+        Args:
+            summary: Resource summary with type counts
+        """
+        if not summary.by_type:
+            return
+
+        self.console.print("[bold]Top 10 Resource Types:[/bold]")
+
+        # Get top 10 resource types
+        sorted_types = sorted(
+            summary.by_type.items(),
+            key=lambda x: x[1],
+            reverse=True,
+        )[:10]
+
+        for resource_type, count in sorted_types:
+            percentage = (count / summary.total_count) * 100
+            self.console.print(f"  {resource_type:45} {count:5}  ({percentage:.1f}%)")
+
+        self.console.print()
+
+    def format_detailed(
+        self,
+        metadata: SnapshotMetadata,
+        resources: List[DetailedResource],
+        page_size: int = 100,
+    ) -> None:
+        """
+        Format and display detailed resource view with pagination.
+
+        Args:
+            metadata: Snapshot metadata for header
+            resources: List of detailed resources to display
+            page_size: Number of resources per page (default: 100)
+        """
+        # Render header
+        self._render_header(metadata, has_filters=False)
+        self.console.print()
+
+        total_resources = len(resources)
+        self.console.print(f"Total Resources: [bold cyan]{total_resources:,}[/bold cyan]\n")
+
+        if total_resources == 0:
+            return
+
+        # Paginate resources
+        pages = list(paginate_resources(resources, page_size=page_size))
+        total_pages = len(pages)
+
+        # Display pages
+        for page_num, page in enumerate(pages, start=1):
+            for idx, resource in enumerate(page, start=1):
+                global_idx = (page_num - 1) * page_size + idx
+                self._render_detailed_resource(resource, global_idx, total_resources)
+
+            # Show pagination info (but no prompts - non-interactive for now)
+            if page_num < total_pages:
+                self.console.print(f"\n[dim]─── Page {page_num} of {total_pages} ───[/dim]\n")
+
+    def _render_detailed_resource(
+        self,
+        resource: DetailedResource,
+        index: int,
+        total: int,
+    ) -> None:
+        """
+        Render a single detailed resource.
+
+        Args:
+            resource: DetailedResource to display
+            index: Resource index (1-based)
+            total: Total number of resources
+        """
+        self.console.print("─" * 65)
+        self.console.print(f"[bold]Resource {index}/{total}[/bold]\n")
+
+        self.console.print(f"[bold]ARN:[/bold]          {resource.arn}")
+        self.console.print(f"[bold]Type:[/bold]         {resource.resource_type}")
+        self.console.print(f"[bold]Name:[/bold]         {resource.name}")
+        self.console.print(f"[bold]Region:[/bold]       {resource.region}")
+
+        # Show creation date if available
+        if resource.created_at:
+            age_str = ""
+            if resource.age_days is not None:
+                age_str = f" ({resource.age_days} days ago)"
+            created_str = resource.created_at.strftime("%Y-%m-%d %H:%M:%S UTC")
+            self.console.print(f"[bold]Created:[/bold]      {created_str}{age_str}")
+
+        # Show tags
+        self.console.print()
+        if resource.tags:
+            self.console.print("[bold]Tags:[/bold]")
+            for key, value in resource.tags.items():
+                self.console.print(f"  {key:20} {value}")
+        else:
+            self.console.print("[dim]No tags[/dim]")
+
+        self.console.print()