option_c_dir.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/option_c_dir.py
 
"""
Purpose
-------
FS-539 - single source of truth for resolving paths to the canonical
``.option_c/`` project dotdir (introduced in v0.19.0) with a read-only
compat shim so projects that haven't run ``oct migrate .option_c``
keep working through the legacy layout:
 
  * ``.octrc.json``                      (legacy) → ``.option_c/octrc.json``
  * ``oc_diagnostics/debug_config.json`` (legacy) → ``.option_c/debug_config.json``
  * ``logs/``                            (legacy) → ``.option_c/logs/``
 
The resolvers always prefer the modern path when present and fall back
to the legacy path otherwise. They never raise on a missing file;
callers are expected to handle absent configs themselves (every OCT
config loader already does).
 
Responsibilities
----------------
- Define :data:`OPTION_C_DIRNAME`, :data:`OC_STATUS_FILENAME`, and
  :data:`VALID_STAGES` - the canonical names consumed across OCT.
- Provide pure path helpers (:func:`option_c_dir`,
  :func:`resolve_octrc`, :func:`resolve_debug_config`,
  :func:`resolve_logs_dir`) that never touch file contents beyond an
  ``is_file`` / ``is_dir`` existence check.
- Expose :class:`OcStatus` + :func:`load_oc_status` /
  :func:`write_oc_status` for the migration-state file
  (``oc_status.json``) that ``oct migrate``, ``oct audit``, and
  ``CLAUDE.md``'s compliance probe consume.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - (none) callers decide how to react to a missing path
    L3 - oc_status read and write entry, naming the project root
    L4 - octrc and debug-config path resolution
 
Contracts
---------
- All public helpers are pure: no network, no mutation outside of
  :func:`write_oc_status` which is explicitly a writer.
- Resolvers only stat the filesystem; they never read config contents,
  so they are safe to call during root discovery.
- :class:`OcStatus` validates ``stage`` at construction; other fields
  are stored as-is to keep the dataclass forwards-compatible with
  future schema extensions.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
import json
from dataclasses import asdict, dataclass, field
from pathlib import Path
from typing import Literal
from oct.core.diagnostics import _dbg
 
 
OPTION_C_DIRNAME: str = ".option_c"
OC_STATUS_FILENAME: str = "oc_status.json"
OC_STATUS_SCHEMA_VERSION: str = "1.0"
 
VALID_STAGES: tuple[str, ...] = ("bootstrap", "migrating", "compliant")
 
Stage = Literal["bootstrap", "migrating", "compliant"]
 
 
# ---------------------------------------------------------------------
# Path helpers
# ---------------------------------------------------------------------
 
 
def option_c_dir(project_root: Path) -> Path:
    """Return ``<project_root>/.option_c`` (existence not checked)."""
    return project_root / OPTION_C_DIRNAME
 
 
def resolve_octrc(project_root: Path) -> Path:
    """Return the path to ``.octrc.json``-equivalent for *project_root*.
 
    Prefers ``.option_c/octrc.json`` when present, else
    ``<project_root>/.octrc.json`` (legacy). The legacy path is also
    returned when neither file exists so the error message points the
    user at the file they're most likely looking for on an unmigrated
    project.
    """
    func = "resolve_octrc"
    _dbg("OCT-CORE", func, f"resolving octrc under {project_root}", 4)
    modern = option_c_dir(project_root) / "octrc.json"
    if modern.is_file():
        return modern
    return project_root / ".octrc.json"
 
 
def resolve_debug_config(project_root: Path) -> Path:
    """Return the path to ``debug_config.json`` for *project_root*.
 
    Preference order:
      1. ``.option_c/debug_config.json`` (post-FS-539)
      2. ``oc_diagnostics/debug_config.json`` (v0.17+)
      3. ``diagnostics/debug_config.json`` (pre-v0.17 legacy)
 
    When nothing exists, the ``oc_diagnostics/`` path is returned so
    callers get the most-commonly-expected missing-file location.
    """
    func = "resolve_debug_config"
    _dbg("OCT-CORE", func, f"resolving debug config under {project_root}", 4)
    modern = option_c_dir(project_root) / "debug_config.json"
    if modern.is_file():
        return modern
    oc_diag = project_root / "oc_diagnostics" / "debug_config.json"
    if oc_diag.is_file():
        return oc_diag
    very_legacy = project_root / "diagnostics" / "debug_config.json"
    if very_legacy.is_file():
        return very_legacy
    return oc_diag
 
 
def resolve_logs_dir(project_root: Path) -> Path:
    """Return the directory where OCT writes audit / run logs.
 
    Prefers ``.option_c/logs`` when present (i.e. on a migrated or
    freshly-scaffolded v0.19.0+ project where
    ``.option_c/`` already exists on disk), otherwise falls back to
    ``<project_root>/logs``. When neither exists, the legacy path is
    returned so that ad-hoc invocations from an unmigrated working tree
    don't spontaneously create a ``.option_c/`` side-effect - that
    creation is reserved for ``oct scaffold`` and ``oct migrate``.
    """
    modern = option_c_dir(project_root) / "logs"
    if modern.is_dir():
        return modern
    # Prefer the modern path only when .option_c/ itself exists (project
    # has been migrated / scaffolded) - then lazy-create the logs subdir
    # under it. On genuinely unmigrated projects, keep using root/logs/
    # so legacy callers don't see surprise directory creation.
    if option_c_dir(project_root).is_dir():
        return modern
    return project_root / "logs"
 
 
# ---------------------------------------------------------------------
# oc_status.json
# ---------------------------------------------------------------------
 
 
@dataclass
class OcStatus:
    """Parsed ``oc_status.json`` - the project's Option C compliance state.
 
    Fields mirror the on-disk JSON:
 
    ``stage``
        One of ``bootstrap`` / ``migrating`` / ``compliant`` - see
        :data:`VALID_STAGES`. Validated at construction.
    ``pillars``
        Per-pillar enablement dict (``linter``, ``diagnostics``, ``git``,
        ``docs``, ``tests``, ``scaffold``). Each entry is
        ``{"enabled": bool, "since": str | None}``.
    ``migrated_from``
        Legacy paths that were copied into ``.option_c/`` - kept for
        ``oct audit`` to cross-reference. Empty dict on fresh scaffolds.
    ``oct_version_at_migration``
        The ``importlib.metadata.version("oct")`` seen when the file was
        first written. Useful for audit trails and future schema bumps.
    """
 
    stage: Stage
    pillars: dict = field(default_factory=dict)
    migrated_from: dict = field(default_factory=dict)
    oct_version_at_migration: str = ""
 
    def __post_init__(self) -> None:
        if self.stage not in VALID_STAGES:
            raise ValueError(
                f"OcStatus.stage must be one of {VALID_STAGES}, got "
                f"{self.stage!r}"
            )
 
 
def load_oc_status(project_root: Path) -> OcStatus | None:
    """Return the parsed ``oc_status.json`` or ``None`` if missing/invalid.
 
    Missing-file, OSError, JSONDecodeError, and invalid-stage all
    collapse to ``None`` so callers (``oct audit``, CLAUDE.md probe,
    etc.) can treat "unmigrated" and "corrupt" identically - both
    require the user to re-run ``oct migrate .option_c``.
    """
    func = "load_oc_status"
    _dbg("OCT-CORE", func, f"reading oc_status under {project_root}", 3)
    path = option_c_dir(project_root) / OC_STATUS_FILENAME
    if not path.is_file():
        return None
    try:
        raw = path.read_text(encoding="utf-8")
        data = json.loads(raw)
    except (OSError, json.JSONDecodeError):
        return None
    if not isinstance(data, dict):
        return None
    stage = data.get("stage")
    if stage not in VALID_STAGES:
        return None
    try:
        return OcStatus(
            stage=stage,
            pillars=data.get("pillars", {}) or {},
            migrated_from=data.get("migrated_from", {}) or {},
            oct_version_at_migration=data.get("oct_version_at_migration", "") or "",
        )
    except (TypeError, ValueError):
        return None
 
 
def write_oc_status(project_root: Path, status: OcStatus) -> None:
    """Write *status* to ``<project_root>/.option_c/oc_status.json``.
 
    Creates ``.option_c/`` if it does not already exist. The on-disk
    JSON is pretty-printed (2-space indent) and prefixed with the
    ``_schema_version`` sentinel used elsewhere in OCT for
    forward-compatible schema evolution.
    """
    func = "write_oc_status"
    _dbg("OCT-CORE", func, f"writing oc_status under {project_root}", 3)
    target_dir = option_c_dir(project_root)
    target_dir.mkdir(parents=True, exist_ok=True)
 
    payload = {"_schema_version": OC_STATUS_SCHEMA_VERSION, **asdict(status)}
    text = json.dumps(payload, indent=2) + "\n"
    (target_dir / OC_STATUS_FILENAME).write_text(text, encoding="utf-8")
 
 
__all__ = [
    "OPTION_C_DIRNAME",
    "OC_STATUS_FILENAME",
    "OC_STATUS_SCHEMA_VERSION",
    "VALID_STAGES",
    "OcStatus",
    "option_c_dir",
    "resolve_octrc",
    "resolve_debug_config",
    "resolve_logs_dir",
    "load_oc_status",
    "write_oc_status",
]