kya-validator 0.2.3

"""
Policy validation interfaces for KYA Validator.

This module provides policy evaluation interfaces and advanced
policy engine bindings.
"""

from typing import Optional, Any
from .types import PolicyContext, ValidationReport


class PolicyEngine:
    """Policy engine for evaluating advanced policy rules.

    This class provides a Pythonic interface to the Rust
    PolicyEngine for evaluating complex policy rules.

    Examples
    --------
    >>> engine = PolicyEngine()
    >>> result = engine.evaluate(manifest, context)
    >>> print(result.allowed)
    True
    """

    def __init__(self):
        """Initialize policy engine.

        Currently a placeholder that will be extended with
        PyO3 bindings to Rust PolicyEngine.
        """
        # Placeholder for future PyO3 bindings
        self._policies = []

    def add_policy(self, policy: dict[str, Any]) -> None:
        """Add a policy to the engine.

        Parameters
        ----------
        policy : dict
            Policy definition with rules.
        """
        self._policies.append(policy)

    def evaluate(
        self,
        manifest: dict[str, Any],
        context: Optional[PolicyContext] = None,
    ) -> 'PolicyEvaluationResult':
        """Evaluate all policies against a manifest.

        Parameters
        ----------
        manifest : dict
            Manifest to evaluate.
        context : PolicyContext, optional
            Evaluation context (region, transaction value, etc.).

        Returns
        -------
        PolicyEvaluationResult
            Evaluation result with allowed status and warnings.
        """
        # Placeholder for future PyO3 bindings
        return PolicyEvaluationResult(
            allowed=True,
            warnings=[],
            rule_results=[],
        )


class PolicyEvaluationResult:
    """Result of policy evaluation.

    This dataclass contains the results of policy evaluation.

    Attributes
    ----------
    allowed : bool
        Whether the manifest is allowed by policies.
    warnings : list[str]
        Warning messages from policy evaluation.
    rule_results : list[dict[str, Any]]
        Results from individual policy rules.
    """

    def __init__(
        self,
        allowed: bool,
        warnings: list[str],
        rule_results: list[dict[str, Any]],
    ):
        """Initialize policy evaluation result.

        Parameters
        ----------
        allowed : bool
            Whether the manifest is allowed.
        warnings : list[str]
            Warning messages.
        rule_results : list[dict]
            Individual rule results.
        """
        self.allowed = allowed
        self.warnings = warnings
        self.rule_results = rule_results

    def to_dict(self) -> dict[str, Any]:
        """Convert result to dictionary.

        Returns
        -------
        dict
            Dictionary representation of result.
        """
        return {
            'allowed': self.allowed,
            'warnings': self.warnings,
            'ruleResults': self.rule_results,
        }


def evaluate_policy(
    manifest: dict[str, Any],
    context: Optional[PolicyContext] = None,
    rules: Optional[list[dict[str, Any]]] = None,
) -> bool:
    """Evaluate simple policy rules against a manifest.

    This function evaluates basic policy rules like region
    restrictions and transaction value limits.

    Parameters
    ----------
    manifest : dict
            Manifest to evaluate.
    context : PolicyContext, optional
            Evaluation context.
    rules : list[dict], optional
            Policy rules to evaluate.

    Returns
    -------
    bool
            True if all rules pass, False otherwise.

    Examples
    --------
    >>> manifest = {'permittedRegions': ['US', 'EU']}
    >>> context = PolicyContext(requested_region='US')
    >>> evaluate_policy(manifest, context)
    True
    """
    if context is None:
        context = PolicyContext()

    # Check permitted regions
    if context.requested_region:
        permitted = manifest.get('permittedRegions')
        if permitted and context.requested_region not in permitted:
            return False

        forbidden = manifest.get('forbiddenRegions')
        if forbidden and context.requested_region in forbidden:
            return False

    # Check transaction value
    if context.transaction_value is not None:
        max_value = manifest.get('maxTransactionValue')
        if max_value and context.transaction_value > max_value:
            return False

    return True


def create_policy(
    name: str,
    rules: list[dict[str, Any]],
    description: Optional[str] = None,
) -> dict[str, Any]:
    """Create a policy definition.

    Parameters
    ----------
    name : str
        Policy name.
    rules : list[dict]
        Policy rules.
    description : str, optional
        Policy description.

    Returns
    -------
    dict
        Policy definition.
    """
    policy = {
        'id': name,
        'name': name,
        'version': '1.0.0',
        'rules': rules,
    }
    if description:
        policy['description'] = description
    return policy


def create_rule(
    name: str,
    condition: dict[str, Any],
    action: str,
    enabled: bool = True,
    priority: int = 0,
) -> dict[str, Any]:
    """Create a policy rule definition.

    Parameters
    ----------
    name : str
        Rule name.
    condition : dict
        Rule condition (JSON pointer, operator, value).
    action : str
        Action to take ('allow', 'deny', 'warn', 'log').
    enabled : bool, optional
        Whether rule is enabled. Default is True.
    priority : int, optional
        Rule priority (higher evaluated first). Default is 0.

    Returns
    -------
    dict
        Rule definition.
    """
    return {
        'name': name,
        'description': f'Rule: {name}',
        'condition': condition,
        'action': action,
        'enabled': enabled,
        'priority': priority,
    }