oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/{triggering → utils/triggering}/pattern.py

@@ -4,7 +4,7 @@ Provides digital pattern matching for multi-channel logic signals.
 Supports exact matches, wildcards, and edge conditions.
 
 Example:
-    >>> from oscura.triggering.pattern import PatternTrigger, find_pattern
+    >>> from oscura.utils.triggering.pattern import PatternTrigger, find_pattern
     >>> # Find pattern 1010 on 4 channels
     >>> trigger = PatternTrigger(pattern=[1, 0, 1, 0])
     >>> events = trigger.find_events(trace)
@@ -18,7 +18,7 @@ import numpy as np
 
 from oscura.core.exceptions import AnalysisError
 from oscura.core.types import DigitalTrace, WaveformTrace
-from oscura.triggering.base import (
+from oscura.utils.triggering.base import (
     Trigger,
     TriggerEvent,
     TriggerType,

oscura/{triggering → utils/triggering}/pulse.py

@@ -4,7 +4,7 @@ Provides pulse width triggering, glitch detection, and runt pulse
 detection for signal integrity analysis.
 
 Example:
-    >>> from oscura.triggering.pulse import PulseWidthTrigger, find_glitches
+    >>> from oscura.utils.triggering.pulse import PulseWidthTrigger, find_glitches
     >>> # Find pulses between 100ns and 200ns
     >>> trigger = PulseWidthTrigger(level=1.5, min_width=100e-9, max_width=200e-9)
     >>> events = trigger.find_events(trace)
@@ -18,10 +18,11 @@ from dataclasses import dataclass
 from typing import Literal
 
 import numpy as np
+from numpy.typing import NDArray
 
 from oscura.core.exceptions import AnalysisError
 from oscura.core.types import DigitalTrace, WaveformTrace
-from oscura.triggering.base import (
+from oscura.utils.triggering.base import (
     Trigger,
     TriggerEvent,
     TriggerType,
@@ -307,6 +308,101 @@ class RuntTrigger(Trigger):
         self.high_threshold = high_threshold
         self.polarity = polarity
 
+    def _get_zone(self, value: float) -> int:
+        """Get zone for a signal value.
+
+        Args:
+            value: Signal value
+
+        Returns:
+            Zone index (0=low, 1=middle, 2=high)
+        """
+        if value < self.low_threshold:
+            return 0
+        if value > self.high_threshold:
+            return 2
+        return 1
+
+    def _find_positive_runt(
+        self,
+        zones: NDArray[np.int_],
+        data: NDArray[np.float64],
+        start_idx: int,
+        sample_period: float,
+    ) -> tuple[TriggerEvent | None, int]:
+        """Find positive runt pulse starting at index.
+
+        Args:
+            zones: Zone classification array
+            data: Signal data
+            start_idx: Starting index
+            sample_period: Sample period
+
+        Returns:
+            Tuple of (event or None, next index)
+        """
+        j = start_idx + 1
+        while j < len(zones) and zones[j] == 1:
+            j += 1
+
+        if j < len(zones) and zones[j] == 0:
+            peak = float(np.max(data[start_idx : j + 1]))
+            event = TriggerEvent(
+                timestamp=start_idx * sample_period,
+                sample_index=start_idx,
+                event_type=TriggerType.RUNT,
+                level=peak,
+                duration=(j - start_idx) * sample_period,
+                data={
+                    "polarity": "positive",
+                    "expected_high": self.high_threshold,
+                    "actual_peak": peak,
+                },
+            )
+            return event, j
+
+        return None, j
+
+    def _find_negative_runt(
+        self,
+        zones: NDArray[np.int_],
+        data: NDArray[np.float64],
+        start_idx: int,
+        sample_period: float,
+    ) -> tuple[TriggerEvent | None, int]:
+        """Find negative runt pulse starting at index.
+
+        Args:
+            zones: Zone classification array
+            data: Signal data
+            start_idx: Starting index
+            sample_period: Sample period
+
+        Returns:
+            Tuple of (event or None, next index)
+        """
+        j = start_idx + 1
+        while j < len(zones) and zones[j] == 1:
+            j += 1
+
+        if j < len(zones) and zones[j] == 2:
+            trough = float(np.min(data[start_idx : j + 1]))
+            event = TriggerEvent(
+                timestamp=start_idx * sample_period,
+                sample_index=start_idx,
+                event_type=TriggerType.RUNT,
+                level=trough,
+                duration=(j - start_idx) * sample_period,
+                data={
+                    "polarity": "negative",
+                    "expected_low": self.low_threshold,
+                    "actual_trough": trough,
+                },
+            )
+            return event, j
+
+        return None, j
+
     def find_events(
         self,
         trace: WaveformTrace | DigitalTrace,
@@ -320,88 +416,33 @@ class RuntTrigger(Trigger):
             List of trigger events for each runt pulse.
         """
         if isinstance(trace, DigitalTrace):
-            # Digital traces don't have runts
             return []
 
         data = trace.data
         sample_period = trace.metadata.time_base
         events: list[TriggerEvent] = []
 
-        # Track signal zones
-        # Zone 0: below low_threshold
-        # Zone 1: between thresholds
-        # Zone 2: above high_threshold
-        def get_zone(value: float) -> int:
-            if value < self.low_threshold:
-                return 0
-            elif value > self.high_threshold:
-                return 2
-            else:
-                return 1
-
-        zones = np.array([get_zone(v) for v in data])
-
-        # Find runt pulses: transitions that enter zone 1 but don't reach the other side
+        zones = np.array([self._get_zone(v) for v in data])
+
         i = 0
         while i < len(zones) - 1:
             curr_zone = zones[i]
 
-            if curr_zone == 0:
-                # Starting low - look for positive runt
-                if self.polarity in ("positive", "either"):
-                    # Find transition to zone 1
-                    if zones[i + 1] == 1:
-                        start_idx = i
-                        # Track through zone 1
-                        j = i + 1
-                        while j < len(zones) and zones[j] == 1:
-                            j += 1
-                        if j < len(zones) and zones[j] == 0:
-                            # Returned to low without reaching high - RUNT
-                            peak = float(np.max(data[start_idx : j + 1]))
-                            events.append(
-                                TriggerEvent(
-                                    timestamp=start_idx * sample_period,
-                                    sample_index=start_idx,
-                                    event_type=TriggerType.RUNT,
-                                    level=peak,
-                                    duration=(j - start_idx) * sample_period,
-                                    data={
-                                        "polarity": "positive",
-                                        "expected_high": self.high_threshold,
-                                        "actual_peak": peak,
-                                    },
-                                )
-                            )
-                        i = j
-                        continue
-
-            elif curr_zone == 2:
-                # Starting high - look for negative runt
-                if self.polarity in ("negative", "either") and zones[i + 1] == 1:
-                    start_idx = i
-                    j = i + 1
-                    while j < len(zones) and zones[j] == 1:
-                        j += 1
-                    if j < len(zones) and zones[j] == 2:
-                        # Returned to high without reaching low - RUNT
-                        trough = float(np.min(data[start_idx : j + 1]))
-                        events.append(
-                            TriggerEvent(
-                                timestamp=start_idx * sample_period,
-                                sample_index=start_idx,
-                                event_type=TriggerType.RUNT,
-                                level=trough,
-                                duration=(j - start_idx) * sample_period,
-                                data={
-                                    "polarity": "negative",
-                                    "expected_low": self.low_threshold,
-                                    "actual_trough": trough,
-                                },
-                            )
-                        )
-                    i = j
-                    continue
+            # Check for positive runt (starting from zone 0)
+            if curr_zone == 0 and self.polarity in ("positive", "either") and zones[i + 1] == 1:
+                event, next_i = self._find_positive_runt(zones, data, i, sample_period)
+                if event:
+                    events.append(event)
+                i = next_i
+                continue
+
+            # Check for negative runt (starting from zone 2)
+            if curr_zone == 2 and self.polarity in ("negative", "either") and zones[i + 1] == 1:
+                event, next_i = self._find_negative_runt(zones, data, i, sample_period)
+                if event:
+                    events.append(event)
+                i = next_i
+                continue
 
             i += 1
 

oscura/{triggering → utils/triggering}/window.py

@@ -4,7 +4,7 @@ Provides window triggering (signal inside/outside voltage window) and
 zone triggering (signal enters/exits defined zones) for limit testing.
 
 Example:
-    >>> from oscura.triggering.window import WindowTrigger, find_window_violations
+    >>> from oscura.utils.triggering.window import WindowTrigger, find_window_violations
     >>> # Trigger when signal exits 0-3.3V window
     >>> trigger = WindowTrigger(low_threshold=0, high_threshold=3.3, trigger_on="exit")
     >>> violations = trigger.find_events(trace)
@@ -18,7 +18,7 @@ from typing import TYPE_CHECKING, Literal
 import numpy as np
 
 from oscura.core.exceptions import AnalysisError
-from oscura.triggering.base import (
+from oscura.utils.triggering.base import (
     Trigger,
     TriggerEvent,
     TriggerType,

oscura/utils/validation.py

@@ -0,0 +1,32 @@
+"""Validation utility functions.
+
+This module provides validation helpers used across export and other modules.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oscura.workflows.reverse_engineering import ProtocolSpec
+
+
+def validate_protocol_spec(spec: "ProtocolSpec") -> None:
+    """Validate protocol specification.
+
+    Ensures protocol specification has required fields and is well-formed.
+
+    Args:
+        spec: Protocol specification to validate
+
+    Raises:
+        ValueError: If spec is invalid (missing name or fields)
+
+    Example:
+        >>> from oscura.analyzers.protocols.base import ProtocolSpec
+        >>> spec = ProtocolSpec(name="MyProtocol", fields=[...])
+        >>> validate_protocol_spec(spec)  # No error if valid
+    """
+    if not spec.name:
+        raise ValueError("Protocol name is required")
+
+    if not spec.fields:
+        raise ValueError("Protocol must have at least one field")

oscura/validation/__init__.py

@@ -0,0 +1,121 @@
+"""Validation and test generation for protocol specifications.
+
+This module provides tools for generating test vectors, validating protocol
+implementations, fuzzing protocol parsers, and replaying messages to verify
+reverse-engineered protocols.
+
+Example:
+    >>> from oscura.validation import GrammarTestGenerator, TestGenerationConfig
+    >>> from oscura.sessions import ProtocolSpec
+    >>>
+    >>> config = TestGenerationConfig(strategy="coverage", num_tests=100)
+    >>> generator = GrammarTestGenerator(config)
+    >>> tests = generator.generate_tests(protocol_spec)
+    >>> print(f"Generated {len(tests.valid_messages)} valid messages")
+    >>>
+    >>> # Replay validation
+    >>> from oscura.validation import ReplayConfig, ReplayValidator
+    >>> replay_config = ReplayConfig(interface="serial", port="/dev/ttyUSB0")
+    >>> validator = ReplayValidator(replay_config)
+    >>> result = validator.validate_protocol(protocol_spec, test_messages)
+    >>>
+    >>> # Fuzzing
+    >>> from oscura.validation import ProtocolFuzzer, FuzzingConfig
+    >>> fuzzer_config = FuzzingConfig(strategy="coverage_guided", max_iterations=1000)
+    >>> fuzzer = ProtocolFuzzer(fuzzer_config)
+    >>> report = fuzzer.fuzz_protocol(protocol_spec, seed_corpus)
+    >>> print(f"Found {report.total_crashes} crashes")
+
+Modules:
+    grammar_tests: Grammar-based test vector generation and fuzzing
+    replay: Protocol replay validation framework
+    fuzzer: Advanced protocol fuzzing with coverage-guided mutation
+"""
+
+from oscura.validation.compliance_tests import (
+    ComplianceConfig,
+    ComplianceTestGenerator,
+    ComplianceTestSuite,
+    StandardType,
+    TestCase,
+    TestType,
+)
+from oscura.validation.fuzzer import (
+    FuzzingConfig,
+    FuzzingReport,
+    FuzzingResult,
+    FuzzingStrategy,
+    MutationOperator,
+    ProtocolFuzzer,
+    TestResult,
+)
+from oscura.validation.grammar_tests import (
+    GeneratedTests,
+    GrammarTestGenerator,
+    TestGenerationConfig,
+)
+from oscura.validation.grammar_validator import (
+    ErrorSeverity,
+    ErrorType,
+    ProtocolGrammarValidator,
+    ValidationError,
+    ValidationReport,
+)
+from oscura.validation.hil_testing import (
+    HILConfig,
+    HILTester,
+    HILTestReport,
+    HILTestResult,
+    InterfaceType,
+    TestStatus,
+)
+from oscura.validation.regression_suite import (
+    ComparisonMode,
+    RegressionReport,
+    RegressionTestResult,
+    RegressionTestSuite,
+)
+from oscura.validation.replay import (
+    ProtocolSpec,
+    ReplayConfig,
+    ReplayValidator,
+    ValidationResult,
+)
+
+__all__ = [
+    "ComparisonMode",
+    "ComplianceConfig",
+    "ComplianceTestGenerator",
+    "ComplianceTestSuite",
+    "ErrorSeverity",
+    "ErrorType",
+    "FuzzingConfig",
+    "FuzzingReport",
+    "FuzzingResult",
+    "FuzzingStrategy",
+    "GeneratedTests",
+    "GrammarTestGenerator",
+    "HILConfig",
+    "HILTestReport",
+    "HILTestResult",
+    "HILTester",
+    "InterfaceType",
+    "MutationOperator",
+    "ProtocolFuzzer",
+    "ProtocolGrammarValidator",
+    "ProtocolSpec",
+    "RegressionReport",
+    "RegressionTestResult",
+    "RegressionTestSuite",
+    "ReplayConfig",
+    "ReplayValidator",
+    "StandardType",
+    "TestCase",
+    "TestGenerationConfig",
+    "TestResult",
+    "TestStatus",
+    "TestType",
+    "ValidationError",
+    "ValidationReport",
+    "ValidationResult",
+]

oscura/{compliance → validation/compliance}/__init__.py

@@ -7,7 +7,7 @@ and MIL-STD standards.
 
 Example:
     >>> import oscura as osc
-    >>> from oscura.compliance import load_limit_mask, check_compliance, generate_compliance_report
+    >>> from oscura.validation.compliance import load_limit_mask, check_compliance, generate_compliance_report
     >>>
     >>> trace = osc.load('emissions.wfm')
     >>> mask = load_limit_mask('FCC_Part15_ClassB')
@@ -15,7 +15,7 @@ Example:
     >>> generate_compliance_report(result, 'compliance_report.html')
 """
 
-from oscura.compliance.advanced import (
+from oscura.validation.compliance.advanced import (
     ComplianceTestConfig,
     ComplianceTestRunner,
     ComplianceTestSuite,
@@ -26,17 +26,17 @@ from oscura.compliance.advanced import (
     QuasiPeakDetector,
     interpolate_limit,
 )
-from oscura.compliance.masks import (
+from oscura.validation.compliance.masks import (
     AVAILABLE_MASKS,
     LimitMask,
     create_custom_mask,
     load_limit_mask,
 )
-from oscura.compliance.reporting import (
+from oscura.validation.compliance.reporting import (
     ComplianceReportFormat,
     generate_compliance_report,
 )
-from oscura.compliance.testing import (
+from oscura.validation.compliance.testing import (
     ComplianceResult,
     ComplianceViolation,
     DetectorType,

oscura/{compliance → validation/compliance}/advanced.py

@@ -22,7 +22,7 @@ import numpy as np
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
-    from oscura.compliance.masks import LimitMask
+    from oscura.validation.compliance.masks import LimitMask
 
 logger = logging.getLogger(__name__)
 
@@ -63,7 +63,7 @@ class LimitInterpolator:
     defined frequency points.
 
     Example:
-        >>> from oscura.compliance import load_limit_mask
+        >>> from oscura.validation.compliance import load_limit_mask
         >>> mask = load_limit_mask('FCC_Part15_ClassB')
         >>> interp = LimitInterpolator(mask)
         >>> limit_at_100mhz = interp.interpolate(100e6)
@@ -339,7 +339,7 @@ class ComplianceTestRunner:
         Returns:
             Self for chaining
         """
-        from oscura.compliance.masks import load_limit_mask
+        from oscura.validation.compliance.masks import load_limit_mask
 
         mask = load_limit_mask(mask_name)
         self._masks.append((mask_name, mask))
@@ -573,7 +573,7 @@ class QuasiPeakDetector:
     """
 
     # CISPR 16-1-1 detector parameters by band
-    BAND_PARAMS = {  # noqa: RUF012
+    BAND_PARAMS = {
         QPDetectorBand.BAND_A: QPDetectorParams(
             bandwidth=200,  # 200 Hz
             charge_time=45,  # ms
@@ -601,7 +601,7 @@ class QuasiPeakDetector:
     }
 
     # Frequency ranges for bands (Hz)
-    BAND_RANGES = {  # noqa: RUF012
+    BAND_RANGES = {
         QPDetectorBand.BAND_A: (9e3, 150e3),
         QPDetectorBand.BAND_B: (150e3, 30e6),
         QPDetectorBand.BAND_C: (30e6, 300e6),

oscura/{compliance → validation/compliance}/masks.py

@@ -4,7 +4,7 @@ This module provides limit mask loading and management for EMC compliance testin
 
 
 Example:
-    >>> from oscura.compliance.masks import load_limit_mask, AVAILABLE_MASKS
+    >>> from oscura.validation.compliance.masks import load_limit_mask, AVAILABLE_MASKS
     >>> print(AVAILABLE_MASKS)
     >>> mask = load_limit_mask('FCC_Part15_ClassB')
     >>> print(f"Frequency range: {mask.frequency_range}")