log_writer.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/log_writer.py
 
"""
Purpose
-------
Write structured JSON command logs to the project's log directory.
 
Responsibilities
----------------
- Resolve the log directory via :func:`oct.core.option_c_dir.resolve_logs_dir`.
- Create the directory if it does not exist.
- Write JSON with a deterministic filename convention.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - (none) the write is reported at L3
    L3 - log write events
    L4 - (none)
 
Contracts
---------
- Always writes JSON (``indent=2``, UTF-8).
- Filename: ``oct-{command}-{YYYYMMDD-HHMMSS}.json``.
- Returns the written :class:`~pathlib.Path`.
 
Dependencies
------------
- oct.core.option_c_dir (resolve_logs_dir log-directory resolver)
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
import json
from datetime import datetime
from pathlib import Path
 
from oct.core.option_c_dir import resolve_logs_dir
from oct.core.diagnostics import _dbg
 
 
def write_command_log(project_root: Path, command: str, data: dict) -> Path:
    """Write *data* as JSON to the project log directory.
 
    Returns the path of the written file.
    """
    func = "write_command_log"
    _dbg("OCT-CORE", func, f"writing the {command} log under {project_root}", 3)
    log_dir = resolve_logs_dir(project_root)
    log_dir.mkdir(parents=True, exist_ok=True)
    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
    log_path = log_dir / f"oct-{command}-{stamp}.json"
    log_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
    return log_path