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

omnibase_infra/models/validation/model_declarative_node_violation.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Declarative Node Violation Model.
+
+Defines the result structure for detected declarative node violations.
+Used by the declarative node validator to report policy breaches with
+full context for debugging and CI gate integration.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumValidationSeverity
+from omnibase_infra.enums.enum_declarative_node_violation import (
+    EnumDeclarativeNodeViolation,
+)
+
+
+class ModelDeclarativeNodeViolation(BaseModel):
+    """Result of a declarative node violation detection.
+
+    Contains full context about a detected violation for debugging,
+    reporting, and CI gate integration. Each violation includes the
+    source location, violation type, and suggested fix.
+
+    Attributes:
+        file_path: Path to the source file containing the violation.
+        line_number: Line number where the violation was detected (1-indexed).
+        violation_type: The specific violation category detected.
+        code_snippet: The relevant code snippet showing the violation.
+        suggestion: Human-readable suggestion for fixing the violation.
+        severity: Severity classification (error blocks CI, warning is advisory).
+        node_class_name: Name of the node class containing the violation.
+        method_name: Name of the offending method/property if applicable.
+
+    Example:
+        >>> violation = ModelDeclarativeNodeViolation(
+        ...     file_path=Path("/src/nodes/my_node/node.py"),
+        ...     line_number=42,
+        ...     violation_type=EnumDeclarativeNodeViolation.CUSTOM_METHOD,
+        ...     code_snippet="def compute(self, data): ...",
+        ...     suggestion="Move business logic to a Handler class...",
+        ...     node_class_name="MyNode",
+        ...     method_name="compute",
+        ... )
+
+    Note:
+        Violations with severity='error' or 'critical' should block CI pipelines.
+        All declarative node violations are errors by default.
+    """
+
+    file_path: Path = Field(
+        ...,
+        description="Path to the source file containing the violation",
+    )
+    line_number: int = Field(
+        ...,
+        ge=1,
+        description="Line number where the violation was detected (1-indexed)",
+    )
+    violation_type: EnumDeclarativeNodeViolation = Field(
+        ...,
+        description="The specific declarative node violation category",
+    )
+    code_snippet: str = Field(
+        ...,
+        description="The relevant code snippet showing the violation",
+    )
+    suggestion: str = Field(
+        ...,
+        description="Human-readable suggestion for fixing the violation",
+    )
+    severity: EnumValidationSeverity = Field(
+        default=EnumValidationSeverity.ERROR,
+        description="Severity classification: 'error' blocks CI, 'warning' is advisory",
+    )
+    node_class_name: str = Field(
+        default="",
+        description="Name of the node class containing the violation",
+    )
+    method_name: str = Field(
+        default="",
+        description="Name of the offending method/property if applicable",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        str_strip_whitespace=True,
+        use_enum_values=False,
+    )
+
+    def is_blocking(self) -> bool:
+        """Check if this violation should block CI.
+
+        Returns:
+            True if severity is 'error' or 'critical', False for 'warning'.
+        """
+        return self.severity in {
+            EnumValidationSeverity.ERROR,
+            EnumValidationSeverity.CRITICAL,
+        }
+
+    @property
+    def is_exemptable(self) -> bool:
+        """Check if this violation can be exempted via ONEX_EXCLUDE comment.
+
+        Delegates to the violation type's is_exemptable property.
+        Some violations like SYNTAX_ERROR and NO_NODE_CLASS cannot be
+        exempted because they indicate fundamental issues with the source file.
+
+        Returns:
+            True if the violation can be exempted via inline comment.
+        """
+        return self.violation_type.is_exemptable
+
+    def format_for_ci(self) -> str:
+        """Format violation for CI output (GitHub Actions compatible).
+
+        Returns:
+            Formatted string in GitHub Actions annotation format.
+
+        Example:
+            ::error file=src/nodes/my_node/node.py,line=42::CUSTOM_METHOD: ...
+        """
+        annotation_type = "error" if self.is_blocking() else "warning"
+        context = f" in {self.node_class_name}" if self.node_class_name else ""
+        return (
+            f"::{annotation_type} file={self.file_path},line={self.line_number}::"
+            f"{self.violation_type.value}{context}: {self.code_snippet}"
+        )
+
+    def format_human_readable(self) -> str:
+        """Format violation for human-readable console output.
+
+        Includes exemption hint for exemptable violation types.
+
+        Returns:
+            Formatted string with file location and suggestion.
+
+        Example:
+            src/nodes/my_node/node.py:42 - CUSTOM_METHOD
+            Class: MyNode
+            Method: compute
+            Code: def compute(self, data): ...
+            Suggestion: Move business logic to a Handler class...
+            Exemption: Add '# ONEX_EXCLUDE: declarative_node' above the class
+        """
+        lines = [
+            f"{self.file_path}:{self.line_number} - {self.violation_type.value}",
+        ]
+        if self.node_class_name:
+            lines.append(f"  Class: {self.node_class_name}")
+        if self.method_name:
+            lines.append(f"  Method: {self.method_name}")
+        lines.append(f"  Code: {self.code_snippet}")
+        lines.append(f"  Suggestion: {self.suggestion}")
+        if self.is_exemptable:
+            lines.append(
+                "  Exemption: Add '# ONEX_EXCLUDE: declarative_node' above the class"
+            )
+        return "\n".join(lines)
+
+
+__all__ = ["ModelDeclarativeNodeViolation"]

omnibase_infra/nodes/architecture_validator/__init__.py

@@ -13,8 +13,12 @@ Available Validators:
         - ARCH-003: No Workflow FSM in Orchestrators
 
     NodeArchitectureValidatorCompute (OMN-1138):
-        Generic architecture validator supporting pluggable rules via
-        ProtocolArchitectureRule implementations.
+        Declarative compute node for architecture validation. Delegates all
+        validation logic to HandlerArchitectureValidation.
+
+    HandlerArchitectureValidation (OMN-1726):
+        Handler implementing validation logic for NodeArchitectureValidatorCompute.
+        Supports pluggable rules via ProtocolArchitectureRule implementations.
 
 Example:
     >>> from omnibase_core.models.container import ModelONEXContainer
@@ -22,13 +26,17 @@ Example:
     ...     NodeArchitectureValidatorCompute,
     ...     ModelArchitectureValidationRequest,
     ... )
+    >>> from omnibase_infra.nodes.architecture_validator.handlers import (
+    ...     HandlerArchitectureValidation,
+    ... )
     >>>
-    >>> # Create validator with rules
+    >>> # Create declarative node
     >>> container = ModelONEXContainer()
-    >>> validator = NodeArchitectureValidatorCompute(container, rules=my_rules)
+    >>> node = NodeArchitectureValidatorCompute(container)
     >>>
-    >>> # Validate architecture
-    >>> result = validator.compute(ModelArchitectureValidationRequest(
+    >>> # Use handler for validation
+    >>> handler = HandlerArchitectureValidation(rules=my_rules)
+    >>> result = handler.handle(ModelArchitectureValidationRequest(
     ...     nodes=my_nodes,
     ...     handlers=my_handlers,
     ... ))
@@ -38,11 +46,23 @@ Example:
 .. versionadded:: 0.8.0
     Added NodeArchitectureValidatorCompute as part of OMN-1138.
     Added NodeArchitectureValidator as part of OMN-1099.
+
+.. versionchanged:: 0.9.0
+    Refactored to declarative pattern as part of OMN-1726. Validation logic
+    moved to HandlerArchitectureValidation.
 """
 
 # Canonical severity enum
 from omnibase_infra.enums import EnumValidationSeverity
 
+# Constants
+from omnibase_infra.nodes.architecture_validator.constants import SUPPORTED_RULE_IDS
+
+# Handlers
+from omnibase_infra.nodes.architecture_validator.handlers import (
+    HandlerArchitectureValidation,
+)
+
 # Models
 from omnibase_infra.nodes.architecture_validator.models import (
     ModelArchitectureValidationRequest,
@@ -52,7 +72,6 @@ from omnibase_infra.nodes.architecture_validator.models import (
 )
 from omnibase_infra.nodes.architecture_validator.node import NodeArchitectureValidator
 from omnibase_infra.nodes.architecture_validator.node_architecture_validator import (
-    SUPPORTED_RULE_IDS,
     NodeArchitectureValidatorCompute,
 )
 from omnibase_infra.nodes.architecture_validator.protocols import (
@@ -63,6 +82,8 @@ from omnibase_infra.nodes.architecture_validator.registry import (
 )
 
 __all__ = [
+    # OMN-1726: HandlerArchitectureValidation
+    "HandlerArchitectureValidation",
     # OMN-1138: NodeArchitectureValidatorCompute
     "NodeArchitectureValidatorCompute",
     "SUPPORTED_RULE_IDS",

omnibase_infra/nodes/architecture_validator/constants.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Constants for the architecture validator node.
+
+This module defines constants used by the architecture validator node and its
+handlers. These constants are extracted from the node to enable handler-based
+architecture while keeping the supported rules defined in one place.
+
+Related:
+    - OMN-1138: Architecture Validator for omnibase_infra
+    - OMN-1726: Refactor to declarative pattern
+
+.. versionadded:: 0.8.0
+    Created as part of OMN-1138 Architecture Validator implementation.
+
+.. versionchanged:: 0.9.0
+    Extracted to separate module as part of OMN-1726 declarative refactoring.
+"""
+
+from __future__ import annotations
+
+# Supported rule IDs from contract_architecture_validator.yaml
+# These are the only rules that this validator node is designed to handle.
+# Any rule not in this set indicates a misconfiguration or version mismatch.
+SUPPORTED_RULE_IDS: frozenset[str] = frozenset(
+    {
+        "NO_HANDLER_PUBLISHING",
+        "PURE_REDUCERS",
+        "NO_FSM_IN_ORCHESTRATORS",
+        "NO_WORKFLOW_IN_REDUCERS",
+        "NO_DIRECT_HANDLER_DISPATCH",
+        "NO_LOCAL_ONLY_PATHS",
+    }
+)
+
+__all__ = ["SUPPORTED_RULE_IDS"]

omnibase_infra/nodes/architecture_validator/handlers/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handlers for NodeArchitectureValidatorCompute.
+
+This module exports the architecture validation handler that implements
+the validation logic for the declarative compute node.
+
+Handler Architecture:
+    - Handlers are stateless classes (no mutable state between calls)
+    - Handlers receive all context via the request model
+    - Handlers return structured result models
+    - Time-based decisions use explicit timestamp injection
+
+Related Tickets:
+    - OMN-1138: Architecture Validator for omnibase_infra
+    - OMN-1726: Refactor to declarative pattern with contract-driven handler
+
+.. versionadded:: 0.9.0
+    Created as part of OMN-1726 declarative refactoring.
+"""
+
+from omnibase_infra.nodes.architecture_validator.handlers.handler_architecture_validation import (
+    HandlerArchitectureValidation,
+)
+
+__all__: list[str] = [
+    "HandlerArchitectureValidation",
+]

omnibase_infra/nodes/architecture_validator/handlers/contract.yaml

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Handler Contract - Architecture Validation Handler
+#
+# This contract defines the interface for the Architecture Validation handler,
+# which validates ONEX nodes and handlers against architecture rules.
+#
+# =============================================================================
+# HANDLER OVERVIEW
+# =============================================================================
+# This handler processes architecture validation requests and returns structured
+# validation results. It encapsulates the validation logic that was previously
+# in NodeArchitectureValidatorCompute.
+#
+# Supported Operations:
+#   - architecture.validate: Validate nodes and handlers against rules
+#
+# =============================================================================
+# Handler identifier
+name: "handler_architecture_validation"
+handler_id: "handler-architecture-validation"
+# Version (semantic versioning)
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+# Node type context - this handler is used by COMPUTE_GENERIC nodes
+node_type: "COMPUTE_GENERIC"
+# Description
+description: >
+  Handler for architecture validation operations. Validates ONEX nodes and handlers against configurable architecture rules. Supports pluggable rules via the ProtocolArchitectureRule protocol. Returns structured validation results with violations grouped by rule and severity.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelArchitectureValidationRequest"
+  module: "omnibase_infra.nodes.architecture_validator.models"
+  description: >
+    Request containing nodes and handlers to validate, optional rule filters, and validation configuration (fail_fast, correlation_id).
+
+output_model:
+  name: "ModelArchitectureValidationResult"
+  module: "omnibase_infra.nodes.architecture_validator.models"
+  description: >
+    Result containing validation status, violations found, rules checked, and counts of nodes/handlers validated.
+
+# Handler routing configuration
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    - handler_type: "architecture_validation"
+      handler:
+        name: "HandlerArchitectureValidation"
+        module: "omnibase_infra.nodes.architecture_validator.handlers.handler_architecture_validation"
+      supported_operations:
+        - "architecture.validate"
+# Supported rules (from contract_architecture_validator.yaml)
+# These are the only rules that this handler is designed to process.
+supported_rules:
+  - rule_id: "NO_HANDLER_PUBLISHING"
+    description: >
+      Handlers MUST NOT have direct event bus access. Only orchestrators may publish events. Handlers return events; orchestrators publish.
+
+  - rule_id: "PURE_REDUCERS"
+    description: >
+      Reducers MUST be pure functions without side effects. They aggregate state and emit intents, but do not perform I/O operations.
+
+  - rule_id: "NO_FSM_IN_ORCHESTRATORS"
+    description: >
+      Orchestrators MUST NOT contain FSM (Finite State Machine) definitions. FSMs belong exclusively to reducer nodes.
+
+  - rule_id: "NO_WORKFLOW_IN_REDUCERS"
+    description: >
+      Reducers MUST NOT contain workflow logic. Workflow coordination belongs exclusively to orchestrator nodes.
+
+  - rule_id: "NO_DIRECT_HANDLER_DISPATCH"
+    description: >
+      Handlers MUST NOT be invoked directly bypassing the RuntimeHost. All event routing MUST go through the MessageDispatchEngine.
+
+  - rule_id: "NO_LOCAL_ONLY_PATHS"
+    description: >
+      Paths MUST NOT use local-only conventions that break portability. All paths should be relative or use environment variables.
+
+# Handler descriptor
+descriptor:
+  node_archetype: compute
+  purity: pure
+  idempotent: true
+  timeout_ms: 30000
+  retry_policy:
+    enabled: false
+  circuit_breaker:
+    enabled: false
+  concurrency_policy: concurrent
+  isolation_policy: none
+  observability_level: standard
+# Capabilities provided by this handler
+capabilities:
+  - name: "architecture_validation"
+    description: "Validate architecture patterns across nodes and handlers"
+  - name: "rule_based_validation"
+    description: "Extensible rule-based validation engine"
+  - name: "violation_reporting"
+    description: "Structured violation reporting with severity levels"
+# Tags
+tags:
+  - compute
+  - validation
+  - architecture
+  - handler
+  - onex-compliance
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2025-01-30"
+  ticket: "OMN-1726"
+  related_tickets:
+    - "OMN-1138"
+    - "OMN-1099"