omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/validation/model_localhandler_validation_result.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""LocalHandler Validation Result Model.
+
+Defines the aggregate result structure for LocalHandler validation operations.
+Used by the LocalHandler 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_localhandler_violation import (
+    ModelLocalHandlerViolation,
+)
+
+
+class ModelLocalHandlerValidationResult(BaseModel):
+    """Aggregate result of LocalHandler validation.
+
+    Provides a structured result for CI pipeline integration with
+    convenience methods for reporting.
+
+    Attributes:
+        passed: True if no violations found.
+        violations: List of all detected violations.
+        files_checked: Number of files that were validated.
+
+    Custom Boolean Behavior:
+        This model implements ``__bool__`` to return ``passed``.
+        This enables idiomatic usage like ``if result: ...``.
+
+        Warning:
+            This differs from standard Pydantic behavior where
+            ``bool(model)`` always returns True for non-empty models.
+
+    Example:
+        >>> result = ModelLocalHandlerValidationResult.from_violations(
+        ...     violations=[violation1],
+        ...     files_checked=10,
+        ... )
+        >>> if not result:  # Uses __bool__, checks passed
+        ...     print(result.format_summary())
+    """
+
+    passed: bool = Field(
+        ...,
+        description="True if no LocalHandler violations found",
+    )
+    violations: list[ModelLocalHandlerViolation] = 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",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    def __bool__(self) -> bool:
+        """Return True if validation passed (no violations).
+
+        Warning:
+            This differs from standard Pydantic behavior where
+            ``bool(model)`` always returns True for non-empty models.
+            Here, ``bool(result)`` returns ``result.passed``.
+        """
+        return self.passed
+
+    @classmethod
+    def from_violations(
+        cls,
+        violations: list[ModelLocalHandlerViolation],
+        files_checked: int = 0,
+    ) -> ModelLocalHandlerValidationResult:
+        """Create a result from a list of violations.
+
+        Args:
+            violations: List of detected violations.
+            files_checked: Number of files that were checked.
+
+        Returns:
+            A ModelLocalHandlerValidationResult instance.
+        """
+        return cls(
+            passed=len(violations) == 0,
+            violations=violations,
+            files_checked=files_checked,
+        )
+
+    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 violation count.
+
+        Example:
+            LocalHandler: FAIL
+              Blocked imports found in src/omnibase_infra/:
+              - src/.../bad_handler.py:5: from omnibase_core.handlers import LocalHandler
+
+              LocalHandler is for test-only use. Remove from production code.
+        """
+        if self.passed:
+            return (
+                f"LocalHandler: PASS\n"
+                f"  Files checked: {self.files_checked}\n"
+                f"  No LocalHandler imports found in production code."
+            )
+
+        lines = [
+            "LocalHandler: FAIL",
+            "  Blocked imports found in src/omnibase_infra/:",
+        ]
+        for v in self.violations:
+            lines.append(f"  - {v.file_path}:{v.line_number}: {v.import_line}")
+        lines.append("")
+        lines.append(
+            "  LocalHandler is for test-only use. Remove from production code."
+        )
+        return "\n".join(lines)
+
+
+__all__ = ["ModelLocalHandlerValidationResult"]

omnibase_infra/models/validation/model_localhandler_violation.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""LocalHandler Violation Model.
+
+Defines the result structure for detected LocalHandler import violations.
+Used by the LocalHandler validator to report policy breaches with
+full context for debugging and CI gate integration.
+
+LocalHandler is a test-only handler that must NEVER be imported in production
+code (src/omnibase_infra/). This validator enforces that policy.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLocalHandlerViolation(BaseModel):
+    """Result of a LocalHandler import violation detection.
+
+    Contains full context about a detected violation for debugging,
+    reporting, and CI gate integration. Each violation includes the
+    source location, the violating import line, 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).
+        import_line: The actual import statement that violates the policy.
+
+    Example:
+        >>> violation = ModelLocalHandlerViolation(
+        ...     file_path=Path("/src/omnibase_infra/handlers/bad_handler.py"),
+        ...     line_number=5,
+        ...     import_line="from omnibase_core.handlers import LocalHandler",
+        ... )
+        >>> print(violation.format_for_ci())
+        ::error file=.../bad_handler.py,line=5::LocalHandler import forbidden...
+
+    Note:
+        All LocalHandler violations are blocking (error severity).
+        LocalHandler is only permitted in test code (tests/ directory).
+    """
+
+    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)",
+    )
+    import_line: str = Field(
+        ...,
+        min_length=1,
+        description="The actual import statement that violates the policy",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        str_strip_whitespace=True,
+    )
+
+    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=5::LocalHandler import forbidden...
+        """
+        return (
+            f"::error file={self.file_path},line={self.line_number}::"
+            f"LocalHandler import forbidden in production code: {self.import_line}"
+        )
+
+    def format_human_readable(self) -> str:
+        """Format violation for human-readable console output.
+
+        Returns:
+            Formatted string with file location and violation details.
+
+        Example:
+            src/omnibase_infra/handlers/bad_handler.py:5
+              Import: from omnibase_core.handlers import LocalHandler
+              Fix: Remove LocalHandler - use only in tests/
+        """
+        return (
+            f"{self.file_path}:{self.line_number}\n"
+            f"  Import: {self.import_line}\n"
+            f"  Fix: Remove LocalHandler import - LocalHandler is for test-only use"
+        )
+
+
+__all__ = ["ModelLocalHandlerViolation"]

omnibase_infra/models/validation/model_output_validation_params.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Output Validation Parameters Model.
+
+Defines the parameter model for validating outputs against
+execution shape constraints.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import (
+    EnumMessageCategory,
+    EnumNodeArchetype,
+    EnumNodeOutputType,
+)
+
+
+class ModelOutputValidationParams(BaseModel):
+    """Parameters for validating output against execution shape constraints.
+
+    This model encapsulates the parameters needed for the validate_handler_output
+    method of RuntimeShapeValidator.
+
+    Attributes:
+        node_archetype: The declared node archetype.
+        output: The actual output object (used for context in violation message).
+        output_category: The message category or node output type of the output.
+        file_path: Optional file path for violation reporting.
+        line_number: Optional line number for violation reporting.
+
+    Example:
+        >>> params = ModelOutputValidationParams(
+        ...     node_archetype=EnumNodeArchetype.REDUCER,
+        ...     output=some_event,
+        ...     output_category=EnumMessageCategory.EVENT,
+        ...     file_path="test_handler.py",
+        ...     line_number=42,
+        ... )
+    """
+
+    node_archetype: EnumNodeArchetype = Field(
+        ...,
+        description="The declared node archetype",
+    )
+    # NOTE: Using `object` per ONEX guidelines (not `Any`) - output can be any handler return value
+    output: object = Field(
+        ...,
+        description="The actual output object (used for context in violation message)",
+    )
+    output_category: EnumMessageCategory | EnumNodeOutputType = Field(
+        ...,
+        description="The message category or node output type of the output",
+    )
+    file_path: str = Field(
+        default="<runtime>",
+        description="Optional file path for violation reporting",
+    )
+    line_number: int = Field(
+        default=0,
+        ge=0,
+        description="Optional line number for violation reporting",
+    )
+
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True,
+        str_strip_whitespace=True,
+        arbitrary_types_allowed=True,  # Allow arbitrary types for output field
+    )
+
+
+__all__ = ["ModelOutputValidationParams"]

omnibase_infra/models/validation/model_validate_and_raise_params.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validate and Raise Parameters Model.
+
+Defines the parameter model for validating handler outputs and raising
+exceptions on violations, supporting correlation ID for distributed tracing.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import (
+    EnumMessageCategory,
+    EnumNodeArchetype,
+    EnumNodeOutputType,
+)
+
+
+class ModelValidateAndRaiseParams(BaseModel):
+    """Parameters for validating handler output and raising exception if invalid.
+
+    This model encapsulates the parameters needed for the validate_and_raise
+    method of RuntimeShapeValidator, including optional correlation ID for
+    distributed tracing.
+
+    Attributes:
+        node_archetype: The declared node archetype.
+        output: The actual output object.
+        output_category: The message category or node output type of the output.
+        file_path: Optional file path for violation reporting.
+        line_number: Optional line number for violation reporting.
+        correlation_id: Optional correlation ID for distributed tracing.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> params = ModelValidateAndRaiseParams(
+        ...     node_archetype=EnumNodeArchetype.REDUCER,
+        ...     output=event_output,
+        ...     output_category=EnumMessageCategory.EVENT,
+        ...     file_path="handler.py",
+        ...     line_number=42,
+        ...     correlation_id=uuid4(),
+        ... )
+    """
+
+    node_archetype: EnumNodeArchetype = Field(
+        ...,
+        description="The declared node archetype",
+    )
+    # NOTE: Using `object` per ONEX guidelines (not `Any`) - output can be any handler return value
+    output: object = Field(
+        ...,
+        description="The actual output object",
+    )
+    output_category: EnumMessageCategory | EnumNodeOutputType = Field(
+        ...,
+        description="The message category or node output type of the output",
+    )
+    file_path: str = Field(
+        default="<runtime>",
+        description="Optional file path for violation reporting",
+    )
+    line_number: int = Field(
+        default=0,
+        ge=0,
+        description="Optional line number for violation reporting",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Optional correlation ID for distributed tracing",
+    )
+
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True,
+        str_strip_whitespace=True,
+        arbitrary_types_allowed=True,  # Allow arbitrary types for output field
+    )
+
+
+__all__ = ["ModelValidateAndRaiseParams"]

omnibase_infra/models/validation/model_validation_error_params.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validation Error Parameters Model.
+
+Defines the parameter model for creating security validation errors,
+encapsulating all required and optional parameters for the
+convert_to_validation_error function.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.handlers import ModelHandlerIdentifier
+
+
+class ModelValidationErrorParams(BaseModel):
+    """Parameters for creating a security validation error.
+
+    This model encapsulates the parameters needed to create a
+    ModelHandlerValidationError from security validation results.
+
+    Attributes:
+        rule_code: Unique code for the validation rule (e.g., "SECURITY-001").
+        message: Human-readable error message.
+        remediation_hint: Actionable fix suggestion.
+        handler_identity: Handler identification information.
+        file_path: Optional file path where error occurred.
+        line_number: Optional line number (1-indexed).
+        details: Optional additional context.
+
+    Example:
+        >>> params = ModelValidationErrorParams(
+        ...     rule_code="SECURITY-001",
+        ...     message="Handler exposes 'get_password' method",
+        ...     remediation_hint="Prefix with underscore: '_get_password'",
+        ...     handler_identity=ModelHandlerIdentifier.from_handler_id("auth"),
+        ...     file_path="nodes/auth/handlers/handler_authenticate.py",
+        ...     line_number=42,
+        ... )
+    """
+
+    rule_code: str = Field(
+        ...,
+        description="Unique code for the validation rule (e.g., 'SECURITY-001')",
+        min_length=1,
+    )
+    message: str = Field(
+        ...,
+        description="Human-readable error message",
+        min_length=1,
+    )
+    remediation_hint: str = Field(
+        ...,
+        description="Actionable fix suggestion",
+        min_length=1,
+    )
+    handler_identity: ModelHandlerIdentifier = Field(
+        ...,
+        description="Handler identification information",
+    )
+    file_path: str | None = Field(
+        default=None,
+        description="Optional file path where error occurred",
+    )
+    line_number: int | None = Field(
+        default=None,
+        ge=1,
+        description="Optional line number (1-indexed)",
+    )
+    details: dict[str, object] | None = Field(
+        default=None,
+        description="Optional additional context",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        str_strip_whitespace=True,
+    )
+
+
+__all__ = ["ModelValidationErrorParams"]