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

oscura/reporting/templates/index.md

@@ -0,0 +1,173 @@
+# {{title}}
+
+## Report Metadata
+
+|Field|Value|
+|---|---|
+|**Input File**|{{input_name}}|
+|**File Size**|{{input_size}}|
+|**Input Type**|{{input_type}}|
+|**Generated**|{{timestamp}}|
+|**Analysis Duration**|{{duration}}|
+
+## Analysis Summary
+
+|Metric|Count|
+|---|---|
+|Total Analyses|{{total_analyses}}|
+|Successful|{{successful}}|
+|Failed|{{failed}}|
+|Analysis Domains|{{domains_count}}|
+
+{{#if has_errors}}
+
+> **Warning**: {{failed}} analyses encountered errors. See [Errors](#errors) section for details.
+> {{/if}}
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+  {{#each domains}}
+- [{{domain_name}}](#{{domain_id}})
+  {{/each}}
+  {{#if has_errors}}
+- [Errors](#errors)
+  {{/if}}
+- [Data Files](#data-files)
+
+---
+
+## Overview
+
+This comprehensive analysis report contains **{{total_analyses}}** analyses across **{{domains_count}}** domains. Analysis completed in **{{duration}}**.
+
+{{#if has_errors}}
+**Note**: {{failed}} analyses encountered errors during execution. Check the [Errors](#errors) section below for details.
+{{/if}}
+
+---
+
+{{#each domains}}
+
+## {{domain_name}} {#{{domain_id}}}
+
+**Statistics**: {{analyses_count}} analyses | {{plots_count}} plots | {{data_files_count}} data files
+
+{{#if key_findings}}
+
+### Key Findings
+
+{{#each key_findings}}
+
+- {{this}}
+  {{/each}}
+
+{{/if}}
+{{#if plots}}
+
+### Visualizations
+
+{{#each plots}}
+
+#### {{title}}
+
+![{{title}}]({{path}})
+
+{{/each}}
+
+{{/if}}
+{{#if data_files}}
+
+### Data Files
+
+{{#each data_files}}
+
+- [{{filename}}]({{path}}) - {{format}}
+  {{/each}}
+
+{{/if}}
+
+{{/each}}
+
+{{#if has_errors}}
+
+## Errors {#errors}
+
+The following analyses encountered errors during execution:
+
+{{#each errors}}
+
+### {{domain}} - {{analysis_name}}
+
+```
+{{error_message}}
+```
+
+{{/each}}
+
+---
+
+{{/if}}
+
+## Data Files {#data-files}
+
+Full analysis results are available in multiple formats:
+
+- [summary.json](summary.json) - Complete JSON output
+- [summary.yaml](summary.yaml) - YAML format for readability
+- [summary.csv](summary.csv) - Tabular data export
+- [index.md](index.md) - This Markdown report
+
+---
+
+## Technical Details
+
+### Analysis Configuration
+
+All analyses were executed using the Oscura comprehensive analysis system with the following configuration:
+
+- Input file: `{{input_name}}`
+- File size: {{input_size}}
+- Input type: {{input_type}}
+- Analysis duration: {{duration}}
+- Total analyses: {{total_analyses}}
+- Success rate: {{successful}}/{{total_analyses}}
+
+### Output Structure
+
+```
+output_directory/
+├── index.html              # Interactive HTML report
+├── index.md                # This Markdown report
+├── summary.json            # Complete JSON data
+├── summary.yaml            # YAML formatted data
+├── summary.csv             # CSV export
+{{#each domains}}
+├── {{domain_id}}/          # {{domain_name}} outputs
+{{#if plots}}
+│   ├── plots/              # Visualization files
+{{#each plots}}
+│   │   ├── {{filename}}
+{{/each}}
+{{/if}}
+{{#if data_files}}
+│   └── data/               # Analysis data files
+{{#each data_files}}
+│       ├── {{filename}}
+{{/each}}
+{{/if}}
+{{/each}}
+```
+
+### Viewing This Report
+
+- **HTML Version**: Open `index.html` in any modern web browser for an interactive experience with dark mode support
+- **Markdown Version**: View this file in any Markdown-compatible viewer or editor
+- **PDF Export**: The HTML version is print-optimized for PDF generation via browser print
+
+---
+
+_Generated by Oscura Comprehensive Analysis System_
+_Report timestamp: {{timestamp}}_

oscura/schemas/__init__.py

@@ -0,0 +1,158 @@
+"""JSON Schema definitions for TraceKit configuration types.
+
+This module provides JSON Schema definitions for validating various
+configuration file types used in TraceKit, including packet formats,
+device mappings, bus configurations, and protocol definitions.
+
+
+Example:
+    >>> from oscura.schemas import load_schema, validate_config
+    >>> schema = load_schema("packet_format")
+    >>> validate_config(config_dict, "packet_format")
+    True
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from oscura.config.schema import (
+    ConfigSchema,
+    get_schema_registry,
+    register_schema,
+    validate_against_schema,
+)
+
+__all__ = [
+    "SCHEMA_NAMES",
+    "get_schema_path",
+    "load_schema",
+    "register_builtin_schemas",
+    "validate_config",
+]
+
+# Schema type names
+SCHEMA_NAMES = [
+    "packet_format",
+    "device_mapping",
+    "bus_configuration",
+    "protocol_definition",
+]
+
+
+def get_schema_path(schema_name: str) -> Path:
+    """Get the file path for a schema definition.
+
+    Args:
+        schema_name: Schema name (e.g., "packet_format").
+
+    Returns:
+        Path to the JSON schema file.
+
+    Raises:
+        ValueError: If schema name is not recognized.
+        FileNotFoundError: If schema file does not exist.
+    """
+    if schema_name not in SCHEMA_NAMES:
+        raise ValueError(f"Unknown schema name: {schema_name}. Available schemas: {SCHEMA_NAMES}")
+
+    schema_dir = Path(__file__).parent
+    schema_file = schema_dir / f"{schema_name}.json"
+
+    if not schema_file.exists():
+        raise FileNotFoundError(f"Schema file not found: {schema_file}")
+
+    return schema_file
+
+
+def load_schema(schema_name: str) -> dict[str, Any]:
+    """Load a JSON schema definition from disk.
+
+    Args:
+        schema_name: Schema name (e.g., "packet_format").
+
+    Returns:
+        JSON schema dictionary.
+    """
+    schema_path = get_schema_path(schema_name)
+
+    with open(schema_path) as f:
+        result: dict[str, Any] = json.load(f)
+        return result
+
+
+def validate_config(
+    config: dict[str, Any],
+    schema_name: str,
+    *,
+    strict: bool = False,
+) -> bool:
+    """Validate a configuration dictionary against a schema.
+
+    Args:
+        config: Configuration dictionary to validate.
+        schema_name: Schema name (e.g., "packet_format").
+        strict: If True, fail on additional properties.
+
+    Returns:
+        True if validation passes.
+
+    Example:
+        >>> config = {"name": "test", "packet": {...}, "header": {...}}
+        >>> validate_config(config, "packet_format")
+        True
+    """
+    # Use the existing validation system from config.schema
+    return validate_against_schema(config, schema_name, strict=strict)
+
+
+def register_builtin_schemas() -> None:
+    """Register all built-in configuration schemas.
+
+    This function registers the following schemas:
+    - packet_format: Binary packet format configurations
+    - device_mapping: Device ID to name mappings
+    - bus_configuration: Parallel bus configurations
+    - protocol_definition: Protocol DSL definitions
+
+
+
+    The schemas are registered with the global SchemaRegistry and can
+    be accessed via validate_against_schema() or get_schema_registry().
+    """
+    registry = get_schema_registry()
+
+    # Load and register each schema
+    for schema_name in SCHEMA_NAMES:
+        # Skip if already registered
+        if registry.has_schema(schema_name):
+            continue
+
+        schema_dict = load_schema(schema_name)
+
+        # Extract version from $id if present
+        version = "1.0.0"  # default
+        if "$id" in schema_dict:
+            # Extract version from URI like .../v1.0.0.json
+            schema_id = schema_dict["$id"]
+            if "/v" in schema_id:
+                version_part = schema_id.split("/v")[-1]
+                version = version_part.replace(".json", "")
+
+        # Create ConfigSchema object
+        config_schema = ConfigSchema(
+            name=schema_name,
+            version=version,
+            schema=schema_dict,
+            description=schema_dict.get("description", ""),
+            uri=schema_dict.get("$id"),
+        )
+
+        # Register with global registry
+        register_schema(config_schema, set_default=True)
+
+
+# Auto-register schemas on module import
+register_builtin_schemas()

oscura/schemas/bus_configuration.json

@@ -0,0 +1,322 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://tracekit.io/schemas/bus_configuration.json",
+  "title": "Bus Configuration Schema",
+  "description": "Schema for validating parallel bus configurations for multi-bit protocols (CFG-001).",
+  "type": "object",
+  "required": ["name", "settings"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Bus configuration identifier",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "description": "Configuration version",
+      "pattern": "^\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description"
+    },
+    "settings": {
+      "type": "object",
+      "description": "Global bus settings",
+      "properties": {
+        "active_low": {
+          "type": "boolean",
+          "description": "Signals are active-low (inverted)"
+        },
+        "sample_on": {
+          "type": "string",
+          "enum": ["rising", "falling", "both"],
+          "description": "Sample on clock/timing pulse edge"
+        },
+        "bit_numbering": {
+          "type": "string",
+          "enum": ["lsb_0", "msb_0"],
+          "description": "Bit numbering convention"
+        }
+      },
+      "additionalProperties": false
+    },
+    "data_bus": {
+      "type": "object",
+      "description": "Data bus definition",
+      "required": ["name", "width", "bits"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Bus name",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 128,
+          "description": "Bus width in bits"
+        },
+        "description": {
+          "type": "string",
+          "description": "Bus description"
+        },
+        "active_low": {
+          "type": "boolean",
+          "description": "Override global active_low setting"
+        },
+        "bits": {
+          "type": "array",
+          "description": "Bit mappings from channel to position",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["channel", "bit"],
+            "properties": {
+              "channel": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Source channel index"
+              },
+              "bit": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Bit position in bus"
+              },
+              "name": {
+                "type": "string",
+                "description": "Signal name",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "address_bus": {
+      "type": "object",
+      "description": "Address bus definition",
+      "required": ["name", "width", "bits"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Bus name",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 128,
+          "description": "Bus width in bits"
+        },
+        "description": {
+          "type": "string",
+          "description": "Bus description"
+        },
+        "active_low": {
+          "type": "boolean",
+          "description": "Override global active_low setting"
+        },
+        "bits": {
+          "type": "array",
+          "description": "Bit mappings from channel to position",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["channel", "bit"],
+            "properties": {
+              "channel": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Source channel index"
+              },
+              "bit": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Bit position in bus"
+              },
+              "name": {
+                "type": "string",
+                "description": "Signal name",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "control_signals": {
+      "type": "array",
+      "description": "Control signal definitions",
+      "items": {
+        "type": "object",
+        "required": ["name", "channel"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Signal name",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+          },
+          "channel": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Source channel index"
+          },
+          "active_low": {
+            "type": "boolean",
+            "description": "Signal is active-low"
+          },
+          "description": {
+            "type": "string",
+            "description": "Signal description"
+          },
+          "short_name": {
+            "type": "string",
+            "description": "Short name/abbreviation",
+            "maxLength": 8
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "timing": {
+      "type": "object",
+      "description": "Timing constraints and validation",
+      "properties": {
+        "clock_period_ns": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Clock period in nanoseconds"
+        },
+        "setup_time_ns": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Setup time requirement in nanoseconds"
+        },
+        "hold_time_ns": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Hold time requirement in nanoseconds"
+        },
+        "pulse_width_ns": {
+          "type": "object",
+          "description": "Pulse width requirements by signal type",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "transactions": {
+      "type": "object",
+      "description": "Transaction decoding rules",
+      "properties": {
+        "types": {
+          "type": "array",
+          "description": "Transaction type definitions",
+          "items": {
+            "type": "object",
+            "required": ["name", "conditions"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Transaction type name",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
+              },
+              "conditions": {
+                "type": "object",
+                "description": "Signal conditions for this transaction",
+                "additionalProperties": {
+                  "type": "boolean"
+                }
+              },
+              "sample_on": {
+                "type": "string",
+                "description": "Control signal to sample on"
+              },
+              "capture": {
+                "type": "object",
+                "description": "Buses/signals to capture",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "instruction_decode": {
+      "type": "object",
+      "description": "Instruction decoding (if data contains opcodes)",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable instruction decoding"
+        },
+        "opcode_bits": {
+          "type": "array",
+          "description": "Bit range for opcode [start, end]",
+          "items": { "type": "integer", "minimum": 0 },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "opcodes": {
+          "type": "object",
+          "description": "Opcode to instruction mappings (keys can be integers or binary/hex strings)",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Instruction mnemonic"
+              },
+              "description": {
+                "type": "string",
+                "description": "Instruction description"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "output": {
+      "type": "object",
+      "description": "Output formatting options",
+      "properties": {
+        "format": {
+          "type": "string",
+          "enum": ["raw", "transaction", "annotated"],
+          "description": "Output format type"
+        },
+        "timestamp_format": {
+          "type": "string",
+          "enum": ["absolute", "relative_us", "relative_ns", "sample_index"],
+          "description": "Timestamp format"
+        },
+        "include_raw_values": {
+          "type": "boolean",
+          "description": "Include raw values in output"
+        },
+        "hex_format": {
+          "type": "boolean",
+          "description": "Display values in hexadecimal"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}