omnibase_infra 0.2.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

omnibase_infra/nodes/architecture_validator/handlers/handler_architecture_validation.py

@@ -0,0 +1,359 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler for architecture validation operations.
+
+This handler processes architecture validation requests by validating nodes and
+handlers against configurable architecture rules. It implements the validation
+logic that was previously in NodeArchitectureValidatorCompute.
+
+Design Pattern:
+    HandlerArchitectureValidation follows the ONEX handler pattern:
+    - Receives strongly-typed request (ModelArchitectureValidationRequest)
+    - Returns strongly-typed result (ModelArchitectureValidationResult)
+    - Manages validation rules internally
+    - Stateless operation (rules injected at construction)
+
+Thread Safety:
+    The handler is thread-safe when used with immutable rules. Each handle()
+    call is independent and does not modify shared state.
+
+Related:
+    - OMN-1138: Architecture Validator for omnibase_infra
+    - OMN-1726: Refactor to declarative pattern with contract-driven handler
+
+Example:
+    >>> from omnibase_infra.nodes.architecture_validator.handlers import (
+    ...     HandlerArchitectureValidation,
+    ... )
+    >>> from omnibase_infra.nodes.architecture_validator.models import (
+    ...     ModelArchitectureValidationRequest,
+    ... )
+    >>>
+    >>> # Create handler with rules
+    >>> handler = HandlerArchitectureValidation(
+    ...     rules=(no_handler_publishing_rule, no_workflow_in_reducer_rule),
+    ... )
+    >>>
+    >>> # Validate nodes and handlers
+    >>> request = ModelArchitectureValidationRequest(
+    ...     nodes=(my_orchestrator, my_reducer),
+    ...     handlers=(my_handler,),
+    ... )
+    >>> result = handler.handle(request)
+    >>> if result.valid:
+    ...     print("All architecture rules passed")
+
+.. versionadded:: 0.9.0
+    Created as part of OMN-1726 declarative refactoring.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ProtocolConfigurationError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+from omnibase_infra.nodes.architecture_validator.constants import SUPPORTED_RULE_IDS
+from omnibase_infra.nodes.architecture_validator.models import (
+    ModelArchitectureValidationRequest,
+    ModelArchitectureValidationResult,
+    ModelArchitectureViolation,
+    ModelRuleCheckResult,
+)
+
+if TYPE_CHECKING:
+    from omnibase_infra.nodes.architecture_validator.protocols import (
+        ProtocolArchitectureRule,
+    )
+
+HANDLER_ID_ARCHITECTURE_VALIDATION: str = "handler-architecture-validation"
+
+__all__ = ["HandlerArchitectureValidation", "HANDLER_ID_ARCHITECTURE_VALIDATION"]
+
+
+class HandlerArchitectureValidation:
+    """Handler for architecture validation operations.
+
+    Validates nodes and handlers against architecture rules. This handler
+    encapsulates all validation logic that was previously in the compute node.
+
+    Can be called:
+    - At startup (direct call, pre-runtime validation)
+    - During runtime (via orchestrator for dynamic validation)
+    - From CI/CD (standalone validation in test/build pipelines)
+
+    Attributes:
+        _rules: Tuple of architecture rules to enforce during validation.
+
+    Thread Safety:
+        This handler is thread-safe when:
+        - Rules are stateless (recommended)
+        - Request objects are not shared across threads
+        - Each handle() call operates independently
+
+    Example:
+        >>> # Create handler with rules
+        >>> handler = HandlerArchitectureValidation(rules=rules)
+        >>> result = handler.handle(request)
+        >>> if not result:
+        ...     from omnibase_infra.enums import EnumInfraTransportType
+        ...     from omnibase_infra.errors import (
+        ...         ModelInfraErrorContext,
+        ...         ProtocolConfigurationError,
+        ...     )
+        ...     context = ModelInfraErrorContext.with_correlation(
+        ...         transport_type=EnumInfraTransportType.RUNTIME,
+        ...         operation="architecture_validation",
+        ...     )
+        ...     raise ProtocolConfigurationError(
+        ...         f"Validation failed: {result.violation_count} violations",
+        ...         context=context,
+        ...         code="ARCHITECTURE_VALIDATION_FAILED",
+        ...         violations=[v.to_structured_dict() for v in result.violations],
+        ...     )
+
+    .. versionadded:: 0.9.0
+        Created as part of OMN-1726 declarative refactoring.
+    """
+
+    def __init__(
+        self,
+        rules: tuple[ProtocolArchitectureRule, ...] = (),
+    ) -> None:
+        """Initialize handler with architecture rules.
+
+        Args:
+            rules: Architecture rules to enforce. These should implement
+                ProtocolArchitectureRule. Rules from OMN-1099 validators can be
+                passed directly.
+
+        Raises:
+            ProtocolConfigurationError: If any rule has a rule_id not in
+                SUPPORTED_RULE_IDS. The error message includes the unsupported
+                rule_id and the list of supported rules for debugging.
+
+        Example:
+            >>> from my_rules import NoHandlerPublishingRule, NoWorkflowInReducerRule
+            >>>
+            >>> handler = HandlerArchitectureValidation(
+            ...     rules=(NoHandlerPublishingRule(), NoWorkflowInReducerRule()),
+            ... )
+
+        .. versionadded:: 0.9.0
+        """
+        self._validate_rules_against_contract(rules)
+        self._rules = rules
+
+    @property
+    def handler_id(self) -> str:
+        """Return unique identifier for this handler.
+
+        Returns:
+            str: Handler identifier.
+
+        .. versionadded:: 0.9.0
+        """
+        return HANDLER_ID_ARCHITECTURE_VALIDATION
+
+    @property
+    def supported_operations(self) -> frozenset[str]:
+        """Return supported operations for this handler.
+
+        Returns:
+            frozenset[str]: Set of supported operation names.
+
+        .. versionadded:: 0.9.0
+        """
+        return frozenset({"architecture.validate"})
+
+    def _validate_rules_against_contract(
+        self,
+        rules: tuple[ProtocolArchitectureRule, ...],
+    ) -> None:
+        """Validate that all provided rules are in the contract's supported_rules.
+
+        This validation ensures that only rules defined in the contract's
+        supported_rules list can be used with this handler. Using unsupported
+        rules would indicate a misconfiguration or version mismatch between
+        the handler and the rules being passed.
+
+        Args:
+            rules: Tuple of architecture rules to validate against the contract.
+
+        Raises:
+            ProtocolConfigurationError: If any rule has a rule_id not in
+                SUPPORTED_RULE_IDS. The error message includes the unsupported
+                rule_id and the list of supported rules for debugging.
+                Includes ModelInfraErrorContext with RUNTIME transport type.
+
+        .. versionadded:: 0.9.0
+        """
+        for rule in rules:
+            if rule.rule_id not in SUPPORTED_RULE_IDS:
+                context = ModelInfraErrorContext.with_correlation(
+                    transport_type=EnumInfraTransportType.RUNTIME,
+                    operation="validate_rules_against_contract",
+                )
+                raise ProtocolConfigurationError(
+                    f"Rule '{rule.rule_id}' is not in contract supported_rules. "
+                    f"Supported rules: {sorted(SUPPORTED_RULE_IDS)}",
+                    context=context,
+                    rule_id=rule.rule_id,
+                    supported_rules=sorted(SUPPORTED_RULE_IDS),
+                )
+
+    def validate_architecture(
+        self,
+        request: ModelArchitectureValidationRequest,
+    ) -> ModelArchitectureValidationResult:
+        """Validate architecture compliance.
+
+        Applies all registered rules to the nodes and handlers in the request.
+        Returns a result containing any violations found and summary statistics.
+
+        This is a pure transformation with no side effects:
+        - Same input always produces same output
+        - Does not modify request, rules, or external state
+        - Safe to call concurrently from multiple threads
+
+        Args:
+            request: Validation request containing:
+                - nodes: Nodes to validate
+                - handlers: Handlers to validate
+                - rule_ids: Optional filter for specific rules
+                - fail_fast: Whether to stop on first violation
+                - correlation_id: For distributed tracing
+
+        Returns:
+            ModelArchitectureValidationResult with:
+            - violations: All violations found (empty if validation passed)
+            - rules_checked: IDs of rules that were evaluated
+            - nodes_checked: Count of nodes validated
+            - handlers_checked: Count of handlers validated
+            - correlation_id: Propagated from request
+
+        Example:
+            >>> # Check all rules
+            >>> result = handler.handle(ModelArchitectureValidationRequest(
+            ...     nodes=all_nodes,
+            ...     handlers=all_handlers,
+            ... ))
+            >>> print(f"Checked {result.nodes_checked} nodes, "
+            ...       f"{result.handlers_checked} handlers")
+            >>> print(f"Found {result.violation_count} violations")
+
+            >>> # Check specific rules only
+            >>> result = handler.handle(ModelArchitectureValidationRequest(
+            ...     nodes=all_nodes,
+            ...     rule_ids=("NO_HANDLER_PUBLISHING", "PURE_REDUCERS"),
+            ...     fail_fast=True,
+            ... ))
+
+        .. versionadded:: 0.9.0
+        """
+        violations: list[ModelArchitectureViolation] = []
+        rules_to_check = self._get_rules_to_check(request.rule_ids)
+
+        # Validate nodes
+        for node in request.nodes:
+            for rule in rules_to_check:
+                result = rule.check(node)
+                if not result.passed:
+                    violation = self._create_violation(rule, node, result)
+                    violations.append(violation)
+                    if request.fail_fast:
+                        return self._build_result(violations, rules_to_check, request)
+
+        # Validate handlers
+        for handler in request.handlers:
+            for rule in rules_to_check:
+                result = rule.check(handler)
+                if not result.passed:
+                    violation = self._create_violation(rule, handler, result)
+                    violations.append(violation)
+                    if request.fail_fast:
+                        return self._build_result(violations, rules_to_check, request)
+
+        return self._build_result(violations, rules_to_check, request)
+
+    def _get_rules_to_check(
+        self,
+        rule_ids: tuple[str, ...] | None,
+    ) -> tuple[ProtocolArchitectureRule, ...]:
+        """Get rules to check based on request filter.
+
+        Args:
+            rule_ids: Optional tuple of rule IDs to filter by.
+                If None, all registered rules are returned.
+
+        Returns:
+            Tuple of rules to check. If rule_ids is provided, only
+            rules with matching IDs are included.
+
+        .. versionadded:: 0.9.0
+        """
+        if rule_ids is None:
+            return self._rules
+        return tuple(r for r in self._rules if r.rule_id in rule_ids)
+
+    def _create_violation(
+        self,
+        rule: ProtocolArchitectureRule,
+        target: object,
+        result: ModelRuleCheckResult,
+    ) -> ModelArchitectureViolation:
+        """Create violation from rule check result.
+
+        Args:
+            rule: The rule that was violated.
+            target: The node or handler that violated the rule.
+            result: The check result with violation details.
+
+        Returns:
+            ModelArchitectureViolation with full context for debugging
+            and remediation.
+
+        Note:
+            Uses getattr for target_name to handle both class types
+            (with __name__) and instances (fallback to str()).
+
+        .. versionadded:: 0.9.0
+        """
+        return ModelArchitectureViolation(
+            rule_id=rule.rule_id,
+            rule_name=rule.name,
+            severity=rule.severity,
+            target_type=type(target).__name__,
+            target_name=getattr(target, "__name__", str(target)),
+            message=result.message or rule.description,
+            details=result.details,
+        )
+
+    def _build_result(
+        self,
+        violations: list[ModelArchitectureViolation],
+        rules_checked: tuple[ProtocolArchitectureRule, ...],
+        request: ModelArchitectureValidationRequest,
+    ) -> ModelArchitectureValidationResult:
+        """Build final validation result.
+
+        Args:
+            violations: All violations found during validation.
+            rules_checked: Rules that were evaluated.
+            request: Original validation request (for counts and correlation_id).
+
+        Returns:
+            ModelArchitectureValidationResult with complete validation summary.
+
+        .. versionadded:: 0.9.0
+        """
+        return ModelArchitectureValidationResult(
+            violations=tuple(violations),
+            rules_checked=tuple(r.rule_id for r in rules_checked),
+            nodes_checked=len(request.nodes),
+            handlers_checked=len(request.handlers),
+            correlation_id=request.correlation_id,
+        )

omnibase_infra/nodes/architecture_validator/node.py

@@ -69,6 +69,7 @@ if TYPE_CHECKING:
 _ValidatorFunc = Callable[[str], ModelFileValidationResult]
 
 
+# ONEX_EXCLUDE: declarative_node - legacy validator with embedded validation logic (OMN-1725)
 class NodeArchitectureValidator(NodeCompute):
     """Architecture Validator - COMPUTE_GENERIC node for architecture pattern validation.