omnibase_infra 0.2.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

omnibase_infra/services/contract_publisher/sources/model_discovered.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovered Contract Model.
+
+Internal model for contracts discovered by sources. Using a Pydantic model
+instead of tuples prevents position bugs and makes error reporting cleaner.
+
+This model is populated in stages:
+1. Discovery: origin, ref, text are set
+2. Parsing: handler_id is extracted from YAML
+3. Hashing: content_hash (SHA-256) is computed
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+logger = logging.getLogger(__name__)
+
+
+class ModelDiscoveredContract(BaseModel):
+    """Internal model for discovered contracts.
+
+    Represents a contract discovered by a source (filesystem or package)
+    before validation and publishing. This model prevents tuple position
+    bugs and provides a clear structure for error reporting.
+
+    Population Stages:
+        1. Discovery: origin, ref, text are set by the source
+        2. Parsing: handler_id is extracted from YAML (may fail)
+        3. Hashing: content_hash is computed for dedup/conflict detection
+
+    Attributes:
+        origin: Source type that discovered this contract
+        ref: Path (filesystem) or resource path (package)
+        text: Raw YAML content
+        handler_id: Extracted from contract YAML, None if parsing failed
+        content_hash: SHA-256 hash of text, for dedup/conflict detection
+
+    Example:
+        >>> contract = ModelDiscoveredContract(
+        ...     origin="filesystem",
+        ...     ref=Path("/app/contracts/foo/contract.yaml"),
+        ...     text="handler_id: foo.handler\\n...",
+        ... )
+        >>> contract = contract.with_parsed_data(
+        ...     handler_id="foo.handler",
+        ... )
+        >>> contract = contract.with_content_hash()
+
+    .. versionadded:: 0.3.0
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    origin: Literal["filesystem", "package"] = Field(
+        description="Source type that discovered this contract"
+    )
+    ref: Path | str = Field(description="Path (filesystem) or resource path (package)")
+    text: str = Field(description="Raw YAML content")
+    handler_id: str | None = Field(
+        default=None,
+        description="Handler ID extracted from YAML, None if parsing failed",
+    )
+    content_hash: str | None = Field(
+        default=None,
+        description="SHA-256 hash of text for dedup/conflict detection",
+    )
+
+    def with_parsed_data(self, handler_id: str) -> ModelDiscoveredContract:
+        """Return new instance with handler_id populated.
+
+        Args:
+            handler_id: Handler ID extracted from contract YAML
+
+        Returns:
+            New instance with handler_id set
+        """
+        return self.model_copy(update={"handler_id": handler_id})
+
+    def extract_handler_id(self) -> ModelDiscoveredContract:
+        """Extract handler_id from YAML and return new instance with it populated.
+
+        Parses the YAML text content to extract handler_id early, enabling
+        proper deterministic sorting and deduplication before validation.
+
+        Returns:
+            New instance with handler_id if extraction succeeded,
+            self unchanged if parsing failed (will fail validation later).
+        """
+        # Skip if handler_id already extracted
+        if self.handler_id is not None:
+            return self
+
+        try:
+            data = yaml.safe_load(self.text)
+            if isinstance(data, dict) and "handler_id" in data:
+                handler_id = data["handler_id"]
+                if isinstance(handler_id, str) and handler_id:
+                    return self.with_parsed_data(handler_id=handler_id)
+        except yaml.YAMLError:
+            # YAML parse errors will be caught during validation
+            logger.debug(
+                "Failed to extract handler_id from %s:%s (YAML parse error)",
+                self.origin,
+                self.ref,
+            )
+        return self
+
+    def with_content_hash(self) -> ModelDiscoveredContract:
+        """Return new instance with content_hash computed.
+
+        Computes SHA-256 hash of the text content for use in
+        deduplication and conflict detection.
+
+        Returns:
+            New instance with content_hash set
+        """
+        hash_value = hashlib.sha256(self.text.encode("utf-8")).hexdigest()
+        return self.model_copy(update={"content_hash": hash_value})
+
+    @staticmethod
+    def compute_content_hash(text: str) -> str:
+        """Compute SHA-256 hash of text content.
+
+        Args:
+            text: Raw YAML content
+
+        Returns:
+            Hexadecimal SHA-256 hash string
+        """
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def sort_key(self) -> tuple[str, str, str]:
+        """Return sort key for deterministic ordering.
+
+        Sorts by (handler_id, origin, ref) to ensure consistent
+        ordering across runs regardless of filesystem order.
+
+        Returns:
+            Tuple for sorting: (handler_id or "", origin, str(ref))
+        """
+        return (self.handler_id or "", self.origin, str(self.ref))
+
+
+__all__ = ["ModelDiscoveredContract"]

omnibase_infra/services/contract_publisher/sources/protocol.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Publisher Source Protocol.
+
+Defines the protocol interface for contract sources. Sources are responsible
+for discovering contracts from their respective backends (filesystem, package
+resources, etc.).
+
+This protocol is distinct from ProtocolContractSource (used for handler
+discovery) because it returns raw contracts for publishing rather than
+parsed handler descriptors.
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from omnibase_infra.services.contract_publisher.sources.model_discovered import (
+    ModelDiscoveredContract,
+)
+
+
+@runtime_checkable
+class ProtocolContractPublisherSource(Protocol):
+    """Protocol for contract publisher sources.
+
+    Defines the interface for sources that discover contracts for bulk
+    publishing. Implementations must provide discovery of contracts
+    from their specific backend.
+
+    Methods:
+        source_type: Returns identifier for the source type
+        source_description: Returns human-readable description
+        discover_contracts: Discovers all contracts from the source
+
+    Implementations:
+        - SourceContractFilesystem: Discovers from directory tree
+        - SourceContractPackage: Discovers from package resources
+        - SourceContractComposite: Merges multiple sources
+
+    Example:
+        >>> class MySource:
+        ...     @property
+        ...     def source_type(self) -> str:
+        ...         return "custom"
+        ...
+        ...     @property
+        ...     def source_description(self) -> str:
+        ...         return "custom: my-source"
+        ...
+        ...     async def discover_contracts(self) -> list[ModelDiscoveredContract]:
+        ...         return []
+
+    .. versionadded:: 0.3.0
+    """
+
+    @property
+    def source_type(self) -> str:
+        """Return source type identifier.
+
+        Used for logging and statistics. Should be a short, lowercase
+        identifier like "filesystem" or "package".
+
+        Returns:
+            Source type identifier string
+        """
+        ...
+
+    @property
+    def source_description(self) -> str:
+        """Return human-readable source description.
+
+        Used for error messages and logging. Should include the source
+        type and any relevant configuration details.
+
+        Returns:
+            Human-readable description (e.g., "filesystem: /app/contracts")
+        """
+        ...
+
+    async def discover_contracts(self) -> list[ModelDiscoveredContract]:
+        """Discover all contracts from this source.
+
+        Searches the source backend for contract.yaml files and returns
+        them as ModelDiscoveredContract instances. The handler_id and
+        content_hash fields are NOT populated at this stage - they are
+        filled in during validation.
+
+        Returns:
+            List of discovered contracts with origin, ref, and text populated
+
+        Raises:
+            OSError: If the source location is inaccessible
+        """
+        ...
+
+
+__all__ = ["ProtocolContractPublisherSource"]

omnibase_infra/services/contract_publisher/sources/source_composite.py

@@ -0,0 +1,309 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Composite Contract Source.
+
+Merges contracts from filesystem and package sources with deterministic
+conflict detection. Both sources are discovered, and contracts are merged
+by handler_id.
+
+Merge Rules:
+    1. Discover from both configured sources
+    2. For each contract, parse handler_id and compute content_hash
+    3. If same handler_id appears in both sources:
+       - Same hash → dedup silently (use first occurrence)
+       - Different hash → ModelContractError("duplicate_conflict")
+
+Ordering:
+    Results are sorted by (handler_id, origin, ref) for deterministic
+    ordering across runs regardless of filesystem order.
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from omnibase_infra.services.contract_publisher.models import ModelContractError
+from omnibase_infra.services.contract_publisher.sources.model_discovered import (
+    ModelDiscoveredContract,
+)
+
+if TYPE_CHECKING:
+    from omnibase_infra.services.contract_publisher.sources.source_filesystem import (
+        SourceContractFilesystem,
+    )
+    from omnibase_infra.services.contract_publisher.sources.source_package import (
+        SourceContractPackage,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class SourceContractComposite:
+    """Composite source that merges filesystem and package sources.
+
+    Discovers contracts from both configured sources and merges them
+    with deterministic conflict detection. At least one source must
+    be configured.
+
+    Conflict Detection:
+        When the same handler_id appears in both sources:
+        - If content hash matches: Deduplicate silently (keep first)
+        - If content hash differs: Generate ModelContractError
+
+    Ordering:
+        All results are sorted by (handler_id, origin, ref) to ensure
+        deterministic ordering across runs.
+
+    Attributes:
+        _filesystem_source: Optional filesystem source
+        _package_source: Optional package source
+        _last_merge_errors: Errors from last discover_contracts call
+
+    Example:
+        >>> filesystem = SourceContractFilesystem(Path("/app/contracts"))
+        >>> package = SourceContractPackage("myapp.contracts")
+        >>> composite = SourceContractComposite(filesystem, package)
+        >>> contracts = await composite.discover_contracts()
+        >>> errors = composite.get_merge_errors()
+
+    .. versionadded:: 0.3.0
+    """
+
+    __slots__ = (
+        "_filesystem_source",
+        "_last_dedup_count",
+        "_last_merge_errors",
+        "_package_source",
+    )
+
+    def __init__(
+        self,
+        filesystem_source: SourceContractFilesystem | None = None,
+        package_source: SourceContractPackage | None = None,
+    ) -> None:
+        """Initialize composite source.
+
+        Args:
+            filesystem_source: Optional filesystem source
+            package_source: Optional package source
+
+        Raises:
+            ValueError: If neither source is configured
+        """
+        if not filesystem_source and not package_source:
+            raise ValueError(
+                "Composite source requires at least one source "
+                "(filesystem_source or package_source)"
+            )
+
+        self._filesystem_source = filesystem_source
+        self._package_source = package_source
+        self._last_merge_errors: list[ModelContractError] = []
+        self._last_dedup_count: int = 0
+
+    @property
+    def source_type(self) -> str:
+        """Return source type identifier.
+
+        Returns:
+            "composite"
+        """
+        return "composite"
+
+    @property
+    def source_description(self) -> str:
+        """Return human-readable source description.
+
+        Returns:
+            Description including configured sources
+        """
+        parts: list[str] = ["composite:"]
+        if self._filesystem_source:
+            parts.append(f"filesystem={self._filesystem_source.root}")
+        if self._package_source:
+            parts.append(f"package={self._package_source.package_module}")
+        return " ".join(parts)
+
+    @property
+    def filesystem_source(self) -> SourceContractFilesystem | None:
+        """Return the filesystem source if configured."""
+        return self._filesystem_source
+
+    @property
+    def package_source(self) -> SourceContractPackage | None:
+        """Return the package source if configured."""
+        return self._package_source
+
+    async def discover_contracts(self) -> list[ModelDiscoveredContract]:
+        """Discover contracts from all configured sources and merge.
+
+        Discovers from both sources (if configured), then merges with
+        conflict detection. Conflict errors are stored internally and
+        can be retrieved via get_merge_errors().
+
+        Returns:
+            Deduplicated and sorted contracts (excludes conflicts)
+
+        Note:
+            The returned contracts have handler_id and content_hash populated.
+            Call get_merge_errors() after discovery to get conflict errors.
+            Call get_dedup_count() after discovery to get deduplication count.
+        """
+        all_contracts: list[ModelDiscoveredContract] = []
+
+        # Clear previous state
+        self._last_merge_errors = []
+        self._last_dedup_count = 0
+
+        # Discover from filesystem source
+        if self._filesystem_source:
+            filesystem_contracts = await self._filesystem_source.discover_contracts()
+            all_contracts.extend(filesystem_contracts)
+            logger.debug(
+                "Composite: discovered %d contracts from filesystem",
+                len(filesystem_contracts),
+            )
+
+        # Discover from package source
+        if self._package_source:
+            package_contracts = await self._package_source.discover_contracts()
+            all_contracts.extend(package_contracts)
+            logger.debug(
+                "Composite: discovered %d contracts from package",
+                len(package_contracts),
+            )
+
+        # Extract handler_ids BEFORE merging (enables proper dedup/conflict detection)
+        all_contracts = [c.extract_handler_id() for c in all_contracts]
+
+        # Compute content hashes for all contracts
+        all_contracts = [c.with_content_hash() for c in all_contracts]
+
+        # Merge with conflict detection (now handler_id is populated)
+        merged, conflicts, dedup_count = self._merge_contracts(all_contracts)
+
+        # Store results for later retrieval
+        self._last_merge_errors = conflicts
+        self._last_dedup_count = dedup_count
+
+        # Sort merged contracts for deterministic ordering
+        merged.sort(key=lambda c: c.sort_key())
+
+        logger.info(
+            "Composite discovery complete: %d merged, %d conflicts, %d deduped, %d total",
+            len(merged),
+            len(conflicts),
+            dedup_count,
+            len(all_contracts),
+        )
+
+        return merged
+
+    def get_merge_errors(self) -> list[ModelContractError]:
+        """Get merge errors from last discover_contracts call.
+
+        Returns:
+            List of ModelContractError from the last merge operation.
+            Empty if discover_contracts hasn't been called or no conflicts.
+        """
+        return self._last_merge_errors.copy()
+
+    def get_dedup_count(self) -> int:
+        """Get deduplication count from last discover_contracts call.
+
+        Returns the count of contracts that were deduplicated (same handler_id
+        and same content hash). This does NOT include conflicts (same handler_id
+        but different content hash) - those are tracked via get_merge_errors().
+
+        Returns:
+            Number of deduplicated contracts (0 if discover_contracts hasn't
+            been called or no duplicates found).
+        """
+        return self._last_dedup_count
+
+    def _merge_contracts(
+        self,
+        contracts: list[ModelDiscoveredContract],
+    ) -> tuple[list[ModelDiscoveredContract], list[ModelContractError], int]:
+        """Merge contracts with conflict detection.
+
+        Groups contracts by handler_id (extracted from YAML), then:
+        - Single occurrence: Keep as-is
+        - Multiple with same hash: Deduplicate (keep first), increment dedup_count
+        - Multiple with different hash: Generate conflict error
+
+        Note: Contracts without handler_id (failed parsing) are kept
+        as-is and will generate validation errors later.
+
+        Args:
+            contracts: List of contracts with handler_id and content_hash computed
+
+        Returns:
+            Tuple of (merged_contracts, conflict_errors, dedup_count)
+        """
+        merged: list[ModelDiscoveredContract] = []
+        conflicts: list[ModelContractError] = []
+        dedup_count = 0
+
+        # Track seen handler_ids with their hash
+        seen: dict[
+            str, tuple[ModelDiscoveredContract, str]
+        ] = {}  # handler_id -> (contract, hash)
+
+        for contract in contracts:
+            handler_id = contract.handler_id
+            content_hash = contract.content_hash or ""
+
+            # If no handler_id, keep contract (will fail validation later)
+            if not handler_id:
+                merged.append(contract)
+                continue
+
+            if handler_id not in seen:
+                # First occurrence
+                seen[handler_id] = (contract, content_hash)
+                merged.append(contract)
+            else:
+                # Duplicate handler_id
+                existing_contract, existing_hash = seen[handler_id]
+
+                if content_hash == existing_hash:
+                    # Same hash - dedup silently, increment counter
+                    dedup_count += 1
+                    logger.debug(
+                        "Deduplicating contract %s (same hash): %s vs %s",
+                        handler_id,
+                        contract.ref,
+                        existing_contract.ref,
+                    )
+                else:
+                    # Different hash - conflict error
+                    error = ModelContractError(
+                        contract_path=str(contract.ref),
+                        handler_id=handler_id,
+                        error_type="duplicate_conflict",
+                        message=(
+                            f"Duplicate handler_id '{handler_id}' with different content: "
+                            f"found in {contract.origin}:{contract.ref} "
+                            f"(hash: {content_hash[:8]}...) but already exists in "
+                            f"{existing_contract.origin}:{existing_contract.ref} "
+                            f"(hash: {existing_hash[:8]}...)"
+                        ),
+                    )
+                    conflicts.append(error)
+
+                    logger.warning(
+                        "Conflict detected for handler_id %s: %s vs %s",
+                        handler_id,
+                        contract.ref,
+                        existing_contract.ref,
+                    )
+
+        return merged, conflicts, dedup_count
+
+
+__all__ = ["SourceContractComposite"]