omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/validation/mixin_node_archetype_detection.py

@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Mixin for AST-based node archetype detection.
+
+This module provides the MixinNodeArchetypeDetection mixin which extracts handler
+detection logic from ExecutionShapeValidator. It detects ONEX node archetypes
+(EFFECT, COMPUTE, REDUCER, ORCHESTRATOR) from Python AST structures.
+
+Detection Methods:
+    - Class name suffix: *EffectHandler, *ReducerHandler, etc.
+    - Base class: class MyHandler(EffectHandler)
+    - Decorator: @node_archetype(EnumNodeArchetype.EFFECT), @effect_handler
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+from omnibase_infra.enums import EnumNodeArchetype
+
+if TYPE_CHECKING:
+    from omnibase_infra.validation.validator_execution_shape import (
+        ModelDetectedNodeInfo,
+    )
+
+# Node archetype detection patterns
+_NODE_ARCHETYPE_SUFFIX_MAP: dict[str, EnumNodeArchetype] = {
+    "EffectHandler": EnumNodeArchetype.EFFECT,
+    "ReducerHandler": EnumNodeArchetype.REDUCER,
+    "OrchestratorHandler": EnumNodeArchetype.ORCHESTRATOR,
+    "ComputeHandler": EnumNodeArchetype.COMPUTE,
+    # Base class patterns
+    "Effect": EnumNodeArchetype.EFFECT,
+    "Reducer": EnumNodeArchetype.REDUCER,
+    "Orchestrator": EnumNodeArchetype.ORCHESTRATOR,
+    "Compute": EnumNodeArchetype.COMPUTE,
+}
+
+
+class MixinNodeArchetypeDetection:
+    """Mixin providing AST-based node archetype detection capabilities.
+
+    This mixin extracts handler detection logic from ExecutionShapeValidator
+    to reduce method count while preserving functionality.
+
+    Methods:
+        _find_handlers: Find all handler classes and functions in an AST.
+        _detect_node_archetype_from_class: Detect archetype from class definition.
+        _detect_node_archetype_from_decorator: Detect archetype from decorators.
+        _get_name_from_expr: Extract name string from AST expression.
+    """
+
+    def _find_handlers(
+        self, tree: ast.AST, file_path: str
+    ) -> list[ModelDetectedNodeInfo]:
+        """Find all handler classes and functions in an AST.
+
+        Detection methods:
+            1. Class name suffix: *EffectHandler, *ReducerHandler, etc.
+            2. Base class: class MyHandler(EffectHandler)
+            3. Decorator: @node_archetype(EnumNodeArchetype.EFFECT)
+
+        Args:
+            tree: The parsed AST.
+            file_path: Path to the source file.
+
+        Returns:
+            List of detected handlers with their archetype information.
+        """
+        # Import here to avoid circular import at module level
+        from omnibase_infra.validation.validator_execution_shape import (
+            ModelDetectedNodeInfo,
+        )
+
+        handlers: list[ModelDetectedNodeInfo] = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                archetype = self._detect_node_archetype_from_class(node)
+                if archetype is not None:
+                    handlers.append(
+                        ModelDetectedNodeInfo(
+                            name=node.name,
+                            node_archetype=archetype,
+                            node=node,
+                            line_number=node.lineno,
+                            file_path=file_path,
+                        )
+                    )
+            elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                archetype = self._detect_node_archetype_from_decorator(node)
+                if archetype is not None:
+                    handlers.append(
+                        ModelDetectedNodeInfo(
+                            name=node.name,
+                            node_archetype=archetype,
+                            node=node,
+                            line_number=node.lineno,
+                            file_path=file_path,
+                        )
+                    )
+
+        return handlers
+
+    def _detect_node_archetype_from_class(
+        self,
+        node: ast.ClassDef,
+    ) -> EnumNodeArchetype | None:
+        """Detect node archetype from class definition.
+
+        Checks:
+            1. Class name suffix (e.g., OrderEffectHandler)
+            2. Base class names (e.g., class OrderHandler(EffectHandler))
+            3. Decorator on class
+
+        Args:
+            node: The class definition AST node.
+
+        Returns:
+            The detected node archetype, or None if not a handler.
+        """
+        # Check class name suffix
+        for suffix, archetype in _NODE_ARCHETYPE_SUFFIX_MAP.items():
+            if node.name.endswith(suffix):
+                return archetype
+
+        # Check base classes
+        for base in node.bases:
+            base_name = self._get_name_from_expr(base)
+            if base_name is not None:
+                for pattern, archetype in _NODE_ARCHETYPE_SUFFIX_MAP.items():
+                    if base_name.endswith(pattern):
+                        return archetype
+
+        # Check decorators
+        return self._detect_node_archetype_from_decorator(node)
+
+    def _detect_node_archetype_from_decorator(
+        self,
+        node: ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> EnumNodeArchetype | None:
+        """Detect node archetype from decorators.
+
+        Looks for patterns like:
+            @node_archetype(EnumNodeArchetype.EFFECT)
+            @effect_handler
+            @reducer_handler
+
+        Args:
+            node: The AST node with decorators.
+
+        Returns:
+            The detected node archetype, or None if not found.
+        """
+        for decorator in node.decorator_list:
+            # Check @node_archetype(EnumNodeArchetype.X) pattern
+            if isinstance(decorator, ast.Call):
+                func = decorator.func
+                func_name = self._get_name_from_expr(func)
+                if func_name in ("node_archetype", "handler_type") and decorator.args:
+                    arg = decorator.args[0]
+                    arg_str = self._get_name_from_expr(arg)
+                    if arg_str is not None:
+                        # Handle EnumNodeArchetype.EFFECT or just EFFECT
+                        # Use exact matching to avoid false positives from substring matches
+                        # (e.g., "side_effect" should not match "effect")
+                        arg_upper = arg_str.upper()
+                        for archetype in EnumNodeArchetype:
+                            # Match exact enum member name: "EFFECT", "COMPUTE", etc.
+                            if arg_upper == archetype.name:
+                                return archetype
+                            # Match qualified name: "EnumNodeArchetype.EFFECT"
+                            if arg_upper.endswith(f".{archetype.name}"):
+                                return archetype
+                            # Match quoted string value: "effect", "compute", etc.
+                            if arg_upper == archetype.value.upper():
+                                return archetype
+
+            # Check @effect_handler, @reducer_handler patterns
+            # Use suffix/prefix matching to reduce false positives from decorators
+            # that happen to contain archetype keywords (e.g., @side_effect)
+            decorator_name = self._get_name_from_expr(decorator)
+            if decorator_name is not None:
+                decorator_lower = decorator_name.lower()
+
+                # Check for specific handler decorator patterns:
+                # - Suffix: *_effect, *_reducer, *_orchestrator, *_compute
+                # - Prefix: effect_*, reducer_*, orchestrator_*, compute_*
+                # - Exact: effect, reducer, orchestrator, compute
+                #
+                # This avoids false positives like:
+                # - @side_effect (not an effect handler decorator)
+                # - @no_compute (not a compute handler decorator)
+
+                # Effect handler patterns
+                if (
+                    decorator_lower.endswith("_effect")
+                    or decorator_lower.startswith("effect_")
+                    or decorator_lower == "effect"
+                    or decorator_lower == "effect_handler"
+                ):
+                    return EnumNodeArchetype.EFFECT
+
+                # Reducer handler patterns
+                if (
+                    decorator_lower.endswith("_reducer")
+                    or decorator_lower.startswith("reducer_")
+                    or decorator_lower == "reducer"
+                    or decorator_lower == "reducer_handler"
+                ):
+                    return EnumNodeArchetype.REDUCER
+
+                # Orchestrator handler patterns
+                if (
+                    decorator_lower.endswith("_orchestrator")
+                    or decorator_lower.startswith("orchestrator_")
+                    or decorator_lower == "orchestrator"
+                    or decorator_lower == "orchestrator_handler"
+                ):
+                    return EnumNodeArchetype.ORCHESTRATOR
+
+                # Compute handler patterns
+                if (
+                    decorator_lower.endswith("_compute")
+                    or decorator_lower.startswith("compute_")
+                    or decorator_lower == "compute"
+                    or decorator_lower == "compute_handler"
+                ):
+                    return EnumNodeArchetype.COMPUTE
+
+        return None
+
+    def _get_name_from_expr(self, expr: ast.expr) -> str | None:
+        """Extract a name string from an AST expression.
+
+        Handles:
+            - Name nodes: x -> "x"
+            - Attribute nodes: a.b.c -> "a.b.c"
+
+        Args:
+            expr: The AST expression.
+
+        Returns:
+            The name as a string, or None if cannot be extracted.
+        """
+        if isinstance(expr, ast.Name):
+            return expr.id
+        if isinstance(expr, ast.Attribute):
+            base = self._get_name_from_expr(expr.value)
+            if base is not None:
+                return f"{base}.{expr.attr}"
+            return expr.attr
+        return None

omnibase_infra/validation/models/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validation models package."""
+
+from omnibase_infra.validation.models.model_contract_lint_result import (
+    ModelContractLintResult,
+)
+from omnibase_infra.validation.models.model_contract_violation import (
+    ModelContractViolation,
+)
+
+__all__: list[str] = [
+    "ModelContractLintResult",
+    "ModelContractViolation",
+]

omnibase_infra/validation/models/model_contract_lint_result.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for contract linting results."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.validation.enums.enum_contract_violation_severity import (
+    EnumContractViolationSeverity,
+)
+from omnibase_infra.validation.models.model_contract_violation import (
+    ModelContractViolation,
+)
+
+if TYPE_CHECKING:
+    from omnibase_infra.models.errors import ModelHandlerValidationError
+
+
+class ModelContractLintResult(BaseModel):
+    """Result of linting one or more contract files."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    is_valid: bool = Field(description="True if no ERROR-level violations found")
+    violations: list[ModelContractViolation] = Field(
+        default_factory=list,
+        description="All violations found during linting",
+    )
+    files_checked: int = Field(
+        default=0, description="Number of contract files checked"
+    )
+    files_valid: int = Field(
+        default=0, description="Number of contract files with no errors"
+    )
+    files_with_errors: int = Field(
+        default=0, description="Number of contract files with errors"
+    )
+
+    @property
+    def error_count(self) -> int:
+        """Count of ERROR-level violations."""
+        return sum(
+            1
+            for v in self.violations
+            if v.severity == EnumContractViolationSeverity.ERROR
+        )
+
+    @property
+    def warning_count(self) -> int:
+        """Count of WARNING-level violations."""
+        return sum(
+            1
+            for v in self.violations
+            if v.severity == EnumContractViolationSeverity.WARNING
+        )
+
+    def __str__(self) -> str:
+        """Format result summary as human-readable string."""
+        status = "PASS" if self.is_valid else "FAIL"
+        summary = f"Contract Lint: {status} ({self.files_checked} files, {self.error_count} errors, {self.warning_count} warnings)"
+        return summary
+
+    def to_handler_errors(
+        self,
+        correlation_id: UUID | None = None,
+    ) -> list[ModelHandlerValidationError]:
+        """Convert all violations to structured handler validation errors.
+
+        Transforms all ModelContractViolation instances into ModelHandlerValidationError
+        instances with appropriate rule IDs, handler identities, and remediation hints.
+        This enables integration with the structured validation and error reporting system.
+
+        Args:
+            correlation_id: Optional correlation ID to apply to all errors.
+
+        Returns:
+            List of ModelHandlerValidationError instances.
+
+        Example:
+            >>> linter = ContractLinter()
+            >>> result = linter.lint_file(Path("contract.yaml"))
+            >>> errors = result.to_handler_errors()
+            >>> for error in errors:
+            ...     logger.error(error.format_for_logging())
+        """
+        # Late import to avoid circular dependency
+        from omnibase_infra.validation.linter_contract import (
+            convert_violation_to_handler_error,
+        )
+
+        return [
+            convert_violation_to_handler_error(violation, correlation_id)
+            for violation in self.violations
+        ]

omnibase_infra/validation/models/model_contract_violation.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for a single contract validation violation."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.validation.enums.enum_contract_violation_severity import (
+    EnumContractViolationSeverity,
+)
+
+
+class ModelContractViolation(BaseModel):
+    """A single contract validation violation."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    file_path: str = Field(description="Path to the contract file")
+    field_path: str = Field(
+        description="JSON path to the violating field (e.g., 'input_model.module')"
+    )
+    message: str = Field(description="Human-readable violation description")
+    severity: EnumContractViolationSeverity = Field(
+        default=EnumContractViolationSeverity.ERROR,
+        description="Violation severity level",
+    )
+    suggestion: str | None = Field(
+        default=None,
+        description="Suggested fix for the violation",
+    )
+
+    def __str__(self) -> str:
+        """Format violation as human-readable string."""
+        prefix = f"[{self.severity.value.upper()}]"
+        location = f"{self.file_path}:{self.field_path}"
+        msg = f"{prefix} {location}: {self.message}"
+        if self.suggestion:
+            msg += f" (suggestion: {self.suggestion})"
+        return msg