omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/validation/__init__.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Validation Models.
+
+Provides models for ONEX execution shape validation and chain validation,
+including rules defining handler constraints, violation results for CI gate
+integration, message category to node kind routing validation, coverage metrics
+for routing validation, correlation/causation chain violation tracking,
+and Any type violation detection.
+
+Exports:
+    ModelAnyTypeValidationResult: Aggregate result of Any type validation for CI
+    ModelAnyTypeViolation: Result of Any type violation detection
+    ModelCategoryMatchResult: Result of category matching operation
+    ModelChainViolation: Result of chain violation detection
+    ModelCoverageMetrics: Coverage metrics for routing validation
+    ModelExecutionShapeRule: Rule defining handler type constraints
+    ModelExecutionShapeValidation: Validates message category to node kind routing
+    ModelExecutionShapeValidationResult: Aggregate result of execution shape validation
+    ModelExecutionShapeViolationResult: Result of violation detection
+    ModelLocalHandlerValidationResult: Aggregate result of LocalHandler validation for CI
+    ModelLocalHandlerViolation: Result of LocalHandler import violation detection
+    ModelOutputValidationParams: Parameters for output validation
+    ModelValidateAndRaiseParams: Parameters for validate and raise operations
+    ModelValidationErrorParams: Parameters for security validation error creation
+    ModelValidationOutcome: Generic validation result model
+"""
+
+from omnibase_infra.models.validation.model_any_type_validation_result import (
+    ModelAnyTypeValidationResult,
+)
+from omnibase_infra.models.validation.model_any_type_violation import (
+    ModelAnyTypeViolation,
+)
+from omnibase_infra.models.validation.model_category_match_result import (
+    ModelCategoryMatchResult,
+)
+from omnibase_infra.models.validation.model_chain_violation import ModelChainViolation
+from omnibase_infra.models.validation.model_coverage_metrics import (
+    ModelCoverageMetrics,
+)
+from omnibase_infra.models.validation.model_execution_shape_rule import (
+    ModelExecutionShapeRule,
+)
+from omnibase_infra.models.validation.model_execution_shape_validation import (
+    ModelExecutionShapeValidation,
+)
+from omnibase_infra.models.validation.model_execution_shape_validation_result import (
+    ModelExecutionShapeValidationResult,
+)
+from omnibase_infra.models.validation.model_execution_shape_violation import (
+    ModelExecutionShapeViolationResult,
+)
+from omnibase_infra.models.validation.model_localhandler_validation_result import (
+    ModelLocalHandlerValidationResult,
+)
+from omnibase_infra.models.validation.model_localhandler_violation import (
+    ModelLocalHandlerViolation,
+)
+from omnibase_infra.models.validation.model_output_validation_params import (
+    ModelOutputValidationParams,
+)
+from omnibase_infra.models.validation.model_validate_and_raise_params import (
+    ModelValidateAndRaiseParams,
+)
+from omnibase_infra.models.validation.model_validation_error_params import (
+    ModelValidationErrorParams,
+)
+from omnibase_infra.models.validation.model_validation_outcome import (
+    ModelValidationOutcome,
+)
+
+__all__ = [
+    "ModelAnyTypeValidationResult",
+    "ModelAnyTypeViolation",
+    "ModelCategoryMatchResult",
+    "ModelChainViolation",
+    "ModelCoverageMetrics",
+    "ModelExecutionShapeRule",
+    "ModelExecutionShapeValidation",
+    "ModelExecutionShapeValidationResult",
+    "ModelExecutionShapeViolationResult",
+    "ModelLocalHandlerValidationResult",
+    "ModelLocalHandlerViolation",
+    "ModelOutputValidationParams",
+    "ModelValidateAndRaiseParams",
+    "ModelValidationErrorParams",
+    "ModelValidationOutcome",
+]

omnibase_infra/models/validation/model_any_type_validation_result.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Any Type Validation Result Model.
+
+Defines the aggregate result structure for Any type validation operations.
+Used by the Any type validator to provide a structured result for CI pipeline
+integration with convenience methods for reporting.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.validation.model_any_type_violation import (
+    ModelAnyTypeViolation,
+)
+
+
+class ModelAnyTypeValidationResult(BaseModel):
+    """Aggregate result of Any type validation.
+
+    Provides a structured result for CI pipeline integration with
+    convenience methods for reporting.
+
+    Attributes:
+        passed: True if no blocking violations found.
+        violations: List of all detected violations.
+        files_checked: Number of files that were validated.
+        total_violations: Total count of violations.
+        blocking_count: Count of blocking (error severity) violations.
+
+    Example:
+        >>> result = ModelAnyTypeValidationResult.from_violations(
+        ...     violations=[violation1, violation2],
+        ...     files_checked=10,
+        ... )
+        >>> if not result.passed:
+        ...     print(result.format_summary())
+    """
+
+    passed: bool = Field(
+        ...,
+        description="True if no blocking violations found",
+    )
+    violations: list[ModelAnyTypeViolation] = Field(
+        default_factory=list,
+        description="List of all detected violations",
+    )
+    files_checked: int = Field(
+        default=0,
+        ge=0,
+        description="Number of files that were validated",
+    )
+    total_violations: int = Field(
+        default=0,
+        ge=0,
+        description="Total count of violations",
+    )
+    blocking_count: int = Field(
+        default=0,
+        ge=0,
+        description="Count of blocking (error severity) violations",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    @classmethod
+    def from_violations(
+        cls,
+        violations: list[ModelAnyTypeViolation],
+        files_checked: int = 0,
+    ) -> ModelAnyTypeValidationResult:
+        """Create a result from a list of violations.
+
+        Args:
+            violations: List of detected violations.
+            files_checked: Number of files that were checked.
+
+        Returns:
+            A ModelAnyTypeValidationResult instance.
+        """
+        blocking_count = sum(1 for v in violations if v.is_blocking())
+        return cls(
+            passed=blocking_count == 0,
+            violations=violations,
+            files_checked=files_checked,
+            total_violations=len(violations),
+            blocking_count=blocking_count,
+        )
+
+    def format_for_ci(self) -> list[str]:
+        """Format all violations for CI output.
+
+        Returns:
+            List of formatted strings for CI annotation.
+        """
+        return [v.format_for_ci() for v in self.violations]
+
+    def format_summary(self) -> str:
+        """Format a summary for console output.
+
+        Returns:
+            Summary string with pass/fail status and counts.
+        """
+        status = "PASSED" if self.passed else "FAILED"
+        return (
+            f"Any Type Validation: {status}\n"
+            f"  Files checked: {self.files_checked}\n"
+            f"  Total violations: {self.total_violations}\n"
+            f"  Blocking violations: {self.blocking_count}"
+        )
+
+
+__all__ = ["ModelAnyTypeValidationResult"]

omnibase_infra/models/validation/model_any_type_violation.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Any Type Violation Model.
+
+Defines the result structure for detected Any type violations.
+Used by the Any type 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 EnumAnyTypeViolation, EnumValidationSeverity
+
+
+class ModelAnyTypeViolation(BaseModel):
+    """Result of an Any type 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).
+        column: Column offset where Any appears (0-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).
+        context_name: Name of function, class, or variable where violation occurs.
+
+    Example:
+        >>> violation = ModelAnyTypeViolation(
+        ...     file_path=Path("/src/handlers/data_handler.py"),
+        ...     line_number=42,
+        ...     column=15,
+        ...     violation_type=EnumAnyTypeViolation.FUNCTION_PARAMETER,
+        ...     code_snippet="def process(data: Any) -> str:",
+        ...     suggestion="Replace Any with specific type...",
+        ...     context_name="process",
+        ... )
+
+    Note:
+        Violations with severity='error' should block CI pipelines.
+        Violations with severity='warning' are advisory and should be logged.
+    """
+
+    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)",
+    )
+    column: int = Field(
+        ...,
+        ge=0,
+        description="Column offset where Any appears in the line (0-indexed)",
+    )
+    violation_type: EnumAnyTypeViolation = Field(
+        ...,
+        description="The specific Any type violation category",
+    )
+    code_snippet: str = Field(
+        ...,
+        min_length=1,
+        description="The relevant code snippet showing the violation",
+    )
+    suggestion: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable suggestion for fixing the violation",
+    )
+    severity: EnumValidationSeverity = Field(
+        default=EnumValidationSeverity.ERROR,
+        description="Severity classification: 'error' blocks CI, 'warning' is advisory",
+    )
+    context_name: str = Field(
+        default="",
+        description="Name of function, class, or variable where violation occurs",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        str_strip_whitespace=True,
+        use_enum_values=False,  # Keep enum objects for type safety
+    )
+
+    def is_blocking(self) -> bool:
+        """Check if this violation should block CI.
+
+        Returns:
+            True if severity is 'error', False for 'warning'.
+        """
+        return self.severity == EnumValidationSeverity.ERROR
+
+    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/handler.py,line=42,col=15::FUNCTION_PARAMETER: ...
+        """
+        annotation_type = "error" if self.is_blocking() else "warning"
+        return (
+            f"::{annotation_type} file={self.file_path},line={self.line_number},"
+            f"col={self.column}::{self.violation_type.value}: {self.code_snippet}"
+        )
+
+    def format_human_readable(self) -> str:
+        """Format violation for human-readable console output.
+
+        Returns:
+            Formatted string with file location and suggestion.
+
+        Example:
+            src/handler.py:42:15 - FUNCTION_PARAMETER
+            Code: def process(data: Any) -> str:
+            Suggestion: Replace Any with specific type...
+        """
+        lines = [
+            f"{self.file_path}:{self.line_number}:{self.column} - {self.violation_type.value}",
+            f"  Code: {self.code_snippet}",
+            f"  Suggestion: {self.suggestion}",
+        ]
+        if self.context_name:
+            lines.insert(1, f"  Context: {self.context_name}")
+        return "\n".join(lines)
+
+
+__all__ = ["ModelAnyTypeViolation"]

omnibase_infra/models/validation/model_category_match_result.py

@@ -0,0 +1,345 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Category match result model for message type detection.
+
+This model replaces the tuple pattern ``tuple[bool, MessageOutputCategory | None]``
+that was used for category matching operations in the routing coverage validator.
+By using a structured model, we provide:
+
+- Clear semantics for match results (matched vs has_category)
+- Type-safe access to the matched category
+- Factory methods for common use cases
+
+Usage in routing_coverage_validator.py:
+    The ``_has_message_decorator`` function uses this model to return
+    whether a class has a message type decorator and, if so, which
+    category it represents.
+
+Example:
+    >>> # Successful match with category
+    >>> result = ModelCategoryMatchResult.matched_with_category(
+    ...     EnumMessageCategory.EVENT
+    ... )
+    >>> result.matched
+    True
+    >>> result.has_category
+    True
+    >>> result.category
+    <EnumMessageCategory.EVENT: 'event'>
+
+    >>> # Match without specific category (generic decorator)
+    >>> result = ModelCategoryMatchResult.matched_without_category()
+    >>> result.matched
+    True
+    >>> result.has_category
+    False
+
+    >>> # No match
+    >>> result = ModelCategoryMatchResult.not_matched()
+    >>> result.matched
+    False
+
+.. versionadded:: 0.6.1
+    Created as part of Union Reduction Phase 2 (OMN-1007).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumMessageCategory, EnumNodeOutputType
+from omnibase_infra.types import MessageOutputCategory
+
+
+class ModelCategoryMatchResult(BaseModel):
+    """Result of a category matching operation.
+
+    This model represents the outcome of attempting to match a class name,
+    decorator, or base class to a message category (EVENT, COMMAND, INTENT)
+    or node output type (PROJECTION).
+
+    The model distinguishes between:
+    - **matched**: Whether the matching criteria was satisfied (e.g., decorator found)
+    - **category**: The specific category identified, if any
+
+    This distinction is important because some patterns (e.g., a generic
+    ``@message_type`` decorator) indicate a match but don't specify the category.
+
+    Attributes:
+        matched: Whether the category matching criteria was satisfied.
+        category: The matched category (EnumMessageCategory or EnumNodeOutputType),
+            or None if no specific category was identified.
+
+    Warning:
+        **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to return
+        ``True`` only when ``matched`` is True. This differs from typical Pydantic model
+        behavior where ``bool(model)`` always returns ``True`` for any valid instance.
+
+        This design enables idiomatic conditional checks for category matching::
+
+            if result:
+                # Category was matched - process it
+                handle_category(result.category)
+            else:
+                # No match found - skip processing
+                pass
+
+        If you need to check model validity instead, use explicit attribute access::
+
+            # Check for match (uses __bool__)
+            if result:
+                ...
+
+            # Check model is valid (always True for constructed instance)
+            if result is not None:
+                ...
+
+            # Explicit match check (preferred for clarity)
+            if result.matched:
+                ...
+
+    Example:
+        >>> # Event category match
+        >>> result = ModelCategoryMatchResult.matched_with_category(
+        ...     EnumMessageCategory.EVENT
+        ... )
+        >>> result.matched
+        True
+        >>> result.category
+        <EnumMessageCategory.EVENT: 'event'>
+
+        >>> # Projection (node output type) match
+        >>> result = ModelCategoryMatchResult.matched_with_category(
+        ...     EnumNodeOutputType.PROJECTION
+        ... )
+        >>> result.matched
+        True
+        >>> result.category
+        <EnumNodeOutputType.PROJECTION: 'projection'>
+
+        >>> # No match (e.g., class without message decorator)
+        >>> result = ModelCategoryMatchResult.not_matched()
+        >>> result.matched
+        False
+        >>> result.has_category
+        False
+
+    .. versionadded:: 0.6.1
+        Created as part of OMN-1007 tuple-to-model conversion.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    matched: bool = Field(
+        description="Whether the category matching criteria was satisfied.",
+    )
+    category: MessageOutputCategory | None = Field(
+        default=None,
+        description="The matched category (EnumMessageCategory or EnumNodeOutputType), "
+        "or None if no specific category was identified.",
+    )
+
+    @property
+    def has_category(self) -> bool:
+        """Check if a specific category was identified.
+
+        This property should be used to check if a category exists before
+        accessing the ``category`` field to ensure meaningful results.
+
+        Returns:
+            True if category is not None, False otherwise.
+
+        Example:
+            >>> ModelCategoryMatchResult.matched_with_category(
+            ...     EnumMessageCategory.EVENT
+            ... ).has_category
+            True
+            >>> ModelCategoryMatchResult.matched_without_category().has_category
+            False
+            >>> ModelCategoryMatchResult.not_matched().has_category
+            False
+
+        .. versionadded:: 0.6.1
+        """
+        return self.category is not None
+
+    @property
+    def is_message_category(self) -> bool:
+        """Check if the matched category is a message category (not PROJECTION).
+
+        Message categories (EVENT, COMMAND, INTENT) are routable and can be
+        used for message dispatching. PROJECTION is a node output type that
+        is not routable.
+
+        Returns:
+            True if category is an EnumMessageCategory, False otherwise.
+
+        Example:
+            >>> ModelCategoryMatchResult.matched_with_category(
+            ...     EnumMessageCategory.EVENT
+            ... ).is_message_category
+            True
+            >>> ModelCategoryMatchResult.matched_with_category(
+            ...     EnumNodeOutputType.PROJECTION
+            ... ).is_message_category
+            False
+
+        .. versionadded:: 0.6.1
+        """
+        # Single type check is sufficient - EnumMessageCategory is the only message
+        # category enum. EnumNodeOutputType contains PROJECTION which is NOT a
+        # routable message category (it's for reducer state aggregation outputs).
+        return isinstance(self.category, EnumMessageCategory)
+
+    @property
+    def is_projection(self) -> bool:
+        """Check if the matched category is PROJECTION.
+
+        PROJECTION is a node output type used for reducer state aggregation
+        outputs. It is not a routable message category.
+
+        Returns:
+            True if category is EnumNodeOutputType.PROJECTION, False otherwise.
+
+        Example:
+            >>> ModelCategoryMatchResult.matched_with_category(
+            ...     EnumNodeOutputType.PROJECTION
+            ... ).is_projection
+            True
+            >>> ModelCategoryMatchResult.matched_with_category(
+            ...     EnumMessageCategory.EVENT
+            ... ).is_projection
+            False
+
+        .. versionadded:: 0.6.1
+        """
+        return self.category == EnumNodeOutputType.PROJECTION
+
+    @classmethod
+    def matched_with_category(
+        cls, category: MessageOutputCategory
+    ) -> ModelCategoryMatchResult:
+        """Create a successful match result with a specific category.
+
+        Use this factory when the matching operation found a pattern that
+        indicates a specific message category or node output type.
+
+        Args:
+            category: The matched category (EnumMessageCategory or EnumNodeOutputType).
+
+        Returns:
+            ModelCategoryMatchResult with matched=True and the specified category.
+
+        Example:
+            >>> result = ModelCategoryMatchResult.matched_with_category(
+            ...     EnumMessageCategory.COMMAND
+            ... )
+            >>> result.matched
+            True
+            >>> result.category
+            <EnumMessageCategory.COMMAND: 'command'>
+
+        .. versionadded:: 0.6.1
+        """
+        return cls(matched=True, category=category)
+
+    @classmethod
+    def matched_without_category(cls) -> ModelCategoryMatchResult:
+        """Create a successful match result without a specific category.
+
+        Use this factory when the matching operation found a pattern that
+        indicates a message type, but the specific category cannot be
+        determined. For example, a generic ``@message_type`` decorator
+        without category-specific information.
+
+        Returns:
+            ModelCategoryMatchResult with matched=True but category=None.
+
+        Example:
+            >>> result = ModelCategoryMatchResult.matched_without_category()
+            >>> result.matched
+            True
+            >>> result.has_category
+            False
+
+        .. versionadded:: 0.6.1
+        """
+        return cls(matched=True, category=None)
+
+    @classmethod
+    def not_matched(cls) -> ModelCategoryMatchResult:
+        """Create a result indicating no match was found.
+
+        Use this factory when the matching operation did not find any
+        pattern indicating a message type.
+
+        Returns:
+            ModelCategoryMatchResult with matched=False and category=None.
+
+        Example:
+            >>> result = ModelCategoryMatchResult.not_matched()
+            >>> result.matched
+            False
+            >>> result.has_category
+            False
+
+        .. versionadded:: 0.6.1
+        """
+        return cls(matched=False, category=None)
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context.
+
+        Returns True if the matching operation was successful (matched=True),
+        regardless of whether a specific category was identified.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``matched`` is True. 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 match results::
+
+                if result:
+                    # Category was matched - process it
+                    handle_category(result.category)
+                else:
+                    # No match found - skip processing
+                    pass
+
+            If you need to check model validity instead, use explicit attribute access::
+
+                # Check for match (uses __bool__)
+                if result:
+                    ...
+
+                # Check model is valid (always True for constructed instance)
+                if result is not None:
+                    ...
+
+                # Explicit match check (preferred for clarity)
+                if result.matched:
+                    ...
+
+        Returns:
+            True if matched, False otherwise.
+
+        Example:
+            >>> if ModelCategoryMatchResult.matched_with_category(
+            ...     EnumMessageCategory.EVENT
+            ... ):
+            ...     print("Found!")
+            Found!
+
+            >>> if not ModelCategoryMatchResult.not_matched():
+            ...     print("Not found")
+            Not found
+
+        .. versionadded:: 0.6.1
+        """
+        return self.matched