oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/export/wireshark/lua_builder.py

@@ -0,0 +1,159 @@
+"""Lua code builder for programmatic dissector generation.
+
+This module provides a builder class for constructing Lua code with
+proper indentation and structure.
+"""
+
+
+class LuaCodeBuilder:
+    """Build Lua dissector code programmatically.
+
+    This class helps construct well-formatted Lua code with proper
+    indentation and structure management.
+
+    Example:
+        >>> builder = LuaCodeBuilder()
+        >>> builder.add_comment("Initialize protocol")
+        >>> builder.add_variable("proto", 'Proto("myproto", "My Protocol")')
+        >>> builder.begin_function("dissector", ["buffer", "pinfo", "tree"])
+        >>> builder.add_line("pinfo.cols.protocol = proto.name")
+        >>> builder.end_function()
+        >>> print(builder.to_string())
+    """
+
+    def __init__(self, indent_size: int = 4) -> None:
+        """Initialize the builder.
+
+        Args:
+            indent_size: Number of spaces per indentation level
+        """
+        self.lines: list[str] = []
+        self.indent_level = 0
+        self.indent_size = indent_size
+
+    def add_line(self, line: str) -> None:
+        """Add a line with current indentation.
+
+        Args:
+            line: Line content (without indentation)
+        """
+        if line.strip():  # Don't indent empty lines
+            indent = " " * (self.indent_level * self.indent_size)
+            self.lines.append(f"{indent}{line}")
+        else:
+            self.lines.append("")
+
+    def add_blank_line(self) -> None:
+        """Add a blank line."""
+        self.lines.append("")
+
+    def add_comment(self, comment: str, prefix: str = "--") -> None:
+        """Add a Lua comment.
+
+        Args:
+            comment: Comment text
+            prefix: Comment prefix (default: "--")
+        """
+        self.add_line(f"{prefix} {comment}")
+
+    def begin_function(self, name: str, params: list[str]) -> None:
+        """Start a function definition.
+
+        Args:
+            name: Function name
+            params: List of parameter names
+        """
+        param_list = ", ".join(params)
+        self.add_line(f"function {name}({param_list})")
+        self.indent_level += 1
+
+    def end_function(self) -> None:
+        """End a function definition."""
+        self.indent_level -= 1
+        self.add_line("end")
+
+    def begin_if(self, condition: str) -> None:
+        """Start an if statement.
+
+        Args:
+            condition: If condition
+        """
+        self.add_line(f"if {condition} then")
+        self.indent_level += 1
+
+    def add_else(self) -> None:
+        """Add else clause."""
+        self.indent_level -= 1
+        self.add_line("else")
+        self.indent_level += 1
+
+    def add_elseif(self, condition: str) -> None:
+        """Add elseif clause.
+
+        Args:
+            condition: Elseif condition
+        """
+        self.indent_level -= 1
+        self.add_line(f"elseif {condition} then")
+        self.indent_level += 1
+
+    def end_if(self) -> None:
+        """End an if statement."""
+        self.indent_level -= 1
+        self.add_line("end")
+
+    def begin_for(self, loop_var: str, start: str, end: str) -> None:
+        """Start a for loop.
+
+        Args:
+            loop_var: Loop variable name
+            start: Start value
+            end: End value
+        """
+        self.add_line(f"for {loop_var} = {start}, {end} do")
+        self.indent_level += 1
+
+    def end_for(self) -> None:
+        """End a for loop."""
+        self.indent_level -= 1
+        self.add_line("end")
+
+    def add_variable(self, name: str, value: str, local: bool = True) -> None:
+        """Add a variable declaration.
+
+        Args:
+            name: Variable name
+            value: Variable value
+            local: Whether to use 'local' keyword
+        """
+        prefix = "local " if local else ""
+        self.add_line(f"{prefix}{name} = {value}")
+
+    def add_return(self, value: str) -> None:
+        """Add a return statement.
+
+        Args:
+            value: Return value
+        """
+        self.add_line(f"return {value}")
+
+    def indent(self) -> None:
+        """Increase indentation level."""
+        self.indent_level += 1
+
+    def dedent(self) -> None:
+        """Decrease indentation level."""
+        if self.indent_level > 0:
+            self.indent_level -= 1
+
+    def to_string(self) -> str:
+        """Generate final Lua code.
+
+        Returns:
+            Complete Lua code as a string
+        """
+        return "\n".join(self.lines)
+
+    def __str__(self) -> str:
+        """String representation."""
+        return self.to_string()

oscura/export/wireshark/templates/dissector.lua.j2

@@ -0,0 +1,92 @@
+-- {{ protocol.name }}.lua
+-- Generated by TraceKit on {{ timestamp }}
+--
+-- Protocol: {{ protocol.description }}
+-- Version: {{ protocol.version }}
+{% if protocol.endian %}-- Endianness: {{ protocol.endian }}
+{% endif %}
+
+-- Protocol declaration
+local {{ proto_var }} = Proto("{{ protocol.name }}", "{{ protocol.description }}")
+
+-- Field declarations
+{% for field in fields %}
+local f_{{ field.name }} = {{ field.protofield_type }}(
+    "{{ protocol.name }}.{{ field.name }}",
+    "{{ field.display_name }}",
+    {{ field.display_base }}
+    {%- if field.value_string %}, {{ field.value_string }}{% endif %}
+)
+{% endfor %}
+
+-- Register fields
+{{ proto_var }}.fields = { {% for field in fields %}f_{{ field.name }}{% if not loop.last %}, {% endif %}{% endfor %} }
+
+-- Dissector function
+function {{ proto_var }}.dissector(buffer, pinfo, tree)
+    local pktlen = buffer:len()
+
+    -- Check minimum length
+    if pktlen < {{ min_length }} then
+        return 0  -- Not enough data
+    end
+
+    -- Set protocol column
+    pinfo.cols.protocol = {{ proto_var }}.name
+
+    -- Create protocol subtree
+    local subtree = tree:add({{ proto_var }}, buffer(), "{{ protocol.description }}")
+    local offset = 0
+
+    -- Decode fields
+{% for field in fields %}
+    {% if field.condition %}
+    -- Conditional field: {{ field.name }} ({{ field.condition }})
+    -- TODO: Implement condition evaluation
+    {% endif %}
+    {% if field.is_variable_length %}
+    -- Variable-length field: {{ field.name }}
+    {% if field.size_field %}
+    local {{ field.name }}_len = buffer({{ field.size_offset }}, {{ field.size_field_size }}):{{ field.size_reader }}()
+    if offset + {{ field.name }}_len > pktlen then
+        subtree:add_expert_info(PI_MALFORMED, PI_ERROR, "Truncated {{ field.name }}")
+        return pktlen
+    end
+    subtree:add(f_{{ field.name }}, buffer(offset, {{ field.name }}_len))
+    offset = offset + {{ field.name }}_len
+    {% else %}
+    -- Use remaining data for {{ field.name }}
+    local {{ field.name }}_len = pktlen - offset
+    subtree:add(f_{{ field.name }}, buffer(offset, {{ field.name }}_len))
+    offset = offset + {{ field.name }}_len
+    {% endif %}
+    {% else %}
+    -- Fixed-length field: {{ field.name }} ({{ field.size }} bytes)
+    if offset + {{ field.size }} > pktlen then
+        subtree:add_expert_info(PI_MALFORMED, PI_ERROR, "Truncated {{ field.name }}")
+        return pktlen
+    end
+    subtree:add(f_{{ field.name }}, buffer(offset, {{ field.size }}))
+    offset = offset + {{ field.size }}
+    {% endif %}
+
+{% endfor %}
+    return offset
+end
+
+-- Protocol registration
+{% if transport == "tcp" %}
+-- Register on TCP port {{ port }}
+local tcp_table = DissectorTable.get("tcp.port")
+tcp_table:add({{ port }}, {{ proto_var }})
+{% elif transport == "udp" %}
+-- Register on UDP port {{ port }}
+local udp_table = DissectorTable.get("udp.port")
+udp_table:add({{ port }}, {{ proto_var }})
+{% elif pattern %}
+-- Register on pattern match
+-- TODO: Implement heuristic dissector for pattern "{{ pattern }}"
+{% else %}
+-- No automatic registration - manually register as needed
+-- Example: DissectorTable.get("tcp.port"):add(PORT, {{ proto_var }})
+{% endif %}

oscura/export/wireshark/type_mapping.py

@@ -0,0 +1,165 @@
+"""Type mapping between TraceKit field types and Wireshark ProtoField types.
+
+This module provides mappings from TraceKit protocol field types to their
+corresponding Wireshark Lua ProtoField types and display bases.
+
+References:
+    https://wiki.wireshark.org/LuaAPI/Proto
+"""
+
+from typing import Literal
+
+# Map TraceKit field types to Wireshark ProtoField types
+FIELD_TYPE_MAPPING: dict[str, str] = {
+    "uint8": "ProtoField.uint8",
+    "uint16": "ProtoField.uint16",
+    "uint32": "ProtoField.uint32",
+    "uint64": "ProtoField.uint64",
+    "int8": "ProtoField.int8",
+    "int16": "ProtoField.int16",
+    "int32": "ProtoField.int32",
+    "int64": "ProtoField.int64",
+    "bytes": "ProtoField.bytes",
+    "string": "ProtoField.string",
+    "bool": "ProtoField.bool",
+    "float32": "ProtoField.float",
+    "float64": "ProtoField.double",
+}
+
+# Map display base names to Wireshark base constants
+BASE_MAPPING: dict[str, str] = {
+    "dec": "base.DEC",
+    "hex": "base.HEX",
+    "oct": "base.OCT",
+    "bin": "base.BIN",
+    "none": "base.NONE",
+}
+
+# Default display base for each field type
+DEFAULT_BASE: dict[str, str] = {
+    "uint8": "hex",
+    "uint16": "hex",
+    "uint32": "hex",
+    "uint64": "hex",
+    "int8": "dec",
+    "int16": "dec",
+    "int32": "dec",
+    "int64": "dec",
+    "bytes": "none",
+    "string": "none",
+    "bool": "none",
+    "float32": "none",
+    "float64": "none",
+}
+
+
+def get_protofield_type(field_type: str, display_base: str | None = None) -> tuple[str, str]:
+    """Map TraceKit field type to Wireshark ProtoField and display base.
+
+    Args:
+        field_type: TraceKit field type (uint8, uint16, string, etc.)
+        display_base: Optional display base (dec, hex, oct, bin, none)
+
+    Returns:
+        Tuple of (protofield_type, base_constant)
+        Example: ("ProtoField.uint16", "base.HEX")
+
+    Raises:
+        ValueError: If field type is unknown
+    """
+    if field_type not in FIELD_TYPE_MAPPING:
+        raise ValueError(f"Unknown field type: {field_type}")
+
+    protofield = FIELD_TYPE_MAPPING[field_type]
+
+    # Determine display base
+    if display_base is None:
+        display_base = DEFAULT_BASE[field_type]
+
+    if display_base not in BASE_MAPPING:
+        raise ValueError(f"Unknown display base: {display_base}")
+
+    base_constant = BASE_MAPPING[display_base]
+
+    return protofield, base_constant
+
+
+def get_field_size(field_type: str) -> int | None:
+    """Get the fixed size in bytes for a field type.
+
+    Args:
+        field_type: TraceKit field type
+
+    Returns:
+        Field size in bytes, or None for variable-length types
+    """
+    size_map: dict[str, int | None] = {
+        "uint8": 1,
+        "int8": 1,
+        "uint16": 2,
+        "int16": 2,
+        "uint32": 4,
+        "int32": 4,
+        "uint64": 8,
+        "int64": 8,
+        "float32": 4,
+        "float64": 8,
+        "bool": 1,
+        "bytes": None,  # Variable length
+        "string": None,  # Variable length
+    }
+    return size_map.get(field_type)
+
+
+def is_variable_length(field_type: str) -> bool:
+    """Check if a field type is variable length.
+
+    Args:
+        field_type: TraceKit field type
+
+    Returns:
+        True if field is variable length
+    """
+    return get_field_size(field_type) is None
+
+
+def get_lua_reader_function(field_type: str, endian: Literal["big", "little"] = "big") -> str:
+    """Get the Lua buffer reader function for a field type.
+
+    Args:
+        field_type: TraceKit field type
+        endian: Byte order (big or little endian)
+
+    Returns:
+        Lua function name (e.g., "uint16", "le_uint16")
+
+    Raises:
+        ValueError: If field type is unknown
+    """
+    if field_type not in FIELD_TYPE_MAPPING:
+        raise ValueError(f"Unknown field type: {field_type}")
+
+    # Map field types to Lua buffer reader methods
+    reader_map: dict[str, str] = {
+        "uint8": "uint",
+        "int8": "int",
+        "uint16": "uint16",
+        "int16": "int16",
+        "uint32": "uint32",
+        "int32": "int32",
+        "uint64": "uint64",
+        "int64": "int64",
+        "float32": "float",
+        "float64": "double",
+        "bool": "uint",
+        "bytes": "bytes",
+        "string": "string",
+    }
+
+    reader = reader_map[field_type]
+
+    # Add little-endian prefix if needed
+    if endian == "little" and field_type not in ["uint8", "int8", "bool", "bytes", "string"]:
+        return f"le_{reader}"
+
+    return reader

oscura/export/wireshark/validator.py

@@ -0,0 +1,105 @@
+"""Lua syntax validator using luac compiler.
+
+This module validates generated Lua code syntax using the luac compiler
+if available on the system.
+"""
+
+import subprocess
+from pathlib import Path
+
+
+def validate_lua_syntax(lua_code: str) -> tuple[bool, str]:
+    """Validate Lua syntax using luac compiler.
+
+    This function attempts to validate Lua code by passing it through
+    the luac compiler. If luac is not available, validation is skipped.
+
+    Args:
+        lua_code: Lua code to validate
+
+    Returns:
+        Tuple of (is_valid, error_message)
+        - is_valid: True if syntax is valid or validation skipped
+        - error_message: Empty string if valid, error details if invalid,
+                        or skip message if luac not available
+
+    Example:
+        >>> valid, error = validate_lua_syntax("local x = 1")
+        >>> if not valid:
+        ...     print(f"Syntax error: {error}")
+    """
+    try:
+        # Try to validate using luac
+        result = subprocess.run(
+            ["luac", "-p", "-"],
+            input=lua_code.encode(),
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        if result.returncode == 0:
+            return True, ""
+        return False, result.stderr.decode()
+    except FileNotFoundError:
+        # luac not available, skip validation
+        return True, "luac not found, syntax validation skipped"
+    except subprocess.TimeoutExpired:
+        return False, "Validation timeout"
+    except Exception as e:
+        # Other errors - treat as unable to validate
+        return True, f"Validation skipped: {e!s}"
+
+
+def validate_lua_file(lua_path: Path) -> tuple[bool, str]:
+    """Validate a Lua file using luac compiler.
+
+    Args:
+        lua_path: Path to Lua file
+
+    Returns:
+        Tuple of (is_valid, error_message)
+
+    Raises:
+        FileNotFoundError: If the file does not exist
+    """
+    if not lua_path.exists():
+        raise FileNotFoundError(f"Lua file not found: {lua_path}")
+
+    lua_code = lua_path.read_text()
+    return validate_lua_syntax(lua_code)
+
+
+def check_luac_available() -> bool:
+    """Check if luac compiler is available on the system.
+
+    Returns:
+        True if luac is available, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["luac", "-v"],
+            capture_output=True,
+            timeout=2,
+            check=False,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def save_and_validate(lua_code: str, output_path: Path) -> tuple[bool, str]:
+    """Save Lua code to file and validate it.
+
+    Args:
+        lua_code: Lua code to save
+        output_path: Where to save the file
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    # Save the file first
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(lua_code)
+
+    # Validate
+    return validate_lua_file(output_path)

oscura/exporters/__init__.py

@@ -0,0 +1,94 @@
+"""Data export module for TraceKit.
+
+Provides export functionality to various file formats including CSV, HDF5,
+JSON, MATLAB, Markdown, HTML, NumPy NPZ, and SPICE PWL.
+
+
+Example:
+    >>> from oscura.exporters import export_csv, export_hdf5, export_json, export_mat
+    >>> export_csv(trace, "waveform.csv")
+    >>> export_hdf5(trace, "waveform.h5")
+    >>> export_json(trace, "waveform.json")
+    >>> export_mat(trace, "waveform.mat")
+    >>> export_markdown(data, "report.md")
+    >>> export_html(data, "report.html")
+    >>> export_npz(trace, "waveform.npz")
+    >>> export_pwl(trace, "stimulus.pwl")
+"""
+
+# Import exporters module as namespace for DSL compatibility
+from oscura.exporters import exporters
+from oscura.exporters.csv import (
+    export_csv,
+    export_multi_trace_csv,
+)
+from oscura.exporters.hdf5 import (
+    append_trace,
+    export_hdf5,
+    export_measurement_results,
+)
+from oscura.exporters.html_export import (
+    export_html,
+    generate_html_report,
+)
+from oscura.exporters.json_export import (
+    TraceKitJSONEncoder,
+    export_json,
+    export_measurements,
+    export_protocol_decode,
+    load_json,
+)
+from oscura.exporters.markdown_export import (
+    export_markdown,
+    generate_markdown_report,
+)
+from oscura.exporters.matlab_export import (
+    export_mat,
+    export_multi_trace_mat,
+)
+from oscura.exporters.npz_export import (
+    export_npz,
+    load_npz,
+)
+from oscura.exporters.spice_export import (
+    export_pwl,
+    export_pwl_multi,
+    generate_spice_source,
+)
+
+__all__ = [
+    "TraceKitJSONEncoder",
+    "append_trace",
+    # CSV export (EXP-001)
+    "export_csv",
+    # HDF5 export (EXP-002)
+    "export_hdf5",
+    # HTML export (EXP-007)
+    "export_html",
+    # JSON export (EXP-003)
+    "export_json",
+    # Markdown export (EXP-006)
+    "export_markdown",
+    # MATLAB export (EXP-008)
+    "export_mat",
+    "export_measurement_results",
+    "export_measurements",
+    "export_multi_trace_csv",
+    "export_multi_trace_mat",
+    # NPZ export (EXP-004)
+    "export_npz",
+    "export_protocol_decode",
+    # SPICE PWL export (EXP-005)
+    "export_pwl",
+    "export_pwl_multi",
+    "exporters",
+    # HTML report generation
+    "generate_html_report",
+    # Markdown report generation
+    "generate_markdown_report",
+    # SPICE source generation
+    "generate_spice_source",
+    "load_json",
+    # NPZ loading
+    "load_npz",
+]