omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/nodes/architecture_validator/contract_architecture_validator.yaml

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeArchitectureValidatorCompute
+#
+# This contract defines the interface for the Architecture Validator compute node,
+# which validates architecture compliance against forbidden patterns at startup
+# and during runtime.
+# Contract identifiers
+name: "architecture_validator"
+contract_name: "architecture_validator"
+node_name: "architecture_validator"
+# Version (semantic versioning)
+version:
+  major: 1
+  minor: 0
+  patch: 0
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 0
+  minor: 1
+  patch: 0
+# Node type
+node_type: "COMPUTE_GENERIC"
+# Description
+description: >
+  Compute node for architecture validation. Validates ONEX architecture compliance by checking nodes and handlers against forbidden patterns defined in architecture rules. This node performs pure transformations with no side effects, making it suitable for both startup validation and runtime checks.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelArchitectureValidationRequest"
+  module: "omnibase_infra.nodes.architecture_validator.models"
+  description: "Request containing nodes, handlers, and rules to validate."
+output_model:
+  name: "ModelArchitectureValidationResult"
+  module: "omnibase_infra.nodes.architecture_validator.models"
+  description: "Result containing validation status, violations, and statistics."
+# Runtime configuration
+runtime:
+  # Can be called directly at startup (pre-runtime)
+  supports_direct_call: true
+  # Can be invoked via orchestrator during runtime
+  supports_event_driven: true
+  # Pure transformation, no side effects
+  side_effects: false
+  # Validation should be fast
+  timeout_ms: 5000
+  # Deterministic output for same input
+  deterministic: true
+# Validation rules supported by this node
+# Note: OMN-1099 will define the full rule registry
+validation_rules:
+  supported_rules:
+    - rule_id: "NO_HANDLER_PUBLISHING"
+      description: "Handlers must not have direct event bus access"
+      severity: "error"
+    - rule_id: "PURE_REDUCERS"
+      description: "Reducers must not perform side effects or I/O"
+      severity: "error"
+    - rule_id: "NO_FSM_IN_ORCHESTRATORS"
+      description: "Orchestrators must not own FSM state"
+      severity: "error"
+    - rule_id: "NO_WORKFLOW_IN_REDUCERS"
+      description: "Reducers must not coordinate workflows"
+      severity: "error"
+    - rule_id: "NO_DIRECT_HANDLER_DISPATCH"
+      description: "Handlers must not dispatch to other handlers directly"
+      severity: "warning"
+    - rule_id: "NO_LOCAL_ONLY_PATHS"
+      description: "File paths must not use local-only absolute paths"
+      severity: "warning"
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "protocol_architecture_rule"
+    type: "protocol"
+    class_name: "ProtocolArchitectureRule"
+    module: "omnibase_infra.nodes.architecture_validator.protocols"
+    description: "Protocol for architecture rule implementations"
+# Capabilities provided by this node
+capabilities:
+  - name: "architecture_validation"
+    description: "Validate nodes and handlers against architecture rules"
+  - name: "rule_filtering"
+    description: "Validate against specific rules via rule_ids parameter"
+  - name: "fail_fast_mode"
+    description: "Stop validation on first violation for quick feedback"
+  - name: "violation_aggregation"
+    description: "Collect all violations with severity classification"
+# Model definitions (reference - actual models in models/ directory)
+definitions:
+  ModelArchitectureValidationRequest:
+    type: object
+    description: "Input model for architecture validation operations"
+    properties:
+      nodes:
+        type: array
+        items:
+          type: object
+        description: "Nodes to validate against architecture rules"
+      handlers:
+        type: array
+        items:
+          type: object
+        description: "Handlers to validate against architecture rules"
+      rule_ids:
+        type: array
+        items:
+          type: string
+        nullable: true
+        description: "Specific rule IDs to check. None means check all rules."
+      fail_fast:
+        type: boolean
+        default: false
+        description: "If true, stop on first violation found"
+      correlation_id:
+        type: string
+        nullable: true
+        description: "Request correlation ID for tracing"
+    required: []
+  ModelArchitectureValidationResult:
+    type: object
+    description: "Output model for architecture validation operations"
+    properties:
+      violations:
+        type: array
+        items:
+          $ref: "#/definitions/ModelArchitectureViolation"
+        description: "All violations found during validation"
+      rules_checked:
+        type: array
+        items:
+          type: string
+        description: "Rule IDs that were checked during validation"
+      nodes_checked:
+        type: integer
+        minimum: 0
+        description: "Number of nodes that were validated"
+      handlers_checked:
+        type: integer
+        minimum: 0
+        description: "Number of handlers that were validated"
+      correlation_id:
+        type: string
+        nullable: true
+        description: "Request correlation ID for tracing"
+    required:
+      - violations
+      - rules_checked
+      - nodes_checked
+      - handlers_checked
+  ModelArchitectureViolation:
+    type: object
+    description: "Details about a single architecture violation"
+    properties:
+      rule_id:
+        type: string
+        description: "ID of the violated rule (e.g., NO_HANDLER_PUBLISHING)"
+      rule_name:
+        type: string
+        description: "Human-readable name of the violated rule"
+      severity:
+        type: string
+        enum: ["error", "warning", "info"]
+        description: "Severity level of the violation"
+      target_type:
+        type: string
+        description: "Type of target that violated the rule (e.g., 'handler', 'node')"
+      target_name:
+        type: string
+        description: "Name or identifier of the violating target"
+      message:
+        type: string
+        description: "Human-readable description of the violation"
+      location:
+        type: string
+        nullable: true
+        description: "File path and line number if available"
+      suggestion:
+        type: string
+        nullable: true
+        description: "Optional suggestion for fixing the violation"
+      details:
+        type: object
+        nullable: true
+        description: "Additional context-specific details for debugging"
+    required:
+      - rule_id
+      - rule_name
+      - severity
+      - target_type
+      - target_name
+      - message
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2025-01-07"
+  tags:
+    - compute
+    - validation
+    - architecture
+    - startup
+    - compliance
+    - onex

omnibase_infra/nodes/architecture_validator/mixins/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Mixins for architecture validator rules.
+
+This module provides reusable mixins for architecture validation rules,
+enabling code reuse across multiple rule implementations.
+
+Available Mixins:
+    MixinFilePathRule: Extracts file paths from targets with graceful fallback.
+"""
+
+from omnibase_infra.nodes.architecture_validator.mixins.mixin_file_path_rule import (
+    MixinFilePathRule,
+)
+
+__all__ = ["MixinFilePathRule"]

omnibase_infra/nodes/architecture_validator/mixins/mixin_file_path_rule.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Mixin for file-path-based architecture rules.
+
+This module provides a mixin that extracts file paths from validation targets
+using explicit isinstance checks. Rules that validate file paths can inherit
+from this mixin to avoid duplicating the path extraction logic.
+
+Thread Safety:
+    MixinFilePathRule is stateless and safe for concurrent use.
+    All methods are pure functions with no side effects.
+
+Example:
+    >>> class RuleFilePath(MixinFilePathRule):
+    ...     @property
+    ...     def rule_id(self) -> str:
+    ...         return "FILE-001"
+    ...
+    ...     def check(self, target: object) -> ModelRuleCheckResult:
+    ...         file_path = self._extract_file_path(target)
+    ...         if file_path is None:
+    ...             return ModelRuleCheckResult(
+    ...                 passed=True,
+    ...                 skipped=True,
+    ...                 rule_id=self.rule_id,
+    ...                 reason="Target is not a valid file path",
+    ...             )
+    ...         # Continue with file-based validation...
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["MixinFilePathRule"]
+
+
+class MixinFilePathRule:
+    """Mixin providing file path extraction for architecture rules.
+
+    This mixin provides a standardized method for extracting file paths from
+    validation targets using explicit isinstance checks. It handles the common
+    case where a rule expects a file path but may receive other types of objects.
+
+    The extraction uses explicit type checking to ensure the target is a string
+    or Path object before processing.
+
+    Thread Safety:
+        This mixin is stateless and safe for concurrent use. The
+        ``_extract_file_path`` method is a pure function with no side effects.
+
+    Example:
+        >>> mixin = MixinFilePathRule()
+        >>> mixin._extract_file_path("/path/to/file.py")
+        '/path/to/file.py'
+        >>> mixin._extract_file_path(object())  # Returns None for non-path objects
+        >>> mixin._extract_file_path("")  # Returns None for empty strings
+    """
+
+    def _extract_file_path(self, target: object) -> str | None:
+        """Extract file path from target or return None if invalid.
+
+        Uses explicit isinstance check to validate the target is a string
+        or Path object. Returns None for:
+
+        - Non-string, non-Path objects
+        - Empty strings
+
+        Args:
+            target: Object to extract file path from. Must be a string
+                or Path object; other types return None.
+
+        Returns:
+            File path string if valid, None otherwise.
+
+        Example:
+            >>> self._extract_file_path("/path/to/file.py")
+            '/path/to/file.py'
+            >>> self._extract_file_path(Path("/path/to/file.py"))
+            '/path/to/file.py'
+            >>> self._extract_file_path(object())
+            None
+            >>> self._extract_file_path("")
+            None
+        """
+        # Only handle string or Path-like targets
+        if isinstance(target, str | Path):
+            file_path = str(target)
+            if not file_path:
+                return None
+            return file_path
+        return None

omnibase_infra/nodes/architecture_validator/models/__init__.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Models for the architecture validator nodes.
+
+This module exports all models used by both architecture validators:
+- OMN-1138: NodeArchitectureValidatorCompute (pluggable rules)
+- OMN-1099: NodeArchitectureValidator (core pattern validation)
+"""
+
+# Canonical severity enum
+from omnibase_infra.enums import EnumValidationSeverity
+
+# OMN-1138: Models for NodeArchitectureValidatorCompute
+# OMN-1099: Models for NodeArchitectureValidator
+from omnibase_infra.nodes.architecture_validator.models.model_architecture_validation_request import (
+    ModelArchitectureValidationRequest,
+)
+from omnibase_infra.nodes.architecture_validator.models.model_architecture_validation_result import (
+    ModelArchitectureValidationResult,
+)
+from omnibase_infra.nodes.architecture_validator.models.model_architecture_violation import (
+    ModelArchitectureViolation,
+)
+from omnibase_infra.nodes.architecture_validator.models.model_rule_check_result import (
+    ModelRuleCheckResult,
+)
+
+__all__ = [
+    # OMN-1138 models
+    "ModelArchitectureValidationRequest",
+    "ModelArchitectureValidationResult",
+    "ModelArchitectureViolation",
+    "ModelRuleCheckResult",
+    # Canonical severity enum (from enums/ directory)
+    "EnumValidationSeverity",
+]

omnibase_infra/nodes/architecture_validator/models/model_architecture_validation_request.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Request model for architecture validation."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelArchitectureValidationRequest(BaseModel):
+    """Request to validate architecture compliance.
+
+    Contains nodes and handlers to check against architecture rules.
+    Used as input to NodeArchitectureValidatorCompute.
+
+    Attributes:
+        nodes: Nodes to validate against architecture rules.
+        handlers: Handlers to validate against architecture rules.
+        rule_ids: Specific rule IDs to check. None means check all rules.
+        fail_fast: If True, stop on first violation found.
+        correlation_id: Correlation ID for tracing.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    nodes: tuple[object, ...] = Field(
+        default_factory=tuple,
+        description="Nodes to validate against architecture rules",
+    )
+
+    handlers: tuple[object, ...] = Field(
+        default_factory=tuple,
+        description="Handlers to validate against architecture rules",
+    )
+
+    rule_ids: tuple[str, ...] | None = Field(
+        default=None,
+        description="Specific rule IDs to check. None means check all rules.",
+    )
+
+    fail_fast: bool = Field(
+        default=False,
+        description="If True, stop on first violation found",
+    )
+
+    correlation_id: str | None = Field(
+        default=None,
+        description="Correlation ID for tracing",
+    )
+
+
+__all__ = ["ModelArchitectureValidationRequest"]