# oc_diagnostics  
Unified Debugging, Tracing, and Instrumentation for Option C Projects

`oc_diagnostics` is the official runtime diagnostics package for the Option C ecosystem.  
It provides a unified debugging system, Dash‑aware instrumentation, callback middleware, a UI event logger, and a complete self‑test suite.

It is designed to be:

- predictable  
- project‑agnostic  
- easy to integrate  
- fully configurable  
- compatible with any Option C project  

OCT (Option C Tools) uses this package internally and re‑exports its public API.

---

## Installation

Core debugging only:

```bash
pip install oc_diagnostics
```

With Dash instrumentation:

```bash
pip install oc_diagnostics[dash]
```

---

## Quickstart

### 1. Add a project‑level diagnostics config

Create:

```
diagnostics/debug_config.json
```

Example:

```json
{
  "domains": {
    "DATA": { "level": 3, "color": "cyan" },
    "UI":   { "level": 4, "color": "blue" },
    "INSTRUMENTATION": 3
  },
  "global_settings": {
    "silent_mode": false,
    "enable_timestamps": true,
    "enable_colors": true,
    "include_filename": true,
    "output_mode": "both",
    "instrumentation_enabled": true
  }
}
```

### 2. Use `_dbg` in your code

```python
from oc_diagnostics import _dbg

def compute(x):
    func = "compute"
    _dbg("DATA", func, f"START x={x}", 2)
    return x * 2
```

### 3. Enable instrumentation in Dash apps

```python
from oc_diagnostics.instrumentation_middleware import enable_instrumentation_middleware
from oc_diagnostics.ui_event_logger import ui_event_logger

app = Dash(__name__)
app.layout = build_layout()  # static layout (uninstrumented)

ui_event_logger(app)
register_callbacks(app)
enable_instrumentation_middleware(app)
```

### 4. Instrument dynamic content

```python
from oc_diagnostics.instrumentation_middleware import apply_instrumentation

return apply_instrumentation(html.Div("Dynamic content"))
```

---

## Features

### Unified Debugging
- `_dbg(domain, func, message, level)`
- domain‑level filtering  
- timestamps  
- colorized output  
- filename + line number inclusion  
- stdout/stderr interception  
- uncaught exception logging  
- project‑owned configuration  

### Dash Instrumentation
- ID rewriting (`{"event": "<id>"}`)  
- structural ID protection  
- recursive instrumentation  
- custom component support at higher debug levels  

### Middleware
- callback dispatcher patching  
- automatic instrumentation of callback outputs  

### UI Event Logger
- captures all user interactions  
- logs property changes (`n_clicks`, `value`, `data`, `figure`, `selectedData`)  

### Self‑Test Suite
- deterministic CLI tests  
- optional Dash app tests  
- validates ID rewriting, middleware, and event logging  

---

## Documentation

Full documentation is included in the package:

- **Overview**  
  `README.md`

- **Architecture**  
  `docs/ARCHITECTURE.md`

- **Technical Reference**  
  `docs/REFERENCE.md`

- **Integration Guide**  
  `docs/INTEGRATION_GUIDE.md`

- **Release Notes**  
  `docs/CHANGELOG.md`

- **Opytion C Coding Style Specification** 
  `docs/option_c_specs/00_Master_Option_C_Specs_Intro_V3_4.md` (entry point) plus Core / Tooling / Diagnostics / AI Protocol / Changelog companion files in the same directory.
---

## License

MIT