id_instrumentation.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/id_instrumentation.py
 
"""
ID Instrumentation Helper
=========================
 
This module rewrites Dash component IDs so that every interactive component
receives a pattern-matching ID of the form:
 
    id = {"event": "<original-id>"}
 
This enables the UI event logger to capture all user interactions.
 
Instrumentation behavior is controlled by:
- Global toggle: INSTRUMENTATION_ENABLED
- Debug level:   DEBUG_LEVELS["INSTRUMENTATION"] (0–9)
 
Instrumentation is recursive and safe:
- Structural IDs are never rewritten
- Dict IDs are never rewritten
- Components without IDs are skipped
- Custom components may be included depending on debug level
- Logging verbosity depends on instrumentation debug level
 
Responsibilities
----------------
- Recursively walk Dash component trees via the ``.children`` attribute.
- Rewrite string IDs to ``{"event": "<original-id>"}`` when instrumentation
  is active.
- Skip structural IDs (defined in ``STRUCTURAL_ID_PREFIXES`` and
  ``STRUCTURAL_ID_EXACT``).
- Skip dict IDs and components without an ``id`` attribute.
- Delegate verbosity decisions to ``unified_debug`` helpers
  (``instrumentation_verbose()``, ``instrumentation_allow_custom_components()``).
 
Diagnostics
-----------
Domain: INSTRUMENTATION
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Structural IDs (``root-group-*``, ``tab-group-*``, etc.) must never be
  rewritten.
- Dict IDs must never be rewritten.
- Must return the component unchanged when ``instrumentation_active()`` is
  ``False``.
- Must not raise; errors during ID rewriting are silently swallowed.
- Must not recurse beyond ``MAX_INSTRUMENT_DEPTH`` (500) levels; a L1
  diagnostic is emitted and the subtree is returned unchanged.
- Standard Dash base-class components are always instrumented when active.
- Custom (non-Dash-base-class) components are only instrumented when
  ``instrumentation_allow_custom_components()`` returns ``True``
  (``INSTRUMENTATION`` level ≥ 5).  This prevents accidental ID rewriting
  of plain Python objects that happen to have a ``.id`` attribute.
"""
 
import oc_diagnostics.unified_debug as _ud
from oc_diagnostics.unified_debug import (
    _dbg,
    instrumentation_active,
    instrumentation_verbose,
    instrumentation_allow_custom_components,
)
 
 
# -------------------------------------------------------------------
# Structural IDs — these must NEVER be instrumented
# -------------------------------------------------------------------
 
STRUCTURAL_ID_PREFIXES = (
    "root-group-",
    "tab-group-",
    "tab-content-",
    "pane-group-",
)
 
STRUCTURAL_ID_EXACT = {
    "theme-root",
    "theme-style-injector",
    "ui-theme-store",
    "system-settings-store",
    "data-settings-store",
    "plot-settings-store",
    "settings-data-store",
    "debug-settings-data-store",
    "debug-plot-settings-store",
    "init-once",
    "system-auto-load-interval",
    "plot-figure",          # Plot callback outputs to this
    "plot-status",          # Plot callback outputs to this
    "plot-size-indicator",  # Plot callback outputs to this
}
 
 
def is_structural_id(cid):
    """Return True if this ID should NOT be instrumented.
 
    Checks both the built-in structural-ID lists and any project-defined
    extensions loaded from ``global_settings.structural_id_prefixes`` /
    ``global_settings.structural_id_exact`` in ``debug_config.json``
    (FS-02 / OI-17).
    """
    if cid in STRUCTURAL_ID_EXACT or cid in _ud.ADDITIONAL_STRUCTURAL_EXACT:
        return True
    return (
        any(cid.startswith(p) for p in STRUCTURAL_ID_PREFIXES)
        or any(cid.startswith(p) for p in _ud.ADDITIONAL_STRUCTURAL_PREFIXES)
    )
 
 
# -------------------------------------------------------------------
# Dash base-class detection
# -------------------------------------------------------------------
 
def _is_dash_component(component) -> bool:
    """Return True if *component* inherits from the Dash base Component class.
 
    Dash is an optional dependency.  When it is not installed this function
    always returns False, which causes all components to be treated as custom
    and therefore subject to the ``instrumentation_allow_custom_components()``
    level gate.
    """
    try:
        from dash.development.base_component import Component as _DashBase  # type: ignore[import]
        return isinstance(component, _DashBase)
    except ImportError:
        return False
 
 
# -------------------------------------------------------------------
# Recursion depth limit
# -------------------------------------------------------------------
 
MAX_INSTRUMENT_DEPTH = 500
"""Maximum recursion depth for ``instrument_ids``.
 
Prevents ``RecursionError`` on pathologically deep component trees.
A L1 diagnostic is emitted when the limit is reached and the subtree
below that point is left uninstrumented.  Real-world Dash applications
rarely exceed 30–50 levels of nesting.
"""
 
 
# -------------------------------------------------------------------
# Recursive ID instrumentation
# -------------------------------------------------------------------
 
def instrument_ids(component, _depth: int = 0):
    """
    Recursively instrument Dash component IDs.
 
    Behavior is controlled by unified_debug:
 
    - instrumentation_active():
        False → return component unchanged
 
    - instrumentation_verbose():
        True  → log detailed recursion info
        False → log only high-level events
 
    - instrumentation_allow_custom_components():
        True  → include custom (non-Dash-base-class) components
        False → only standard Dash base-class components are instrumented
 
    Rules:
    - Instrument ANY component that has an ID stored in `.id`,
      or in Dash internals (`_props`, `_prop_ids`).
    - Only rewrite string IDs (ignore dict IDs, None, etc.).
    - Skip structural IDs.
    - Recurse into children (list, tuple, or single child).
    - Stop recursion if depth exceeds MAX_INSTRUMENT_DEPTH.
    """
 
    # ---------------------------------------------------------------
    # 0. Global instrumentation toggle
    # ---------------------------------------------------------------
    if not instrumentation_active():
        return component
 
    # ---------------------------------------------------------------
    # 0b. Recursion depth guard (OI-06)
    # ---------------------------------------------------------------
    if _depth > MAX_INSTRUMENT_DEPTH:
        _dbg(
            "INSTRUMENTATION",
            "instrument_ids",
            f"MAX_INSTRUMENT_DEPTH ({MAX_INSTRUMENT_DEPTH}) exceeded — "
            f"instrumentation truncated at depth {_depth}",
            level=1,
        )
        return component
 
    # ---------------------------------------------------------------
    # 1. Verbose debug header
    # ---------------------------------------------------------------
    if instrumentation_verbose():
        _dbg(
            "INSTRUMENTATION",
            "instrument_ids",
            f"TYPE={type(component).__name__}, "
            f"CHILDREN_TYPE={type(getattr(component, 'children', None))}, "
            f"ID={getattr(component, 'id', None)}",
            level=4,
        )
 
    # ---------------------------------------------------------------
    # 2. Extract the component's ID from all possible Dash locations
    # ---------------------------------------------------------------
    cid = getattr(component, "id", None)
 
    # Dash core components often store IDs internally
    if cid is None and hasattr(component, "_prop_ids"):
        cid = component._prop_ids.get("id")
 
    if cid is None and hasattr(component, "_props"):
        cid = component._props.get("id")
 
    # ---------------------------------------------------------------
    # 3. Instrument string IDs (skip dict IDs and structural IDs)
    # ---------------------------------------------------------------
    if isinstance(cid, str) and not is_structural_id(cid):
 
        # Standard Dash components are always eligible.
        # Custom (non-Dash-base-class) components require INSTRUMENTATION >= 5,
        # unless instrumentation_allow_all is set (FS-13), which bypasses the
        # type guard and instruments every component regardless of base class.
        if _ud.INSTRUMENTATION_ALL or _is_dash_component(component) or instrumentation_allow_custom_components():
 
            new_id = {"event": cid}
 
            # Write back to all known Dash ID locations
            try:
                component.id = new_id
            except Exception:
                pass
 
            if hasattr(component, "_prop_ids"):
                component._prop_ids["id"] = new_id
 
            if hasattr(component, "_props"):
                component._props["id"] = new_id
 
            if instrumentation_verbose():
                _dbg(
                    "INSTRUMENTATION",
                    "instrument_ids",
                    f"Instrumented ID: {cid}",
                    level=4,
                )
 
        elif instrumentation_verbose():
            _dbg(
                "INSTRUMENTATION",
                "instrument_ids",
                f"Skipped custom component ID: {cid} (INSTRUMENTATION level < 5)",
                level=4,
            )
 
    # ---------------------------------------------------------------
    # 4. Recurse into children
    # ---------------------------------------------------------------
    children = getattr(component, "children", None)
 
    if isinstance(children, (list, tuple)):
        for ch in children:
            instrument_ids(ch, _depth + 1)
 
    elif children is not None:
        instrument_ids(children, _depth + 1)
 
    return component