oct_audit.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/audit/oct_audit.py
 
"""
Purpose
-------
FS-539 / FS-501 (stub) - ``oct audit`` reads ``oc_status.json`` and
reports the project's Option C compliance stage.
 
This is the minimal landing surface that ``CLAUDE.md``'s compliance
probe and CI scripts consume. The full audit suite (schema drift,
scaffold age, doc/version mismatch, MCP readiness) lands in Phase 6.
 
Responsibilities
----------------
- Locate the project root and read ``oc_status.json`` from the
  ``.option_c/`` directory when one exists.
- Map the recorded ``stage`` onto the process exit code below, so a CI
  script or the ``CLAUDE.md`` compliance probe can branch on it without
  parsing text.
- Report the stage in human-readable form, or as JSON under
  ``--json-output`` for machine consumers.
- Treat an absent ``oc_status.json`` as a distinct outcome (exit 3)
  rather than an error: an unmigrated project is a legitimate state.
 
Exit codes
----------
    0  - compliant
    1  - migrating
    2  - bootstrap
    3  - no oc_status.json found (unmigrated project)
 
Diagnostics
-----------
Domain: AUDIT
Levels:
    L1 - errors: none; an unreadable or absent status file is exit 3
    L2 - lifecycle: audit entry and the resolved stage
    L3 - semantic: the status path probed and the stage read from it
    L4 - deep tracing: the raw status payload
 
Contracts
---------
- Read-only against the project tree; never writes.
- Exit code is derived from ``oc_status.json`` ``stage`` (or 3 when absent).
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.option_c_dir (load_oc_status, option_c_dir)
- oct.core.project_root (project root detection)
- click (CLI framework)
"""
 
from __future__ import annotations
 
import json
from dataclasses import asdict, dataclass
from pathlib import Path
 
import click
 
from oct.core.diagnostics import _dbg
from oct.core.option_c_dir import load_oc_status, option_c_dir
from oct.core.project_root import get_project_root
 
 
_STAGE_EXIT_CODES: dict[str, int] = {
    "compliant": 0,
    "migrating": 1,
    "bootstrap": 2,
}
 
 
@dataclass
class AuditResult:
    """Structured output from :func:`run_audit`."""
 
    stage: str | None
    pillars: dict
    migrated_from: dict
    oct_version_at_migration: str
    exit_code: int
 
 
def run_audit(project_root: Path) -> AuditResult:
    """Read ``oc_status.json`` and return structured audit information."""
    func = "run_audit"
    _dbg("AUDIT", func, f"start root={project_root}", 2)
 
    status = load_oc_status(project_root)
    if status is None:
        has_dotdir = option_c_dir(project_root).is_dir()
        _dbg(
            "AUDIT", func,
            f"no oc_status.json; .option_c exists={has_dotdir}",
            2,
        )
        return AuditResult(
            stage=None,
            pillars={},
            migrated_from={},
            oct_version_at_migration="",
            exit_code=3,
        )
 
    exit_code = _STAGE_EXIT_CODES.get(status.stage, 3)
    _dbg("AUDIT", func, f"end stage={status.stage} exit={exit_code}", 2)
 
    return AuditResult(
        stage=status.stage,
        pillars=status.pillars,
        migrated_from=status.migrated_from,
        oct_version_at_migration=status.oct_version_at_migration,
        exit_code=exit_code,
    )
 
 
# -- Click surface -------------------------------------------------------
 
@click.command()
@click.option("--json-output", "as_json", is_flag=True, help="Emit JSON instead of human-readable text.")
@click.pass_context
def audit(ctx: click.Context, as_json: bool) -> None:
    """Report Option C compliance stage (stub for FS-501)."""
    project_root = get_project_root(ctx)
    result = run_audit(project_root)
 
    if as_json:
        payload = {
            "stage": result.stage,
            "pillars": result.pillars,
            "migrated_from": result.migrated_from,
            "oct_version_at_migration": result.oct_version_at_migration,
            "exit_code": result.exit_code,
        }
        click.echo(json.dumps(payload, indent=2))
    else:
        if result.stage is None:
            click.echo("Stage: unmigrated (no .option_c/oc_status.json)")
        else:
            click.echo(f"Stage: {result.stage}")
            for name, info in result.pillars.items():
                enabled = info.get("enabled", False)
                marker = "+" if enabled else "-"
                click.echo(f"  [{marker}] {name}")
            if result.migrated_from:
                click.echo("Migrated from:")
                for label, src in result.migrated_from.items():
                    click.echo(f"  {label}: {src}")
 
    raise SystemExit(result.exit_code)