specfact-cli 0.6.3__py3-none-any.whl

specfact_cli/utils/yaml_utils.py

@@ -0,0 +1,200 @@
+"""
+YAML utilities.
+
+This module provides helpers for YAML parsing and serialization.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+from ruamel.yaml import YAML
+
+
+class YAMLUtils:
+    """Helper class for YAML operations."""
+
+    @beartype
+    @require(lambda indent_mapping: indent_mapping > 0, "Indent mapping must be positive")
+    @require(lambda indent_sequence: indent_sequence > 0, "Indent sequence must be positive")
+    def __init__(self, preserve_quotes: bool = True, indent_mapping: int = 2, indent_sequence: int = 2) -> None:
+        """
+        Initialize YAML utilities.
+
+        Args:
+            preserve_quotes: Whether to preserve quotes in strings
+            indent_mapping: Indentation for mappings (must be > 0)
+            indent_sequence: Indentation for sequences (must be > 0)
+        """
+        self.yaml = YAML()
+        self.yaml.preserve_quotes = preserve_quotes
+        self.yaml.indent(mapping=indent_mapping, sequence=indent_sequence)
+        self.yaml.default_flow_style = False
+
+    @beartype
+    @require(lambda file_path: isinstance(file_path, (Path, str)), "File path must be Path or str")
+    @ensure(lambda result: result is not None, "Must return parsed content")
+    def load(self, file_path: Path | str) -> Any:
+        """
+        Load YAML from file.
+
+        Args:
+            file_path: Path to YAML file (must exist)
+
+        Returns:
+            Parsed YAML content
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"YAML file not found: {file_path}")
+
+        with open(file_path, encoding="utf-8") as f:
+            return self.yaml.load(f)
+
+    @beartype
+    @require(lambda yaml_string: isinstance(yaml_string, str), "YAML string must be str")
+    @ensure(lambda result: result is not None, "Must return parsed content")
+    def load_string(self, yaml_string: str) -> Any:
+        """
+        Load YAML from string.
+
+        Args:
+            yaml_string: YAML content as string
+
+        Returns:
+            Parsed YAML content
+        """
+        return self.yaml.load(yaml_string)
+
+    @beartype
+    @require(lambda file_path: isinstance(file_path, (Path, str)), "File path must be Path or str")
+    def dump(self, data: Any, file_path: Path | str) -> None:
+        """
+        Dump data to YAML file.
+
+        Args:
+            data: Data to serialize
+            file_path: Output file path
+        """
+        file_path = Path(file_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(file_path, "w", encoding="utf-8") as f:
+            self.yaml.dump(data, f)
+
+    @beartype
+    @ensure(lambda result: isinstance(result, str), "Must return string")
+    def dump_string(self, data: Any) -> str:
+        """
+        Dump data to YAML string.
+
+        Args:
+            data: Data to serialize
+
+        Returns:
+            YAML string
+        """
+        from io import StringIO
+
+        stream = StringIO()
+        self.yaml.dump(data, stream)
+        return stream.getvalue()
+
+    @beartype
+    @require(lambda base: isinstance(base, dict), "Base must be dictionary")
+    @require(lambda overlay: isinstance(overlay, dict), "Overlay must be dictionary")
+    @ensure(lambda result: isinstance(result, dict), "Must return dictionary")
+    def merge_yaml(self, base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+        """
+        Deep merge two YAML dictionaries.
+
+        Args:
+            base: Base dictionary
+            overlay: Overlay dictionary (takes precedence)
+
+        Returns:
+            Merged dictionary
+        """
+        result = base.copy()
+
+        for key, value in overlay.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self.merge_yaml(result[key], value)
+            else:
+                result[key] = value
+
+        return result
+
+
+# Convenience functions for quick operations
+
+
+@beartype
+@require(lambda file_path: isinstance(file_path, (Path, str)), "File path must be Path or str")
+@ensure(lambda result: result is not None, "Must return parsed content")
+def load_yaml(file_path: Path | str) -> Any:
+    """
+    Load YAML from file (convenience function).
+
+    Args:
+        file_path: Path to YAML file
+
+    Returns:
+        Parsed YAML content
+    """
+    utils = YAMLUtils()
+    return utils.load(file_path)
+
+
+@beartype
+@require(lambda file_path: isinstance(file_path, (Path, str)), "File path must be Path or str")
+def dump_yaml(data: Any, file_path: Path | str) -> None:
+    """
+    Dump data to YAML file (convenience function).
+
+    Args:
+        data: Data to serialize
+        file_path: Output file path
+    """
+    utils = YAMLUtils()
+    utils.dump(data, file_path)
+
+
+@beartype
+@ensure(lambda result: isinstance(result, str), "Must return string")
+def yaml_to_string(data: Any) -> str:
+    """
+    Convert data to YAML string (convenience function).
+
+    Args:
+        data: Data to serialize
+
+    Returns:
+        YAML string
+    """
+    utils = YAMLUtils()
+    return utils.dump_string(data)
+
+
+@beartype
+@require(lambda yaml_string: isinstance(yaml_string, str), "YAML string must be str")
+@ensure(lambda result: result is not None, "Must return parsed content")
+def string_to_yaml(yaml_string: str) -> Any:
+    """
+    Parse YAML string (convenience function).
+
+    Args:
+        yaml_string: YAML content as string
+
+    Returns:
+        Parsed YAML content
+    """
+    utils = YAMLUtils()
+    return utils.load_string(yaml_string)

specfact_cli/validators/__init__.py

@@ -0,0 +1,20 @@
+"""
+SpecFact CLI validators.
+
+This package contains validation logic for schemas, contracts,
+protocols, and plans.
+"""
+
+from specfact_cli.validators.fsm import FSMValidator
+from specfact_cli.validators.repro_checker import ReproChecker, ReproReport
+from specfact_cli.validators.schema import SchemaValidator, validate_plan_bundle, validate_protocol
+
+
+__all__ = [
+    "FSMValidator",
+    "ReproChecker",
+    "ReproReport",
+    "SchemaValidator",
+    "validate_plan_bundle",
+    "validate_protocol",
+]

specfact_cli/validators/fsm.py

@@ -0,0 +1,262 @@
+"""
+FSM (Finite State Machine) validation module.
+
+This module provides validators for state machine protocols and transitions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import networkx as nx
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.models.deviation import Deviation, DeviationSeverity, DeviationType, ValidationReport
+from specfact_cli.models.protocol import Protocol
+from specfact_cli.utils.yaml_utils import load_yaml
+
+
+class FSMValidator:
+    """FSM validator for protocol validation."""
+
+    @beartype
+    @require(
+        lambda protocol, protocol_path: protocol is not None or protocol_path is not None,
+        "Either protocol or protocol_path must be provided",
+    )
+    @require(
+        lambda protocol_path: protocol_path is None or protocol_path.exists(), "Protocol path must exist if provided"
+    )
+    def __init__(
+        self,
+        protocol: Protocol | None = None,
+        protocol_path: Path | None = None,
+        guard_functions: dict | None = None,
+    ) -> None:
+        """
+        Initialize FSM validator.
+
+        Args:
+            protocol: Protocol model to validate
+            protocol_path: Path to protocol YAML file (must exist if provided)
+            guard_functions: Optional dict of guard function implementations
+
+        Raises:
+            ValueError: If neither protocol nor protocol_path is provided
+        """
+
+        if protocol is None:
+            # Load protocol from file
+            data = load_yaml(protocol_path)  # type: ignore
+            self.protocol = Protocol(**data)
+        else:
+            self.protocol = protocol
+
+        self.guard_functions = guard_functions if guard_functions is not None else {}
+        self.graph = self._build_graph()
+
+    def _build_graph(self) -> nx.DiGraph:
+        """
+        Build directed graph from protocol transitions.
+
+        Returns:
+            NetworkX directed graph
+        """
+        graph = nx.DiGraph()
+
+        # Add all states as nodes
+        for state in self.protocol.states:
+            graph.add_node(state)
+
+        # Add transitions as edges
+        for transition in self.protocol.transitions:
+            graph.add_edge(
+                transition.from_state,
+                transition.to_state,
+                event=transition.on_event,
+                guard=transition.guard,
+            )
+
+        return graph
+
+    @beartype
+    @ensure(lambda result: isinstance(result, ValidationReport), "Must return ValidationReport")
+    def validate(self) -> ValidationReport:
+        """
+        Validate the FSM protocol.
+
+        Returns:
+            Validation report with any deviations found
+        """
+        report = ValidationReport()
+
+        # Check 1: Start state exists
+        if self.protocol.start not in self.protocol.states:
+            report.add_deviation(
+                Deviation(
+                    type=DeviationType.FSM_MISMATCH,
+                    severity=DeviationSeverity.HIGH,
+                    description=f"Start state '{self.protocol.start}' not in states list",
+                    location="protocol.start",
+                    fix_hint=f"Add '{self.protocol.start}' to states list",
+                )
+            )
+
+        # Check 2: All transition states exist
+        for transition in self.protocol.transitions:
+            if transition.from_state not in self.protocol.states:
+                report.add_deviation(
+                    Deviation(
+                        type=DeviationType.FSM_MISMATCH,
+                        severity=DeviationSeverity.HIGH,
+                        description=f"Transition from unknown state: '{transition.from_state}'",
+                        location=f"transition[{transition.from_state} → {transition.to_state}]",
+                        fix_hint=f"Add '{transition.from_state}' to states list",
+                    )
+                )
+
+            if transition.to_state not in self.protocol.states:
+                report.add_deviation(
+                    Deviation(
+                        type=DeviationType.FSM_MISMATCH,
+                        severity=DeviationSeverity.HIGH,
+                        description=f"Transition to unknown state: '{transition.to_state}'",
+                        location=f"transition[{transition.from_state} → {transition.to_state}]",
+                        fix_hint=f"Add '{transition.to_state}' to states list",
+                    )
+                )
+
+        # Check 3: Reachability - all states reachable from start
+        if report.passed:  # Only if no critical errors so far
+            reachable = nx.descendants(self.graph, self.protocol.start)
+            reachable.add(self.protocol.start)
+
+            unreachable = set(self.protocol.states) - reachable
+            if unreachable:
+                for state in unreachable:
+                    report.add_deviation(
+                        Deviation(
+                            type=DeviationType.FSM_MISMATCH,
+                            severity=DeviationSeverity.MEDIUM,
+                            description=f"State '{state}' is not reachable from start state",
+                            location=f"state[{state}]",
+                            fix_hint=f"Add transition path from '{self.protocol.start}' to '{state}'",
+                        )
+                    )
+
+        # Check 4: Guards are defined
+        for transition in self.protocol.transitions:
+            if (
+                transition.guard
+                and transition.guard not in self.protocol.guards
+                and transition.guard not in self.guard_functions
+            ):
+                # LOW severity if guard functions can be provided externally
+                report.add_deviation(
+                    Deviation(
+                        type=DeviationType.FSM_MISMATCH,
+                        severity=DeviationSeverity.LOW,
+                        description=f"Guard '{transition.guard}' not defined in protocol or guard_functions",
+                        location=f"transition[{transition.from_state} → {transition.to_state}]",
+                        fix_hint=f"Add guard definition for '{transition.guard}' in protocol.guards or pass guard_functions",
+                    )
+                )
+
+        # Check 5: Detect cycles (informational)
+        try:
+            cycles = list(nx.simple_cycles(self.graph))
+            if cycles:
+                for cycle in cycles:
+                    report.add_deviation(
+                        Deviation(
+                            type=DeviationType.FSM_MISMATCH,
+                            severity=DeviationSeverity.LOW,
+                            description=f"Cycle detected: {' → '.join(cycle)}",
+                            location="protocol.transitions",
+                            fix_hint="Cycles may be intentional for workflows, verify this is expected",
+                        )
+                    )
+        except nx.NetworkXNoCycle:
+            pass  # No cycles is fine
+
+        return report
+
+    @beartype
+    @require(lambda from_state: isinstance(from_state, str) and len(from_state) > 0, "State must be non-empty string")
+    @ensure(lambda result: isinstance(result, set), "Must return set")
+    @ensure(lambda result: all(isinstance(s, str) for s in result), "All items must be strings")
+    def get_reachable_states(self, from_state: str) -> set[str]:
+        """
+        Get all states reachable from given state.
+
+        Args:
+            from_state: Starting state
+
+        Returns:
+            Set of reachable state names
+        """
+        if from_state not in self.protocol.states:
+            return set()
+
+        reachable = nx.descendants(self.graph, from_state)
+        reachable.add(from_state)
+        return reachable
+
+    @beartype
+    @require(lambda state: isinstance(state, str) and len(state) > 0, "State must be non-empty string")
+    @ensure(lambda result: isinstance(result, list), "Must return list")
+    @ensure(lambda result: all(isinstance(t, dict) for t in result), "All items must be dictionaries")
+    def get_transitions_from(self, state: str) -> list[dict]:
+        """
+        Get all transitions from given state.
+
+        Args:
+            state: State name
+
+        Returns:
+            List of transition dictionaries
+        """
+        if state not in self.protocol.states:
+            return []
+
+        transitions = []
+        for successor in self.graph.successors(state):
+            edge_data = self.graph.get_edge_data(state, successor)
+            transitions.append(
+                {
+                    "from_state": state,
+                    "to_state": successor,
+                    "event": edge_data.get("event"),
+                    "guard": edge_data.get("guard"),
+                }
+            )
+
+        return transitions
+
+    @beartype
+    @require(
+        lambda from_state: isinstance(from_state, str) and len(from_state) > 0, "From state must be non-empty string"
+    )
+    @require(lambda on_event: isinstance(on_event, str) and len(on_event) > 0, "Event must be non-empty string")
+    @require(lambda to_state: isinstance(to_state, str) and len(to_state) > 0, "To state must be non-empty string")
+    @ensure(lambda result: isinstance(result, bool), "Must return boolean")
+    def is_valid_transition(self, from_state: str, on_event: str, to_state: str) -> bool:
+        """
+        Check if transition is valid.
+
+        Args:
+            from_state: Source state
+            on_event: Event that triggers the transition
+            to_state: Target state
+
+        Returns:
+            True if transition exists with the given event
+        """
+        # Check if edge exists
+        if not self.graph.has_edge(from_state, to_state):
+            return False
+
+        # Check if the event matches
+        edge_data = self.graph.get_edge_data(from_state, to_state)
+        return edge_data.get("event") == on_event