oct.diag.oct_diag Namespace Reference

Functions
Path	_find_config (Path project_root)
dict	load_config (Path project_root)
tuple[dict, bool]	_get_debug_domain_map (dict config)
dict	migrate_config (Path config_path, *, bool dry_run=False)
list[str]	validate_config (Path project_root)
list[dict]	list_domains (Path project_root)
dict	set_level (Path project_root, str domain, int level, *, bool dry_run=False)
Path	restore_config (Path project_root)

Variables
dict	VALID_LEVELS = {0, 1, 2, 3, 4}
str	CURRENT_SCHEMA_VERSION = "2.0"
dict	EXPECTED_GLOBAL_KEYS

Detailed Description

Purpose
-------
Provide oc_diagnostics configuration management tools for the OCT CLI.

Responsibilities
----------------
- Load, validate, and modify ``oc_diagnostics/debug_config.json``.
- List configured domains with their levels and colors.
- Update domain debug levels in-place.
- Report validation warnings without importing oc_diagnostics at runtime
  (preserving the dev-time/runtime architectural boundary).

Diagnostics
-----------
Domain: OCT-DIAG
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Must not import ``oc_diagnostics`` — operates purely on the JSON config file.
- Must preserve JSON formatting and key order when writing back.
- Level values must be integers 0-4 (matching ``oc_diagnostics.DEBUG_LEVELS``).

Dependencies
------------
- oct.core.option_c_dir (debug_config.json path resolution)

Function Documentation

_find_config()

Path oct.diag.oct_diag._find_config ( Path project_root )

protected

Locate debug_config.json (FS-539: `.option_c/`-first with fallbacks).

Delegates to :func:`oct.core.option_c_dir.resolve_debug_config`, which
tries ``.option_c/debug_config.json`` first, then
``oc_diagnostics/debug_config.json`` (v0.17+), then
``diagnostics/debug_config.json`` (pre-v0.17).

Definition at line 56 of file oct_diag.py.

Here is the caller graph for this function:

_get_debug_domain_map()

tuple[dict, bool] oct.diag.oct_diag._get_debug_domain_map ( dict config )

protected

OI-508 / FS-515: return ``(domain_map, is_legacy)`` from a config dict.

Accepts both the legacy v1 ``domains:`` layout and the current v2
``DEBUG_LEVELS:`` layout. The returned map is always in the v2 shape
(``{name: {"level": int, "color": str}}``) regardless of what the file
contains — call sites can read the result uniformly.

``is_legacy`` is True whenever the file used the ``domains:`` key
**and** the ``DEBUG_LEVELS:`` key was absent — that is the trigger
for the migration hint.

Definition at line 76 of file oct_diag.py.

Here is the caller graph for this function:

list_domains()

list[dict] oct.diag.oct_diag.list_domains

(

Path

project_root

)

Return list of domain info dicts: [{name, level, color}, ...].

OI-508 / FS-515: reads via :func:`_get_debug_domain_map` so both v1
and v2 configs surface identical output.

Definition at line 221 of file oct_diag.py.

Here is the call graph for this function:

load_config()

dict oct.diag.oct_diag.load_config

(

Path

project_root

)

Load and parse debug_config.json. Raises on missing/invalid file.

Definition at line 67 of file oct_diag.py.

Here is the call graph for this function:

Here is the caller graph for this function:

migrate_config()

dict oct.diag.oct_diag.migrate_config	(	Path	config_path,
		*	,
		bool	dry_run = False )

OI-508 / FS-515: rewrite ``config_path`` in-place as a v2 config.

Behaviour:
* Idempotent — if the file already declares ``_schema_version == "2.0"``
  and carries ``DEBUG_LEVELS``, nothing is written.
* Writes ``<config_path>.bk`` before overwriting the original, so a
  botched migration is recoverable.
* When ``dry_run`` is True, the target file is never touched and no
  backup is produced; the returned dict is the post-migration shape.

Returns the (would-be) post-migration config dict so callers can
inspect / pretty-print the result.

Definition at line 105 of file oct_diag.py.

Here is the call graph for this function:

restore_config()

Path oct.diag.oct_diag.restore_config

(

Path

project_root

)

OI-528: restore ``debug_config.json`` from its ``.bk`` backup.

Returns the path that was restored. Raises :class:`FileNotFoundError`
when no backup exists so the CLI can surface a clean error instead of
silently no-op-ing.

Definition at line 293 of file oct_diag.py.

Here is the call graph for this function:

set_level()

dict oct.diag.oct_diag.set_level	(	Path	project_root,
		str	domain,
		int	level,
		*	,
		bool	dry_run = False )

Update a domain's debug level in debug_config.json.

OI-508 / FS-515: writes to whichever key the file actually uses
(``DEBUG_LEVELS`` on v2, ``domains`` on legacy v1) so an operator
can tweak a level without a full migration first.

OI-528: safe-edit semantics. A ``<config_path>.bk`` backup is written
before overwriting the original so a bad edit is recoverable via
:func:`restore_config`. When ``dry_run`` is True, neither the target
nor the backup is touched; the returned dict is the *would-be*
post-edit config shape so callers can preview the result.

Definition at line 239 of file oct_diag.py.

Here is the call graph for this function:

validate_config()

list[str] oct.diag.oct_diag.validate_config

(

Path

project_root

)

Validate debug_config.json schema. Returns list of warnings/errors.

Definition at line 151 of file oct_diag.py.

Here is the call graph for this function:

Variable Documentation

CURRENT_SCHEMA_VERSION

str oct.diag.oct_diag.CURRENT_SCHEMA_VERSION = "2.0"

Definition at line 46 of file oct_diag.py.

EXPECTED_GLOBAL_KEYS

dict oct.diag.oct_diag.EXPECTED_GLOBAL_KEYS

Initial value:

=  {
    "silent_mode", "enable_timestamps", "enable_colors", "include_filename",
    "output_mode", "instrumentation_enabled", "max_log_files", "max_log_size_mb",
    "instrumentation_allow_all", "mode", "http_redact_headers",
    "ui_event_properties", "structural_id_prefixes", "structural_id_exact",
}

Definition at line 48 of file oct_diag.py.

VALID_LEVELS

dict oct.diag.oct_diag.VALID_LEVELS = {0, 1, 2, 3, 4}

Definition at line 43 of file oct_diag.py.