omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/architecture_validator/protocols/protocol_architecture_rule.py

@@ -0,0 +1,225 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol for architecture validation rules.
+
+This module defines the ProtocolArchitectureRule protocol that all architecture
+validation rules must implement. Rules check nodes, handlers, and other
+architectural components for compliance with ONEX patterns and constraints.
+
+Thread Safety:
+    Rule implementations may be invoked concurrently from the validation engine.
+    Rules should be stateless or use appropriate synchronization.
+
+Related:
+    - OMN-1138: Architecture Validator for omnibase_infra
+    - OMN-1099: Implement validators against this protocol
+
+Example:
+    >>> from omnibase_infra.nodes.architecture_validator.protocols import (
+    ...     ProtocolArchitectureRule,
+    ... )
+    >>> from omnibase_infra.enums import EnumValidationSeverity
+    >>> from omnibase_infra.nodes.architecture_validator.models import (
+    ...     ModelRuleCheckResult,
+    ... )
+    >>>
+    >>> class NoHandlerPublishingRule:
+    ...     '''Rule that validates handlers do not have direct event bus access.'''
+    ...
+    ...     @property
+    ...     def rule_id(self) -> str:
+    ...         return "NO_HANDLER_PUBLISHING"
+    ...
+    ...     @property
+    ...     def name(self) -> str:
+    ...         return "No Handler Publishing"
+    ...
+    ...     @property
+    ...     def description(self) -> str:
+    ...         return "Handlers must not have direct event bus access."
+    ...
+    ...     @property
+    ...     def severity(self) -> EnumValidationSeverity:
+    ...         return EnumValidationSeverity.ERROR
+    ...
+    ...     def check(self, target: object) -> ModelRuleCheckResult:
+    ...         # Implementation validates the target
+    ...         return ModelRuleCheckResult(passed=True, rule_id=self.rule_id)
+    >>>
+    >>> # Verify protocol compliance via duck typing
+    >>> rule = NoHandlerPublishingRule()
+    >>> assert hasattr(rule, 'rule_id')
+    >>> assert hasattr(rule, 'check') and callable(rule.check)
+
+See Also:
+    omnibase_infra.nodes.architecture_validator.models.ModelRuleCheckResult:
+        Result model returned by check method
+    omnibase_infra.enums.EnumValidationSeverity:
+        Severity levels for rule violations
+
+.. versionadded:: 0.6.0
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from omnibase_infra.enums import EnumValidationSeverity
+    from omnibase_infra.nodes.architecture_validator.models import ModelRuleCheckResult
+
+__all__ = ["ProtocolArchitectureRule"]
+
+
+@runtime_checkable
+class ProtocolArchitectureRule(Protocol):
+    """Contract for architecture validation rules.
+
+    Validators implementing this protocol check nodes, handlers, and other
+    architectural components for violations of ONEX patterns and constraints.
+
+    Common rule categories:
+    - **Handler Isolation**: Handlers must not have direct event bus access
+    - **Node Archetype Compliance**: Nodes must follow their archetype constraints
+    - **Workflow Logic Location**: Workflow logic must be in orchestrators only
+    - **State Management**: Reducers must be the only source of state changes
+
+    Protocol Verification:
+        Per ONEX conventions, protocol compliance is verified via duck typing
+        rather than isinstance checks. Verify required properties and methods:
+
+        .. code-block:: python
+
+            # Verify required properties and methods exist
+            if (hasattr(rule, 'rule_id') and
+                hasattr(rule, 'name') and
+                hasattr(rule, 'severity') and
+                hasattr(rule, 'check') and callable(rule.check)):
+                validator.register_rule(rule)
+            else:
+                raise TypeError("Object does not implement ProtocolArchitectureRule")
+
+    Attributes:
+        rule_id: Unique identifier for this rule (e.g., 'NO_HANDLER_PUBLISHING').
+        name: Human-readable name for the rule.
+        description: Detailed description of what this rule checks.
+        severity: Severity level if this rule is violated.
+
+    Note:
+        Method bodies in this Protocol use ``...`` (Ellipsis) rather than
+        ``raise NotImplementedError()``. This is the standard Python convention
+        for ``typing.Protocol`` classes per PEP 544.
+
+    .. versionadded:: 0.6.0
+    """
+
+    @property
+    def rule_id(self) -> str:
+        """Return the unique identifier for this rule.
+
+        The rule ID is used for:
+        - Registration and lookup in the validator
+        - Filtering and selection of rules to run
+        - Error reporting and result aggregation
+        - Configuration of rule-specific settings
+
+        Convention: Use SCREAMING_SNAKE_CASE for rule IDs.
+
+        Returns:
+            str: Unique rule identifier (e.g., "NO_HANDLER_PUBLISHING")
+
+        Example:
+            >>> rule.rule_id
+            'NO_HANDLER_PUBLISHING'
+        """
+        ...
+
+    @property
+    def name(self) -> str:
+        """Return the human-readable name for this rule.
+
+        The name is used for:
+        - Display in validation reports
+        - User-facing documentation
+        - Log messages
+
+        Convention: Use Title Case for rule names.
+
+        Returns:
+            str: Human-readable rule name (e.g., "No Handler Publishing")
+
+        Example:
+            >>> rule.name
+            'No Handler Publishing'
+        """
+        ...
+
+    @property
+    def description(self) -> str:
+        """Return a detailed description of what this rule checks.
+
+        The description should explain:
+        - What architectural constraint is being validated
+        - Why the constraint exists
+        - What constitutes a violation
+
+        Returns:
+            str: Detailed description of the rule
+
+        Example:
+            >>> rule.description
+            'Handlers must not have direct event bus access. Only orchestrators may publish events.'
+        """
+        ...
+
+    @property
+    def severity(self) -> EnumValidationSeverity:
+        """Return the severity level for violations of this rule.
+
+        The severity determines how violations are handled:
+        - ERROR: Fail validation, block runtime startup
+        - WARNING: Log warning, allow startup
+        - INFO: Informational only
+
+        Returns:
+            EnumValidationSeverity: The severity level for this rule
+
+        Example:
+            >>> rule.severity
+            <EnumValidationSeverity.ERROR: 'error'>
+            >>> rule.severity.blocks_startup()
+            True
+        """
+        ...
+
+    def check(self, target: object) -> ModelRuleCheckResult:
+        """Check the target against this rule.
+
+        Validates that the target (node, handler, or other architectural
+        component) complies with the constraint defined by this rule.
+
+        Typing Note:
+            The target parameter uses ``object`` instead of ``Any`` to
+            satisfy ONEX "no Any types" guideline. Implementations should
+            validate the target type internally.
+
+        Args:
+            target: The node, handler, or other object to validate.
+                   Implementations should validate the target type and
+                   return a passing result if the target type is not
+                   applicable to this rule.
+
+        Returns:
+            ModelRuleCheckResult with:
+            - passed=True if the target complies with the rule
+            - passed=False if a violation is detected
+            - message describing the result (especially for violations)
+            - details with additional debugging information
+
+        Example:
+            >>> result = rule.check(my_handler)
+            >>> if result.is_violation():
+            ...     print(f"Violation: {result.message}")
+            ...     print(f"Details: {result.details}")
+        """
+        ...

omnibase_infra/nodes/architecture_validator/registry/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for Architecture Validator node.
+
+This module contains the infrastructure registry for the
+Architecture Validator node, following the naming convention:
+    RegistryInfraArchitectureValidator
+
+Usage:
+    ```python
+    from omnibase_core.models.container import ModelONEXContainer
+    from omnibase_infra.nodes.architecture_validator.registry import (
+        RegistryInfraArchitectureValidator,
+    )
+
+    container = ModelONEXContainer()
+    RegistryInfraArchitectureValidator.register(container)
+    ```
+
+Related:
+    - Ticket: OMN-1099 (Architecture Validator)
+"""
+
+from omnibase_infra.nodes.architecture_validator.registry.registry_infra_architecture_validator import (
+    RegistryInfraArchitectureValidator,
+)
+
+__all__: list[str] = ["RegistryInfraArchitectureValidator"]

omnibase_infra/nodes/architecture_validator/registry/registry_infra_architecture_validator.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry for NodeArchitectureValidator.
+
+Provides dependency injection registration for the architecture validator node.
+This registry follows the ONEX pattern of container-managed service registration.
+
+Usage:
+    ```python
+    from omnibase_core.models.container import ModelONEXContainer
+    from omnibase_infra.nodes.architecture_validator.registry import (
+        RegistryInfraArchitectureValidator,
+    )
+
+    container = ModelONEXContainer()
+    RegistryInfraArchitectureValidator.register(container)
+
+    # Later, resolve the validator
+    validator = container.get_service(NodeArchitectureValidator)
+    ```
+
+Related:
+    - Ticket: OMN-1099 (Architecture Validator)
+    - NodeArchitectureValidator: The COMPUTE node this registry registers
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+
+from omnibase_infra.nodes.architecture_validator.node import NodeArchitectureValidator
+
+
+class RegistryInfraArchitectureValidator:
+    """Registry for architecture validator components.
+
+    This registry provides a static method to register the NodeArchitectureValidator
+    with the ONEX dependency injection container. The validator is registered as
+    a factory, allowing lazy instantiation when first resolved.
+
+    Thread Safety:
+        Registration is typically done at startup before the container is frozen.
+        After registration, the container provides thread-safe resolution.
+
+    Example:
+        ```python
+        from omnibase_core.models.container import ModelONEXContainer
+        from omnibase_infra.nodes.architecture_validator.registry import (
+            RegistryInfraArchitectureValidator,
+        )
+
+        container = ModelONEXContainer()
+        RegistryInfraArchitectureValidator.register(container)
+        ```
+    """
+
+    @staticmethod
+    def register(container: ModelONEXContainer) -> None:
+        """Register architecture validator with container.
+
+        Registers the NodeArchitectureValidator as a service in the ONEX
+        dependency injection container. The validator is registered with
+        a factory function that creates a new instance on demand.
+
+        Args:
+            container: The DI container to register with.
+
+        Note:
+            If the container's service_registry is not available (e.g., in
+            minimal container configurations), this method will log a warning
+            but not raise an exception. This allows for graceful degradation
+            in environments where full DI is not configured.
+
+        Example:
+            ```python
+            container = ModelONEXContainer()
+            RegistryInfraArchitectureValidator.register(container)
+
+            # Resolve when needed
+            validator = container.get_service(NodeArchitectureValidator)
+            result = await validator.compute(request)
+            ```
+        """
+        # Check if service_registry is available
+        if container.service_registry is None:
+            # Container doesn't have full DI support - skip registration
+            # This allows the code to work with minimal container configurations
+            return
+
+        container.service_registry.register(
+            NodeArchitectureValidator,
+            lambda c: NodeArchitectureValidator(c),
+        )
+
+
+__all__ = ["RegistryInfraArchitectureValidator"]

omnibase_infra/nodes/architecture_validator/validators/__init__.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validators for Architecture Validator node.
+
+This module provides validator implementations for ONEX architecture rules.
+Each validator enforces a specific architectural constraint to ensure proper
+separation of concerns in the ONEX 4-node architecture.
+
+Related:
+    - Ticket: OMN-1099 (Architecture Validator - Protocol Compliance)
+    - PR: #124 (Protocol-Compliant Rule Classes)
+
+Architecture Rules:
+    - ARCH-001: No Direct Handler Dispatch
+        Handlers must be dispatched through the runtime, not called directly.
+        Direct calls bypass event tracking, circuit breaking, and other
+        cross-cutting concerns.
+
+    - ARCH-002: No Handler Publishing Events
+        Handlers must not have direct event bus access. Only orchestrators
+        may publish events. Handlers should return events for orchestrators
+        to publish.
+
+    - ARCH-003: No Workflow FSM in Orchestrators
+        Orchestrators must not implement workflow FSMs (finite state machines).
+        Reducers own state machines; orchestrators are "reaction planners"
+        that coordinate work based on reducer outputs.
+
+Two Interfaces:
+    **1. Function-based validators** - Direct file validation, returns detailed results.
+
+        Suitable for: Scripts, CLI tools, direct validation of single files.
+
+        Example::
+
+            from omnibase_infra.nodes.architecture_validator.validators import (
+                validate_no_direct_dispatch,
+            )
+
+            result = validate_no_direct_dispatch("/path/to/handler.py")
+            if not result.valid:
+                for violation in result.violations:
+                    print(f"{violation.location}: {violation.message}")
+
+    **2. Protocol-compliant rule classes** - Implement `ProtocolArchitectureRule`.
+
+        Suitable for: Integration with NodeArchitectureValidatorCompute, batch
+        validation, registry-based rule management.
+
+        Example::
+
+            from omnibase_infra.nodes.architecture_validator.validators import (
+                RuleNoDirectDispatch,
+                RuleNoHandlerPublishing,
+                RuleNoOrchestratorFSM,
+            )
+
+            rules = [
+                RuleNoDirectDispatch(),
+                RuleNoHandlerPublishing(),
+                RuleNoOrchestratorFSM(),
+            ]
+
+            for rule in rules:
+                result = rule.check("/path/to/file.py")
+                if not result.passed:
+                    print(f"{rule.rule_id}: {result.message}")
+
+Thread Safety:
+    All rule classes are stateless and safe for concurrent use across threads.
+    Function-based validators are also thread-safe as they create new AST
+    visitor instances for each invocation.
+
+Configuration:
+    Validators are wired through contract.yaml using the detection_strategy
+    patterns. See the architecture validator node contract for configuration
+    options and severity mappings.
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.nodes.architecture_validator.validators.validator_no_direct_dispatch import (
+    RuleNoDirectDispatch,
+    validate_no_direct_dispatch,
+)
+from omnibase_infra.nodes.architecture_validator.validators.validator_no_handler_publishing import (
+    RuleNoHandlerPublishing,
+    validate_no_handler_publishing,
+)
+from omnibase_infra.nodes.architecture_validator.validators.validator_no_orchestrator_fsm import (
+    RuleNoOrchestratorFSM,
+    validate_no_orchestrator_fsm,
+)
+
+__all__: list[str] = [
+    # Functions (file-based validators)
+    "validate_no_direct_dispatch",
+    "validate_no_handler_publishing",
+    "validate_no_orchestrator_fsm",
+    # Classes (protocol-compliant rules)
+    "RuleNoDirectDispatch",
+    "RuleNoHandlerPublishing",
+    "RuleNoOrchestratorFSM",
+]