# Architecture Rules - Exception Handling Rules
# Rules for exception handling across the application

exception_rules:

  - id: "EXC-001"
    name: "Define custom exceptions in exceptions module"
    severity: "warning"
    description: |
      Create domain-specific exceptions in app/exceptions/ for better
      error handling and clarity.
    pattern:
      file_pattern:
        - "app/exceptions/**/*.py"
        - "app/modules/*/exceptions.py"
      encouraged_structure: |
        class VendorError(Exception):
            """Base exception for vendor-related errors"""
            pass

  - id: "EXC-002"
    name: "Never use bare except"
    severity: "error"
    description: |
      Always specify exception types. Bare except catches everything including
      KeyboardInterrupt and SystemExit.
    pattern:
      file_pattern: "**/*.py"
      anti_patterns:
        - "except:"
        - "except\\s*:"

  - id: "EXC-003"
    name: "Log all exceptions with context"
    severity: "warning"
    description: |
      When catching exceptions, log them with context and stack trace.
    pattern:
      file_pattern:
        - "app/services/**/*.py"
        - "app/modules/*/services/**/*.py"
      encouraged_patterns:
        - "logger.error"
        - "exc_info=True"

  - id: "EXC-004"
    name: "Domain exceptions must inherit from OrionException"
    severity: "error"
    description: |
      All custom domain exceptions must inherit from OrionException (or its
      subclasses like ResourceNotFoundException, ValidationException, etc.).
      This ensures the global exception handler catches and converts them properly.
    pattern:
      file_pattern:
        - "app/exceptions/**/*.py"
        - "app/modules/*/exceptions.py"
      required_base_class: "OrionException"
      example_good: |
        class VendorNotFoundException(ResourceNotFoundException):
            def __init__(self, vendor_code: str):
                super().__init__(resource_type="Vendor", identifier=vendor_code)

  - id: "EXC-005"
    name: "Exception handler must be registered"
    severity: "error"
    description: |
      The global exception handler must be set up in app initialization to
      catch OrionException and convert to HTTP responses.
    pattern:
      file_pattern: "app/main.py"
      required_patterns:
        - "setup_exception_handlers"