octrc.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/octrc.py
 
"""
Purpose
-------
OI-519 - single source of truth for ``.octrc.json`` loading. Multiple OCT
modules (linter, formatter, health, typecheck, MCP config) used to each
carry their own ``json.loads`` + ``try/except`` around the same file; that
drift-prone pattern is replaced by :func:`load_octrc` and its silent
convenience wrapper :func:`load_octrc_safe`.
 
Responsibilities
----------------
- Resolve ``<project_root>/.octrc.json``.
- Tolerate missing file, OSError, invalid JSON, and non-object top-level
  documents - never raise.
- Return a ``(config, errors)`` tuple from :func:`load_octrc` so callers
  that care about strict-mode handling (the linter) can surface messages.
- Return a plain ``dict`` from :func:`load_octrc_safe` for callers that
  only want the data.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - (none) callers decide how to react to a load failure
    L3 - load entry, naming the project root being read
    L4 - (none)
 
Contracts
---------
- Both functions accept the project root, not the config path, so behavior
  stays consistent with every other OCT helper.
- ``load_octrc_safe(root)`` is exactly equivalent to
  ``load_octrc(root)[0]``.
- ``load_octrc`` never raises; errors are always returned as strings.
 
Dependencies
------------
- oct.core.option_c_dir (resolve_octrc path resolver)
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
import json
from pathlib import Path
 
from oct.core.option_c_dir import resolve_octrc
from oct.core.diagnostics import _dbg
 
 
OCTRC_FILENAME = ".octrc.json"
 
 
def load_octrc(project_root: Path) -> tuple[dict, list[str]]:
    """Load the project's OCT RC config (``.octrc.json`` / ``octrc.json``).
 
    FS-539: prefers ``.option_c/octrc.json`` when present, falls back to
    the legacy ``<project_root>/.octrc.json`` otherwise. The concrete
    path is resolved via :func:`oct.core.option_c_dir.resolve_octrc`.
 
    Returns
    -------
    (config, errors) : tuple[dict, list[str]]
        ``config`` is the parsed JSON object, or an empty dict if the file
        is missing / unreadable / malformed / not a JSON object.
        ``errors`` is a list of human-readable error strings; empty when
        the file was absent or loaded successfully.
    """
    func = "load_octrc"
    _dbg("OCT-CORE", func, f"loading octrc for {project_root}", 3)
    octrc_path = resolve_octrc(project_root)
    label = octrc_path.name  # "octrc.json" (modern) or ".octrc.json" (legacy)
    if not octrc_path.is_file():
        return {}, []
 
    try:
        raw = octrc_path.read_text(encoding="utf-8")
    except OSError as exc:
        return {}, [f"{label} unreadable: {exc}"]
 
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        return {}, [f"{label} has invalid JSON: {exc}"]
 
    if not isinstance(data, dict):
        return {}, [
            f"{label} must be a JSON object, got "
            f"{type(data).__name__}"
        ]
 
    return data, []
 
 
def load_octrc_safe(project_root: Path) -> dict:
    """Load ``.octrc.json`` quietly, returning ``{}`` on any failure."""
    func = "load_octrc_safe"
    _dbg("OCT-CORE", func, f"loading octrc (fail-soft) for {project_root}", 3)
    data, _errors = load_octrc(project_root)
    return data
 
 
__all__ = ["OCTRC_FILENAME", "load_octrc", "load_octrc_safe"]