oct: oct.diag.oct_diag Namespace Reference

oct

Loading...

Searching...

No Matches

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
	VALID_LEVELS = set(range(10))
tuple	VALID_LOG_FORMATS = ("text", "jsonl")
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-9, in either form oc_diagnostics accepts:
  compact (``"GIT": 3``) or rich (``"GIT": {"level": 3, "color": "cyan"}``).
  Until 2026-09-28 this module allowed only 0-4 and the rich form, so a
  valid config such as ``{"*": 9}`` (open every domain for a trace) failed
  ``oct diag validate-config`` and crashed ``list-domains``.

Dependencies
------------
- oct.core.option_c_dir (debug_config.json path resolution)
- oct.core.diagnostics (_dbg structured logger)

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 66 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 88 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 246 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 77 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 123 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 320 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 264 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 171 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 56 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 58 of file oct_diag.py.

◆ VALID_LEVELS

oct.diag.oct_diag.VALID_LEVELS = set(range(10))

Definition at line 50 of file oct_diag.py.

◆ VALID_LOG_FORMATS

tuple oct.diag.oct_diag.VALID_LOG_FORMATS = ("text", "jsonl")

Definition at line 53 of file oct_diag.py.

oct
diag
oct_diag
Generated by 1.15.0