omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/architecture_validator/models/model_rule_check_result.py

@@ -0,0 +1,265 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Rule check result model for architecture validation.
+
+This module defines the result model returned by architecture validation rules
+when checking targets (nodes, handlers, etc.) for compliance violations.
+
+Result Semantics:
+    The combination of ``passed`` and ``skipped`` fields determines the outcome:
+
+    - ``passed=True, skipped=False``: Target was validated and passed the rule
+    - ``passed=True, skipped=True``: Input not applicable to this rule (e.g.,
+      rule checks file paths but received a non-path object)
+    - ``passed=False, skipped=False``: Violation detected
+
+    The ``skipped`` field disambiguates between "actually passed validation"
+    and "input was not applicable to this rule". This is important for
+    accurate reporting and metrics.
+
+Thread Safety:
+    ModelRuleCheckResult is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from omnibase_infra.nodes.architecture_validator.models import ModelRuleCheckResult
+    >>>
+    >>> # Successful check - target validated and passed
+    >>> result = ModelRuleCheckResult(
+    ...     passed=True,
+    ...     rule_id="NO_HANDLER_PUBLISHING",
+    ... )
+    >>> result.is_applicable()
+    True
+    >>>
+    >>> # Skipped check - input not applicable to rule
+    >>> result = ModelRuleCheckResult(
+    ...     passed=True,
+    ...     skipped=True,
+    ...     rule_id="FILE_PATH_CONVENTION",
+    ...     reason="Input is not a file path",
+    ... )
+    >>> result.is_applicable()
+    False
+    >>>
+    >>> # Failed check with details
+    >>> result = ModelRuleCheckResult(
+    ...     passed=False,
+    ...     rule_id="NO_HANDLER_PUBLISHING",
+    ...     message="Handler has direct event bus access",
+    ...     details={"handler_class": "MyHandler", "forbidden_attribute": "_event_bus"},
+    ... )
+
+See Also:
+    omnibase_infra.nodes.architecture_validator.protocols.ProtocolArchitectureRule:
+        Protocol that produces these results
+    omnibase_infra.enums.EnumValidationSeverity:
+        Severity levels for rule violations
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["ModelRuleCheckResult"]
+
+
+class ModelRuleCheckResult(BaseModel):
+    """Result of checking a target against an architecture rule.
+
+    Captures the outcome of validating a node, handler, or other architectural
+    component against a specific rule. Used for aggregating validation results
+    and reporting violations.
+
+    Result Semantics:
+        The combination of ``passed`` and ``skipped`` determines the outcome:
+
+        - ``passed=True, skipped=False``: Target was validated and passed
+        - ``passed=True, skipped=True``: Input not applicable to this rule
+        - ``passed=False, skipped=False``: Violation detected
+
+        Use ``is_applicable()`` to check if the rule was actually evaluated,
+        and ``is_violation()`` to check if a violation was detected.
+
+    Attributes:
+        passed: Whether the target passed the rule check. Note that when
+            ``skipped=True``, this is ``True`` by convention but does not
+            indicate actual validation success.
+        skipped: Whether the check was skipped because the input was not
+            applicable to this rule. For example, a file-path naming rule
+            would skip non-path inputs. Defaults to ``False``.
+        rule_id: Unique identifier of the rule that was checked.
+        message: Human-readable message describing the result or violation.
+        reason: Explanation for why the check was skipped. Only populated
+            when ``skipped=True``. Example: "Input is not a file path".
+        details: Additional details about the check result for debugging.
+
+    Example:
+        >>> # Violation detected
+        >>> result = ModelRuleCheckResult(
+        ...     passed=False,
+        ...     rule_id="NO_WORKFLOW_LOGIC_IN_REDUCER",
+        ...     message="Reducer contains orchestration logic",
+        ...     details={
+        ...         "reducer_class": "MyReducer",
+        ...         "forbidden_method": "execute_workflow",
+        ...     },
+        ... )
+        >>> result.passed
+        False
+        >>> result.is_violation()
+        True
+        >>> result.is_applicable()
+        True
+        >>>
+        >>> # Skipped - input not applicable
+        >>> skipped_result = ModelRuleCheckResult(
+        ...     passed=True,
+        ...     skipped=True,
+        ...     rule_id="FILE_NAMING_CONVENTION",
+        ...     reason="Input is not a file path",
+        ... )
+        >>> skipped_result.passed
+        True
+        >>> skipped_result.is_applicable()
+        False
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    passed: bool = Field(
+        ...,
+        description=(
+            "Whether the target passed the rule check. Note that when "
+            "skipped=True, this is True by convention but does not indicate "
+            "actual validation success."
+        ),
+    )
+
+    skipped: bool = Field(
+        default=False,
+        description=(
+            "Whether the check was skipped because the input was not "
+            "applicable to this rule. For example, a file-path naming rule "
+            "would skip non-path inputs. When True, passed is also True by "
+            "convention."
+        ),
+    )
+
+    rule_id: str = Field(
+        ...,
+        description="Unique identifier of the rule that was checked.",
+        min_length=1,
+    )
+
+    message: str | None = Field(
+        default=None,
+        description=(
+            "Human-readable message describing the result or violation. "
+            "Typically populated when the check fails."
+        ),
+    )
+
+    reason: str | None = Field(
+        default=None,
+        description=(
+            "Explanation for why the check was skipped. Only populated when "
+            "skipped=True. Example: 'Input is not a file path'."
+        ),
+    )
+
+    details: dict[str, object] | None = Field(
+        default=None,
+        description=(
+            "Additional details about the check result for debugging. "
+            "May include target class names, forbidden attributes, etc."
+        ),
+    )
+
+    def is_violation(self) -> bool:
+        """Check if this result represents a rule violation.
+
+        A result is a violation only when the check was actually performed
+        (not skipped) and failed.
+
+        Returns:
+            True if the check failed (violation detected), False otherwise.
+            Returns False when skipped, even though passed=True.
+
+        Example:
+            >>> result = ModelRuleCheckResult(passed=False, rule_id="RULE_1")
+            >>> result.is_violation()
+            True
+            >>> skipped = ModelRuleCheckResult(
+            ...     passed=True, skipped=True, rule_id="RULE_1", reason="N/A"
+            ... )
+            >>> skipped.is_violation()
+            False
+        """
+        return not self.passed
+
+    def is_applicable(self) -> bool:
+        """Check if the rule was applicable to the input.
+
+        A rule is applicable when it was actually evaluated against the input,
+        as opposed to being skipped because the input type was not relevant
+        to the rule.
+
+        Returns:
+            True if the rule was evaluated (not skipped), False if skipped.
+
+        Example:
+            >>> # Rule was evaluated and passed
+            >>> result = ModelRuleCheckResult(passed=True, rule_id="RULE_1")
+            >>> result.is_applicable()
+            True
+            >>>
+            >>> # Rule was skipped - input not applicable
+            >>> skipped = ModelRuleCheckResult(
+            ...     passed=True,
+            ...     skipped=True,
+            ...     rule_id="FILE_PATH_RULE",
+            ...     reason="Input is not a file path",
+            ... )
+            >>> skipped.is_applicable()
+            False
+        """
+        return not self.skipped
+
+    def with_message(self, message: str) -> ModelRuleCheckResult:
+        """Create a new result with an updated message.
+
+        Args:
+            message: The new message to set.
+
+        Returns:
+            New ModelRuleCheckResult with the updated message.
+
+        Example:
+            >>> result = ModelRuleCheckResult(passed=False, rule_id="RULE_1")
+            >>> updated = result.with_message("Violation detected")
+            >>> updated.message
+            'Violation detected'
+        """
+        return self.model_copy(update={"message": message})
+
+    def with_details(self, details: dict[str, object]) -> ModelRuleCheckResult:
+        """Create a new result with updated details.
+
+        Args:
+            details: The new details to set.
+
+        Returns:
+            New ModelRuleCheckResult with the updated details.
+
+        Example:
+            >>> result = ModelRuleCheckResult(passed=False, rule_id="RULE_1")
+            >>> updated = result.with_details({"class": "MyHandler"})
+            >>> updated.details
+            {'class': 'MyHandler'}
+        """
+        return self.model_copy(update={"details": details})

omnibase_infra/nodes/architecture_validator/models/model_validation_request.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Architecture validation request model for the architecture validator node.
+
+This module defines the input model for requesting architecture validation.
+Callers can specify paths to validate, specific rules to check, and
+whether to fail fast on the first violation.
+
+Example:
+    >>> from omnibase_infra.nodes.architecture_validator.models import (
+    ...     ModelArchitectureValidationRequest,
+    ... )
+    >>> # Validate specific files with all rules
+    >>> request = ModelArchitectureValidationRequest(
+    ...     paths=["src/mymodule/service.py", "src/mymodule/models/"],
+    ... )
+    >>> # Validate with specific rules only
+    >>> request = ModelArchitectureValidationRequest(
+    ...     paths=["src/"],
+    ...     rule_ids=["ARCH-001", "ARCH-002"],
+    ...     fail_fast=True,
+    ... )
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelArchitectureValidationRequest(BaseModel):
+    """Request to validate architecture patterns in code.
+
+    This model represents a validation request containing the paths
+    to validate, optional rule filters, and execution options.
+
+    Attributes:
+        paths: List of paths to validate. Can be files, directories,
+            or glob patterns (e.g., "src/**/*.py"). If empty, validation
+            may use a default scope or fail depending on implementation.
+        rule_ids: Optional list of specific rule IDs to check.
+            If empty, all available rules are applied.
+        fail_fast: If True, stop validation on the first violation found.
+            Useful for quick CI checks. Default is False (check all).
+
+    Example:
+        >>> # Validate entire src directory
+        >>> request = ModelArchitectureValidationRequest(
+        ...     paths=["src/"],
+        ... )
+        >>> # Validate with specific rules and fail fast
+        >>> request = ModelArchitectureValidationRequest(
+        ...     paths=["src/omnibase_infra/"],
+        ...     rule_ids=["ARCH-001", "ARCH-003"],
+        ...     fail_fast=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    paths: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Paths to validate. Can be files, directories, or glob patterns. "
+            "If empty, validation scope depends on implementation."
+        ),
+    )
+    rule_ids: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Optional list of specific rule IDs to check (e.g., ['ARCH-001']). "
+            "If empty, all available rules are applied."
+        ),
+    )
+    fail_fast: bool = Field(
+        default=False,
+        description=(
+            "If True, stop validation on the first violation found. "
+            "Useful for quick CI checks."
+        ),
+    )
+
+    @property
+    def has_paths(self) -> bool:
+        """Check if any paths are specified for validation.
+
+        Returns:
+            True if paths list is non-empty, False otherwise.
+        """
+        return len(self.paths) > 0
+
+    @property
+    def has_rule_filter(self) -> bool:
+        """Check if specific rules are requested.
+
+        Returns:
+            True if rule_ids list is non-empty, False otherwise.
+        """
+        return len(self.rule_ids) > 0
+
+
+__all__ = ["ModelArchitectureValidationRequest"]

omnibase_infra/nodes/architecture_validator/models/model_validation_result.py

@@ -0,0 +1,314 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""File-based validation result model for the architecture validator node.
+
+This module defines the output model for file-based architecture validation
+results (OMN-1099). It contains the overall validation status, any violations
+found, and metadata about the validation run.
+
+Note:
+    This is distinct from ModelArchitectureValidationResult in
+    model_architecture_validation_result.py (OMN-1138) which is used for
+    node/handler validation with different fields (nodes_checked, handlers_checked).
+
+Design Pattern:
+    ModelFileValidationResult overrides ``__bool__`` to return
+    ``True`` only when validation passed (no violations). This enables
+    idiomatic conditional checks::
+
+        result = validator.validate(request)
+        if result:
+            print("Validation passed!")
+        else:
+            print(f"Found {len(result.violations)} violations")
+
+Example:
+    >>> from omnibase_infra.nodes.architecture_validator.models.model_validation_result import (
+    ...     ModelFileValidationResult,
+    ... )
+    >>> from omnibase_infra.nodes.architecture_validator.models import (
+    ...     ModelArchitectureViolation,
+    ...     EnumValidationSeverity,
+    ... )
+    >>> # Passing result
+    >>> result = ModelFileValidationResult(
+    ...     valid=True,
+    ...     violations=[],
+    ...     files_checked=42,
+    ...     rules_checked=["ARCH-001", "ARCH-002"],
+    ... )
+    >>> bool(result)
+    True
+    >>>
+    >>> # Failing result
+    >>> violation = ModelArchitectureViolation(
+    ...     rule_id="ARCH-001",
+    ...     rule_name="No Any Types",
+    ...     severity=EnumValidationSeverity.ERROR,
+    ...     target_type="model",
+    ...     target_name="BadModel",
+    ...     message="Found Any type",
+    ... )
+    >>> result = ModelFileValidationResult(
+    ...     valid=False,
+    ...     violations=[violation],
+    ...     files_checked=42,
+    ...     rules_checked=["ARCH-001"],
+    ... )
+    >>> bool(result)
+    False
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumValidationSeverity
+from omnibase_infra.nodes.architecture_validator.models.model_architecture_violation import (
+    ModelArchitectureViolation,
+)
+
+
+class ModelFileValidationResult(BaseModel):
+    """Result of file-based architecture validation containing status and violations.
+
+    This model represents the complete result of a file-based validation run
+    (OMN-1099), including whether validation passed, any violations found,
+    and metadata about what was checked.
+
+    Note:
+        This is distinct from ModelArchitectureValidationResult in
+        model_architecture_validation_result.py (OMN-1138) which uses
+        nodes_checked and handlers_checked instead of files_checked.
+
+    Attributes:
+        valid: True if no violations were found, False otherwise.
+        violations: List of architecture violations detected.
+        files_checked: Number of files that were validated.
+        rules_checked: List of rule IDs that were applied.
+
+    Warning:
+        **Non-standard __bool__ behavior**: This model overrides ``__bool__``
+        to return ``True`` only when validation passed (``valid`` 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::
+
+            if result:
+                # Validation passed - no violations
+                deploy()
+            else:
+                # Validation failed - has violations
+                print(result.violations)
+
+        If you need to check model validity instead, use explicit attribute access::
+
+            # Check validation passed (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 passing result
+        >>> result = ModelFileValidationResult(
+        ...     valid=True,
+        ...     files_checked=100,
+        ...     rules_checked=["ARCH-001", "ARCH-002", "ARCH-003"],
+        ... )
+        >>> result.valid
+        True
+        >>> bool(result)
+        True
+        >>>
+        >>> # Create a failing result
+        >>> result = ModelFileValidationResult(
+        ...     valid=False,
+        ...     violations=[violation],
+        ...     files_checked=100,
+        ...     rules_checked=["ARCH-001"],
+        ... )
+        >>> result.valid
+        False
+        >>> bool(result)
+        False
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    valid: bool = Field(
+        ...,
+        description="True if no violations were found, False otherwise.",
+    )
+    violations: list[ModelArchitectureViolation] = Field(
+        default_factory=list,
+        description="List of architecture violations detected during validation.",
+    )
+    files_checked: int = Field(
+        default=0,
+        description="Number of files that were validated.",
+        ge=0,
+    )
+    rules_checked: list[str] = Field(
+        default_factory=list,
+        description="List of rule IDs that were applied during validation.",
+    )
+
+    @property
+    def violation_count(self) -> int:
+        """Get the number of violations found.
+
+        Returns:
+            Number of violations in the violations list.
+        """
+        return len(self.violations)
+
+    @property
+    def error_count(self) -> int:
+        """Get the number of ERROR severity violations.
+
+        Returns:
+            Count of violations with ERROR severity.
+        """
+        return sum(
+            1 for v in self.violations if v.severity == EnumValidationSeverity.ERROR
+        )
+
+    @property
+    def warning_count(self) -> int:
+        """Get the number of WARNING severity violations.
+
+        Returns:
+            Count of violations with WARNING severity.
+        """
+        return sum(
+            1 for v in self.violations if v.severity == EnumValidationSeverity.WARNING
+        )
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context to check validation status.
+
+        Returns True if validation passed (no violations found),
+        indicating the code meets architecture requirements.
+
+        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 have violations.
+
+            Use ``result.valid`` for explicit, self-documenting code.
+            Use ``result is not None`` if you need to check model existence.
+
+        Returns:
+            True if valid is True, False otherwise.
+
+        Example:
+            >>> result_pass = ModelFileValidationResult(valid=True)
+            >>> bool(result_pass)
+            True
+            >>>
+            >>> result_fail = ModelFileValidationResult(
+            ...     valid=False,
+            ...     violations=[some_violation],
+            ... )
+            >>> bool(result_fail)  # False even though model is valid!
+            False
+        """
+        return self.valid
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String showing validation status, file count, and violation count.
+        """
+        status = "PASSED" if self.valid else "FAILED"
+        return (
+            f"ModelFileValidationResult("
+            f"status={status}, "
+            f"files={self.files_checked}, "
+            f"violations={self.violation_count})"
+        )
+
+    @classmethod
+    def passed(
+        cls,
+        files_checked: int = 0,
+        rules_checked: list[str] | None = None,
+    ) -> ModelFileValidationResult:
+        """Create a passing validation result.
+
+        Factory method for creating a result with no violations.
+
+        Args:
+            files_checked: Number of files that were validated.
+            rules_checked: List of rule IDs that were applied.
+
+        Returns:
+            ModelFileValidationResult with valid=True and no violations.
+
+        Example:
+            >>> result = ModelFileValidationResult.passed(
+            ...     files_checked=50,
+            ...     rules_checked=["ARCH-001", "ARCH-002"],
+            ... )
+            >>> result.valid
+            True
+        """
+        return cls(
+            valid=True,
+            violations=[],
+            files_checked=files_checked,
+            rules_checked=rules_checked or [],
+        )
+
+    @classmethod
+    def failed(
+        cls,
+        violations: list[ModelArchitectureViolation],
+        files_checked: int = 0,
+        rules_checked: list[str] | None = None,
+    ) -> ModelFileValidationResult:
+        """Create a failing validation result.
+
+        Factory method for creating a result with violations.
+
+        Args:
+            violations: List of architecture violations found.
+            files_checked: Number of files that were validated.
+            rules_checked: List of rule IDs that were applied.
+
+        Returns:
+            ModelFileValidationResult with valid=False and violations.
+
+        Example:
+            >>> result = ModelFileValidationResult.failed(
+            ...     violations=[violation1, violation2],
+            ...     files_checked=50,
+            ...     rules_checked=["ARCH-001"],
+            ... )
+            >>> result.valid
+            False
+            >>> result.violation_count
+            2
+        """
+        return cls(
+            valid=False,
+            violations=violations,
+            files_checked=files_checked,
+            rules_checked=rules_checked or [],
+        )
+
+
+__all__ = ["ModelFileValidationResult"]