omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/architecture_validator/models/model_architecture_validation_result.py

@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Architecture validation result model.
+
+This module defines the output model for NodeArchitectureValidatorCompute,
+containing all validation results including violations found and summary statistics.
+
+Design Pattern:
+    ModelArchitectureValidationResult serves as the complete output from architecture
+    validation operations. It aggregates all violations found during validation and
+    provides computed properties for quick status checks.
+
+    The model uses immutable tuple fields to ensure thread safety and prevent
+    accidental modification of validation results after creation.
+
+Thread Safety:
+    ModelArchitectureValidationResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access. All collection fields use
+    immutable tuple types.
+
+Example:
+    >>> from omnibase_infra.nodes.architecture_validator.models import (
+    ...     ModelArchitectureValidationResult,
+    ... )
+    >>>
+    >>> # Create a passing result
+    >>> result = ModelArchitectureValidationResult(
+    ...     rules_checked=("ARCH-001", "ARCH-002"),
+    ...     nodes_checked=5,
+    ...     handlers_checked=10,
+    ... )
+    >>> result.valid
+    True
+    >>> bool(result)  # Uses custom __bool__
+    True
+    >>>
+    >>> # Create a result with violations
+    >>> result_with_violations = ModelArchitectureValidationResult(
+    ...     violations=(violation1, violation2),
+    ...     rules_checked=("ARCH-001",),
+    ...     nodes_checked=5,
+    ... )
+    >>> result_with_violations.valid
+    False
+    >>> result_with_violations.violation_count
+    2
+
+.. versionadded:: 0.8.0
+    Created as part of OMN-1138 Architecture Validator implementation.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.nodes.architecture_validator.models.model_architecture_violation import (
+    ModelArchitectureViolation,
+)
+
+
+class ModelArchitectureValidationResult(BaseModel):
+    """Result of architecture validation.
+
+    Contains all violations found during validation and summary statistics
+    about what was checked. Used as the output from NodeArchitectureValidatorCompute.
+
+    Attributes:
+        violations: All violations found during validation. Empty tuple if
+            validation passed.
+        rules_checked: Rule IDs that were evaluated during validation.
+        nodes_checked: Number of nodes that were validated.
+        handlers_checked: Number of handlers that were validated.
+        correlation_id: Optional correlation ID for distributed tracing.
+
+    Warning:
+        **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to return
+        ``True`` only when validation passed (i.e., no violations found). This
+        differs from typical Pydantic model behavior where ``bool(model)`` always
+        returns ``True`` for any valid model instance.
+
+        This design enables idiomatic conditional checks for validation status::
+
+            if result:
+                # Validation passed - proceed with deployment
+                deploy_nodes()
+            else:
+                # Validation failed - handle violations
+                report_violations(result.violations)
+
+        If you need to check model validity instead, use explicit attribute access::
+
+            # Check for validation success (uses __bool__)
+            if result:
+                ...
+
+            # Check model is valid (always True for constructed instance)
+            if result is not None:
+                ...
+
+            # Explicit validation check (preferred for clarity)
+            if result.valid:
+                ...
+
+    Example:
+        >>> # Create a clean validation result
+        >>> result = ModelArchitectureValidationResult(
+        ...     rules_checked=("ARCH-001", "ARCH-002", "ARCH-003"),
+        ...     nodes_checked=10,
+        ...     handlers_checked=25,
+        ... )
+        >>> result.valid
+        True
+        >>> result.violation_count
+        0
+
+        >>> # Create result with violations
+        >>> result = ModelArchitectureValidationResult(
+        ...     violations=(violation,),
+        ...     rules_checked=("ARCH-001",),
+        ...     nodes_checked=5,
+        ... )
+        >>> result.valid
+        False
+
+    .. versionadded:: 0.8.0
+        Created as part of OMN-1138 Architecture Validator implementation.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    violations: tuple[ModelArchitectureViolation, ...] = Field(
+        default_factory=tuple,
+        description="All violations found during validation. Empty if validation passed.",
+    )
+
+    rules_checked: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Rule IDs that were checked during validation (e.g., 'ARCH-001').",
+    )
+
+    nodes_checked: int = Field(
+        default=0,
+        ge=0,
+        description="Number of nodes that were validated.",
+    )
+
+    handlers_checked: int = Field(
+        default=0,
+        ge=0,
+        description="Number of handlers that were validated.",
+    )
+
+    correlation_id: str | None = Field(
+        default=None,
+        description="Correlation ID for distributed tracing.",
+    )
+
+    @property
+    def valid(self) -> bool:
+        """Whether validation passed (no violations found).
+
+        Returns:
+            True if no violations were found, False otherwise.
+
+        Example:
+            >>> result = ModelArchitectureValidationResult(violations=())
+            >>> result.valid
+            True
+
+        .. versionadded:: 0.8.0
+        """
+        return len(self.violations) == 0
+
+    @property
+    def violation_count(self) -> int:
+        """Total number of violations found.
+
+        Returns:
+            Number of violations in the violations tuple.
+
+        Example:
+            >>> result = ModelArchitectureValidationResult(
+            ...     violations=(v1, v2, v3),
+            ... )
+            >>> result.violation_count
+            3
+
+        .. versionadded:: 0.8.0
+        """
+        return len(self.violations)
+
+    @property
+    def rules_checked_count(self) -> int:
+        """Total number of rules that were evaluated.
+
+        Returns:
+            Number of rules in the rules_checked tuple.
+
+        .. versionadded:: 0.8.0
+        """
+        return len(self.rules_checked)
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context to check validation status.
+
+        Returns True if validation passed (no violations), enabling idiomatic
+        conditional checks for validation success.
+
+        Warning:
+            This differs from typical Pydantic model behavior where ``bool(model)``
+            always returns ``True`` for any valid model instance. Here, ``bool(result)``
+            returns ``False`` for valid results that contain violations.
+
+            Use ``result.valid`` for explicit, self-documenting code.
+            Use ``result is not None`` if you need to check model existence.
+
+        Returns:
+            True if no violations found (validation passed), False otherwise.
+
+        Example:
+            >>> # Passing validation
+            >>> result_pass = ModelArchitectureValidationResult(
+            ...     rules_checked=("ARCH-001",),
+            ...     nodes_checked=5,
+            ... )
+            >>> bool(result_pass)
+            True
+
+            >>> # Failing validation
+            >>> result_fail = ModelArchitectureValidationResult(
+            ...     violations=(some_violation,),
+            ...     rules_checked=("ARCH-001",),
+            ... )
+            >>> bool(result_fail)  # False even though model is valid!
+            False
+
+            >>> # Idiomatic usage
+            >>> if result_pass:
+            ...     print("Validation passed")
+            ... else:
+            ...     print("Validation failed")
+            Validation passed
+
+        .. versionadded:: 0.8.0
+        """
+        return self.valid
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String showing validation status and summary counts.
+
+        .. versionadded:: 0.8.0
+        """
+        status = "PASSED" if self.valid else "FAILED"
+        return (
+            f"ModelArchitectureValidationResult("
+            f"status={status}, "
+            f"violations={self.violation_count}, "
+            f"rules={self.rules_checked_count}, "
+            f"nodes={self.nodes_checked}, "
+            f"handlers={self.handlers_checked})"
+        )
+
+    @classmethod
+    def passed(
+        cls,
+        *,
+        rules_checked: tuple[str, ...] = (),
+        nodes_checked: int = 0,
+        handlers_checked: int = 0,
+        correlation_id: str | None = None,
+    ) -> ModelArchitectureValidationResult:
+        """Create a passing validation result with no violations.
+
+        Factory method for creating clean validation results.
+
+        Args:
+            rules_checked: Rule IDs that were evaluated.
+            nodes_checked: Number of nodes validated.
+            handlers_checked: Number of handlers validated.
+            correlation_id: Optional correlation ID for tracing.
+
+        Returns:
+            ModelArchitectureValidationResult with no violations.
+
+        Example:
+            >>> result = ModelArchitectureValidationResult.passed(
+            ...     rules_checked=("ARCH-001", "ARCH-002"),
+            ...     nodes_checked=10,
+            ... )
+            >>> result.valid
+            True
+
+        .. versionadded:: 0.8.0
+        """
+        return cls(
+            violations=(),
+            rules_checked=rules_checked,
+            nodes_checked=nodes_checked,
+            handlers_checked=handlers_checked,
+            correlation_id=correlation_id,
+        )
+
+
+__all__ = ["ModelArchitectureValidationResult"]

omnibase_infra/nodes/architecture_validator/models/model_architecture_violation.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Architecture Violation Model.
+
+Defines the structure for a single architecture rule violation detected
+during validation. Used by the architecture validator to report violations
+with full context for debugging and remediation.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumValidationSeverity
+
+
+class ModelArchitectureViolation(BaseModel):
+    """A single architecture rule violation.
+
+    Captures details about what rule was violated, where, and why. Each
+    violation includes the rule context, target information, and optional
+    remediation guidance.
+
+    Architecture violations are detected during validation phases and can
+    range from informational notices to blocking errors that prevent
+    startup.
+
+    Attributes:
+        rule_id: Unique identifier for the rule that was violated.
+        rule_name: Human-readable name of the violated rule.
+        severity: Severity level determining how the violation is handled.
+        target_type: Type of target that violated the rule (e.g., 'handler',
+            'node', 'model').
+        target_name: Name or identifier of the violating target.
+        message: Human-readable description of the violation.
+        location: File path and line number if available.
+        suggestion: Suggested fix or remediation for this violation.
+        details: Additional context-specific details for debugging.
+
+    Example:
+        >>> violation = ModelArchitectureViolation(
+        ...     rule_id="no-any-types",
+        ...     rule_name="No Any Types",
+        ...     severity=EnumValidationSeverity.ERROR,
+        ...     target_type="model",
+        ...     target_name="ModelUserData",
+        ...     message="Field 'payload' uses 'Any' type which is forbidden",
+        ...     location="src/models/model_user_data.py:42",
+        ...     suggestion="Use 'object' or a specific type instead of 'Any'",
+        ... )
+        >>> violation.blocks_startup()
+        True
+    """
+
+    rule_id: str = Field(
+        ...,
+        min_length=1,
+        description="Unique identifier of the rule that was violated",
+    )
+    rule_name: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable name of the violated rule",
+    )
+    severity: EnumValidationSeverity = Field(
+        ...,
+        description="Severity level determining how this violation is handled",
+    )
+    target_type: str = Field(
+        ...,
+        min_length=1,
+        description="Type of target that violated the rule (e.g., 'handler', 'node', 'model')",
+    )
+    target_name: str = Field(
+        ...,
+        min_length=1,
+        description="Name or identifier of the violating target",
+    )
+    message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable description of the violation",
+    )
+    location: str | None = Field(
+        default=None,
+        description="File path and line number if available (e.g., 'src/foo.py:42')",
+    )
+    suggestion: str | None = Field(
+        default=None,
+        description="Suggested fix or remediation for this violation",
+    )
+    details: dict[str, object] | None = Field(
+        default=None,
+        description="Additional context-specific details for debugging",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
+        use_enum_values=False,  # Keep enum objects for type safety
+    )
+
+    def blocks_startup(self) -> bool:
+        """Check if this violation should block runtime startup.
+
+        Returns:
+            True if severity is ERROR or CRITICAL, False otherwise.
+
+        Example:
+            >>> violation.blocks_startup()
+            True
+        """
+        return self.severity.blocks_startup()
+
+    def format_for_logging(self) -> str:
+        """Format violation for structured logging output.
+
+        Returns:
+            Formatted string suitable for structured logging systems.
+            Includes all relevant context for debugging violations.
+
+        Example:
+            >>> violation.format_for_logging()
+            '[ERROR] no-any-types (No Any Types) on model/ModelUserData: ...'
+        """
+        location_str = f" at {self.location}" if self.location else ""
+        suggestion_str = f" - Suggestion: {self.suggestion}" if self.suggestion else ""
+
+        return (
+            f"[{self.severity.value.upper()}] {self.rule_id} ({self.rule_name}) "
+            f"on {self.target_type}/{self.target_name}{location_str}: "
+            f"{self.message}{suggestion_str}"
+        )
+
+    def to_structured_dict(self) -> dict[str, str | None]:
+        """Convert violation to a dictionary suitable for structured logging.
+
+        Returns:
+            Dictionary with all violation fields as strings, suitable for
+            JSON logging or metrics systems.
+
+        Note:
+            The ``details`` field is intentionally excluded from this output
+            because it may contain complex objects that are not JSON-serializable.
+            For full violation details, access the ``details`` attribute directly.
+
+        Example:
+            >>> violation.to_structured_dict()
+            {'rule_id': 'no-any-types', 'severity': 'error', ...}
+        """
+        return {
+            "rule_id": self.rule_id,
+            "rule_name": self.rule_name,
+            "severity": self.severity.value,
+            "target_type": self.target_type,
+            "target_name": self.target_name,
+            "message": self.message,
+            "location": self.location,
+            "suggestion": self.suggestion,
+        }
+
+
+__all__ = ["ModelArchitectureViolation"]