oct.diag.oct_diag module

oct.diag.oct_diag module#

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)

oct.diag.oct_diag.list_domains(project_root: Path) → list[dict][source]#

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

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

oct.diag.oct_diag.load_config(project_root: Path) → dict[source]#

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

oct.diag.oct_diag.migrate_config(config_path: Path, *, dry_run: bool = False) → dict[source]#

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.

oct.diag.oct_diag.restore_config(project_root: Path) → Path[source]#

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

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

oct.diag.oct_diag.set_level(project_root: Path, domain: str, level: int, *, dry_run: bool = False) → dict[source]#

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 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.

oct.diag.oct_diag.validate_config(project_root: Path) → list[str][source]#

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