oct_health.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/health/oct_health.py
 
"""
Option C project health dashboard implementation.
 
Purpose
-------
Provide a single-command compliance dashboard that aggregates lint results,
fixable violations, documentation status, test status, and oc_diagnostics
compatibility into one report.
 
Responsibilities
----------------
- Run linter checks on all Python files and aggregate statistics.
- Run formatter checks in dry-run mode to count fixable violations.
- Validate presence of required documentation files.
- Run project tests and capture pass/fail status.
- Check oc_diagnostics version compatibility.
- Output results as terminal report or JSON.
 
Diagnostics
-----------
Domain: OCT.HEALTH
Levels:
    L2 — health check lifecycle and command routing
    L3 — individual check categories (lint, docs, tests, compat)
    L4 — per-file analysis and detailed aggregation
 
Contracts
---------
- Health checks are read-only; no files are modified.
- All checks are independent; failure of one does not prevent others.
- JSON output is always valid JSON with a stable schema.
- Terminal output uses ASCII-safe characters for Windows compatibility.
 
Dependencies
------------
- oct (package version)
- oct.core.progress (terminal dashboard renderer)
- oct.core.parsing (safe AST parsing helper)
- oct.core.paths (project-relative path helper)
- oct.linter.oct_lint (reused validation checks and profile defaults)
- oct.core.exclusions (directory and wildcard exclusion lists)
- oct.core.project_root (project root detection)
- oct.core.compat (oc_diagnostics version compatibility check)
- oct.core.octrc (.octrc.json loader)
- oct.core.terminal (ANSI colour helpers)
"""
 
import json
import re
import subprocess
import sys
from dataclasses import dataclass, field, asdict
from datetime import datetime
from pathlib import Path
from typing import Dict, List, Any, Optional
 
from oct import __version__
from oct.core.progress import Dashboard
from oct.core.parsing import safe_parse
from oct.core.paths import to_project_relative
from oct.linter.oct_lint import (
    validate_header_block,
    check_docstring,
    check_dependencies_section,
    check_diagnostics_profile,
    check_dbg_usage,
    check_dbg_import,
    check_func_pattern,
    check_syntax_warnings,
    find_python_files,
    LinterContext,
    _DEFAULT_RULES,
    _PROFILES,
)
from oct.core.exclusions import LINTER_EXCLUDE_DIRS, WILDCARD_EXCLUDE_DIRS
from oct.core.project_root import find_project_root
from oct.core.compat import check_oc_diagnostics_compat
from oct.core.octrc import load_octrc_safe
from oct.core.terminal import CYAN, GREEN, RED, YELLOW, RESET
 
 
# ============================================================================
# Health Check Functions
# ============================================================================
 
 
def check_lint_health(
    project_root: Path,
    ctx: LinterContext,
    verbose: bool = False,
    exclude_dirs: Optional[set] = None,
    wildcard_exclude: Optional[list] = None,
    active_rules: Optional[dict] = None,
) -> Dict[str, Any]:
    """
    Run linter checks on all Python files and aggregate pass/fail statistics.
 
    Returns a dict with total_files, fully_compliant count, per-check pass
    counts, and compliance percentage.
    """
    func = "check_lint_health"
 
    if exclude_dirs is None:
        exclude_dirs = set(LINTER_EXCLUDE_DIRS)
    if wildcard_exclude is None:
        wildcard_exclude = list(WILDCARD_EXCLUDE_DIRS)
    if active_rules is None:
        active_rules = dict(_DEFAULT_RULES)
 
    python_files = list(find_python_files(project_root, exclude_dirs, wildcard_exclude))
 
    # Build counters only for active rules (excluding tests_exist which health doesn't check)
    health_checks = [
        "header", "docstring", "dependencies_section", "diagnostics_profile",
        "dbg_usage", "dbg_import", "func_pattern", "syntax_warnings",
    ]
    active_checks = [c for c in health_checks if active_rules.get(c, True)]
 
    total = len(python_files)
    counters = {c: 0 for c in active_checks}
    fully_compliant = 0
    file_details = []
 
    check_funcs = {
        "header": lambda text, lines, py_file, tree, sw: validate_header_block(
            lines[:4] if len(lines) >= 4 else lines, py_file, ctx),
        "docstring": lambda text, lines, py_file, tree, sw: check_docstring(text),
        "dependencies_section": lambda text, lines, py_file, tree, sw: check_dependencies_section(text),
        "diagnostics_profile": lambda text, lines, py_file, tree, sw: check_diagnostics_profile(text),
        "dbg_usage": lambda text, lines, py_file, tree, sw: check_dbg_usage(text, tree=tree),
        "dbg_import": lambda text, lines, py_file, tree, sw: check_dbg_import(text, tree=tree),
        "func_pattern": lambda text, lines, py_file, tree, sw: check_func_pattern(text, tree=tree),
        "syntax_warnings": lambda text, lines, py_file, tree, sw: check_syntax_warnings(text, warnings_list=sw),
    }
 
    for py_file in python_files:
        try:
            text = py_file.read_text(encoding="utf-8")
        except Exception:
            continue
 
        lines = text.split('\n')
        tree, syntax_warnings_list = safe_parse(text)
 
        checks = {}
        for check_name in active_checks:
            ok, _ = check_funcs[check_name](text, lines, py_file, tree, syntax_warnings_list)
            checks[check_name] = ok
            if ok:
                counters[check_name] += 1
 
        if all(checks.values()):
            fully_compliant += 1
 
        if verbose:
            rel_path = to_project_relative(py_file, project_root)
            file_details.append({
                "path": rel_path,
                "checks": checks,
                "compliant": all(checks.values()),
            })
 
    compliance_pct = round((fully_compliant / total * 100), 1) if total > 0 else 0.0
 
    result = {
        "total_files": total,
        "fully_compliant": fully_compliant,
        "compliance_pct": compliance_pct,
        "checks": {},
    }
 
    for check_name, count in counters.items():
        pct = round((count / total * 100), 1) if total > 0 else 0.0
        result["checks"][check_name] = {
            "pass": count,
            "total": total,
            "pct": pct,
        }
 
    if verbose:
        result["files"] = file_details
 
    return result
 
 
def check_fixable_health(
    project_root: Path,
    ctx: LinterContext,
    exclude_dirs: Optional[set] = None,
    wildcard_exclude: Optional[list] = None,
    active_rules: Optional[dict] = None,
    verbose: bool = False,
) -> Dict[str, Any]:
    """
    Count violations that oct format could fix automatically.
 
    Runs formatter checks in dry-run mode (no modifications).
    Only counts fixes for rules that are active.
 
    When *verbose* is True the result includes a ``"files"`` key mapping
    to a list of ``{"path": <rel_path>, "fixes": [<fix_name>, ...]}``
    entries so the caller can show which files have fixable violations.
    """
    func = "check_fixable_health"
 
    from oct.formatter.oct_format import (
        fix_header_block,
        fix_docstring,
        fix_dbg_import,
        fix_func_pattern,
        FormatterContext,
    )
 
    if active_rules is None:
        active_rules = dict(_DEFAULT_RULES)
 
    fmt_ctx = FormatterContext(
        project_root=project_root,
        project_name=project_root.name,
        diagnostics_dir=ctx.diagnostics_dir,
        tests_dir=ctx.tests_dir,
        docs_dir=ctx.docs_dir,
        fix_mode=False,
        dry_run_mode=True,
        json_mode=False,
        verbose=False,
    )
 
    if exclude_dirs is None:
        exclude_dirs = set(LINTER_EXCLUDE_DIRS)
    if wildcard_exclude is None:
        wildcard_exclude = list(WILDCARD_EXCLUDE_DIRS)
    python_files = list(find_python_files(project_root, exclude_dirs, wildcard_exclude))
 
    # Map fixable check names to their corresponding lint rule names
    fix_rule_map = {
        "header": "header",
        "docstring": "docstring",
        "dbg_import": "dbg_import",
        "func_pattern": "func_pattern",
    }
    fixable = {k: 0 for k in fix_rule_map if active_rules.get(fix_rule_map[k], True)}
 
    fix_funcs = {
        "header": fix_header_block,
        "docstring": fix_docstring,
        "dbg_import": fix_dbg_import,
        "func_pattern": fix_func_pattern,
    }
 
    file_details: list[dict] = []
 
    for py_file in python_files:
        try:
            text = py_file.read_text(encoding="utf-8")
        except Exception:
            continue
 
        file_fixes: list[str] = []
        for fix_name in fixable:
            changed, _, _ = fix_funcs[fix_name](py_file, text, fmt_ctx)
            if changed:
                fixable[fix_name] += 1
                file_fixes.append(fix_name)
 
        if verbose and file_fixes:
            rel_path = to_project_relative(py_file, project_root)
            file_details.append({"path": rel_path, "fixes": file_fixes})
 
    fixable["total"] = sum(fixable.values())
    if verbose:
        fixable["files"] = file_details
    return fixable
 
 
def check_docs_health(
    project_root: Path,
    *,
    production_mode: bool = False,
) -> Dict[str, Any]:
    """
    Validate presence of required documentation files.
 
    Standard required set: ARCHITECTURE.md, CHANGELOG.md, Tests_README.md,
    run_tests.py, debug_config.json. When ``production_mode=True`` (Appendix H
    Level 2), SECURITY.md is also required; otherwise it is reported as
    optional alongside the required count.
    """
    func = "check_docs_health"
 
    base_required = [
        ("ARCHITECTURE.md", project_root / "docs" / "ARCHITECTURE.md"),
        ("CHANGELOG.md", project_root / "CHANGELOG.md"),
        ("Tests_README.md", project_root / "tests" / "Tests_README.md"),
        ("run_tests.py", project_root / "tests" / "run_tests.py"),
        ("debug_config.json", project_root / "oc_diagnostics" / "debug_config.json"),
    ]
    production_only = [
        ("SECURITY.md", project_root / "SECURITY.md"),
    ]
 
    required_files = base_required + (production_only if production_mode else [])
    optional_files = [] if production_mode else production_only
 
    files_status = []
    present_count = 0
 
    for name, path in required_files:
        exists = path.is_file()
        files_status.append({"name": name, "present": exists, "required": True})
        if exists:
            present_count += 1
 
    for name, path in optional_files:
        exists = path.is_file()
        files_status.append({"name": name, "present": exists, "required": False})
 
    return {
        "total_required": len(required_files),
        "total_present": present_count,
        "files": files_status,
        "production_mode": production_mode,
    }
 
 
_COVERAGE_TOTAL_RE = re.compile(r"^TOTAL\s+\d+\s+\d+\s+(\d+(?:\.\d+)?)%", re.MULTILINE)
 
 
def check_test_health(
    project_root: Path,
    timeout: int = 300,
    *,
    coverage_threshold: Optional[float] = None,
    production_mode: bool = False,
    coverage_target: Optional[str] = None,
) -> Dict[str, Any]:
    """
    Run project tests and capture pass/fail status.
 
    Uses pytest subprocess to run tests and captures the exit code
    and summary line.
 
    Parameters
    ----------
    project_root:
        Path to the project root containing a ``tests/`` directory.
    timeout:
        Maximum seconds to wait for pytest to complete. Default 300 (OI-413).
    coverage_threshold:
        FS-C3 / Drift item C3 — when set, run pytest with ``--cov`` and
        compare the resulting TOTAL coverage percentage against this
        threshold. ``None`` (default) skips the coverage measurement
        entirely so existing CI keeps its prior behaviour.
    production_mode:
        When ``True`` together with a ``coverage_threshold``, a coverage
        result below the threshold flips ``status`` to ``"fail"``.
        Outside production mode, below-threshold coverage is reported
        but never blocks the dashboard.
    coverage_target:
        Module / package name to measure (passed as ``--cov=<target>``).
        Defaults to the project root directory name when ``None``.
    """
    func = "check_test_health"
 
    import importlib.util
 
    tests_dir = project_root / "tests"
    if not tests_dir.is_dir():
        return {
            "status": "not_run",
            "exit_code": -1,
            "summary": "No tests/ directory found",
            "details": [],
            "coverage_pct": None,
            "coverage_threshold": coverage_threshold,
            "coverage_blocking": production_mode,
        }
 
    # Detect missing pytest before attempting subprocess — avoids silent FAIL
    if importlib.util.find_spec("pytest") is None:
        return {
            "status": "fail",
            "exit_code": -1,
            "summary": "pytest not installed — run: pip install pytest",
            "details": [],
            "coverage_pct": None,
            "coverage_threshold": coverage_threshold,
            "coverage_blocking": production_mode,
        }
 
    # FS-C3: when coverage measurement is requested, ensure pytest-cov is
    # available; degrade gracefully (run without --cov) when missing.
    coverage_requested = coverage_threshold is not None
    coverage_available = (
        coverage_requested
        and importlib.util.find_spec("pytest_cov") is not None
    )
 
    pytest_args = [
        sys.executable, "-m", "pytest", str(tests_dir),
        "-n", "auto", "--dist=worksteal", "--tb=line", "--no-header",
    ]
    if coverage_available:
        target = coverage_target or project_root.name
        pytest_args.extend([f"--cov={target}", "--cov-report=term"])
 
    try:
        result = subprocess.run(
            pytest_args,
            capture_output=True,
            text=True,
            encoding="utf-8",
            errors="replace",
            timeout=timeout,
            cwd=str(project_root),
        )
 
        # Extract summary line — scan from end since pytest always puts it last.
        # Match on keywords OR the timing pattern ("N passed in 0.31s") as a fallback
        # since encoding issues can occasionally mangle keyword characters on Windows.
        _SUMMARY_RE = re.compile(r"\b\d+ \w+ in [\d.]+s")
        _DECORATION_RE = re.compile(r"^=+\s*|\s*=+$")
        summary = ""
        for line in reversed(result.stdout.strip().split('\n')):
            line = line.strip()
            if "passed" in line or "failed" in line or "error" in line or _SUMMARY_RE.search(line):
                summary = _DECORATION_RE.sub("", line).strip()
                break
 
        # Extract actionable error detail lines (max 5) from --tb=line output.
        # pytest --tb=line produces lines like:
        #   path/to/test.py - ErrorType: message
        #   FAILED tests/test_foo.py::test_bar - AssertionError
        detail_lines = []
        if result.returncode != 0:
            for line in result.stdout.strip().split('\n'):
                line = line.strip()
                if not line or line.startswith("=") or line.startswith("."):
                    continue
                if ("Error" in line or "Exception" in line
                        or line.startswith("FAILED ")
                        or line.startswith("ERROR ")):
                    detail_lines.append(line)
                    if len(detail_lines) >= 5:
                        break
 
        # Fall back to stderr when stdout has no useful summary (e.g. import errors)
        if not summary and result.stderr.strip():
            err_lines = result.stderr.strip().split('\n')
            summary = err_lines[-1].strip()
 
        # Tertiary fallback — always provide a summary even if regex + stderr both fail
        if not summary:
            summary = f"pytest exited with code {result.returncode}"
 
        status = "pass" if result.returncode == 0 else "fail"
 
        # FS-C3: parse pytest-cov "TOTAL ... NN%" line when coverage was requested.
        coverage_pct: Optional[float] = None
        if coverage_available:
            cov_match = _COVERAGE_TOTAL_RE.search(result.stdout)
            if cov_match:
                try:
                    coverage_pct = float(cov_match.group(1))
                except ValueError:
                    coverage_pct = None
 
        # Production-mode gating: a coverage result below threshold flips
        # status to "fail" only when production_mode is set. Outside
        # production, below-threshold coverage is informational.
        if (
            production_mode
            and coverage_pct is not None
            and coverage_threshold is not None
            and coverage_pct < coverage_threshold
            and status == "pass"
        ):
            status = "fail"
            summary = (
                f"{summary} | coverage {coverage_pct:.1f}% below "
                f"production threshold {coverage_threshold:.1f}%"
            ).strip()
 
        # Surface a clear diagnostic when the user asked for coverage but
        # pytest-cov isn't installed.
        coverage_msg: Optional[str] = None
        if coverage_requested and not coverage_available:
            coverage_msg = (
                "pytest-cov not installed — install with: "
                "pip install -e .[test]"
            )
 
        return {
            "status": status,
            "exit_code": result.returncode,
            "summary": summary,
            "details": detail_lines,
            "coverage_pct": coverage_pct,
            "coverage_threshold": coverage_threshold,
            "coverage_blocking": production_mode,
            "coverage_message": coverage_msg,
        }
 
    except subprocess.TimeoutExpired:
        return {
            "status": "timeout",
            "exit_code": -1,
            "summary": f"Tests timed out after {timeout} seconds",
            "details": [],
            "coverage_pct": None,
            "coverage_threshold": coverage_threshold,
            "coverage_blocking": production_mode,
        }
    except Exception as e:
        return {
            "status": "error",
            "exit_code": -1,
            "summary": str(e),
            "details": [],
            "coverage_pct": None,
            "coverage_threshold": coverage_threshold,
            "coverage_blocking": production_mode,
        }
 
 
def check_compat_health() -> Dict[str, Any]:
    """
    Check oc_diagnostics version compatibility.
    """
    func = "check_compat_health"
 
    msg = check_oc_diagnostics_compat()
 
    try:
        from importlib.metadata import version as _pkg_version
        version = _pkg_version("oc_diagnostics")
        installed = True
    except Exception:
        version = "not installed"
        installed = False
 
    return {
        "installed": installed,
        "version": version,
        "compatible": msg is None or msg == "",
        "message": msg or "",
    }
 
 
def check_venv_health(project_root: Path) -> Dict[str, Any]:
    """
    Check virtual environment status for the project.
 
    Performs three layered checks:
    1. Whether the current process is running inside *any* venv.
    2. Whether a canonical ``.venv`` directory exists at the project root or its
       immediate parent (monorepo pattern: shared venv one level above subproject).
    3. Whether the active venv is the project's own ``.venv`` (not a foreign env).
 
    Returns a dict with ``status`` (OK / WARN / FAIL), ``active`` (bool),
    ``venv_found`` (bool), ``active_path`` (str | None), and ``message`` (str).
    """
    func = "check_venv_health"  # noqa: F841 - Option C func pattern
 
    in_venv: bool = sys.prefix != sys.base_prefix
    active_path: Optional[str] = sys.prefix if in_venv else None
 
    # Probe subproject root first, then repo root (monorepo: oct/ lives inside
    # Option_C/ which owns the shared .venv).
    canonical_venv: Optional[Path] = None
    for _candidate in (project_root / ".venv", project_root.parent / ".venv"):
        if _candidate.is_dir():
            canonical_venv = _candidate
            break
    venv_found: bool = canonical_venv is not None
 
    # Is the active venv the project's own .venv?
    own_venv = False
    if in_venv and venv_found and canonical_venv is not None:
        try:
            own_venv = Path(sys.prefix).resolve() == canonical_venv.resolve()
        except Exception:
            own_venv = False
 
    if not in_venv:
        status = "WARN"
        message = (
            "Not running inside a virtual environment. "
            "Run: .venv\\Scripts\\activate (Windows) or source .venv/bin/activate (Unix)"
        )
    elif not venv_found:
        status = "WARN"
        message = (
            f"Active venv: {active_path}. "
            "No .venv/ found at project root or repo root -- "
            "create one with: python -m venv .venv"
        )
    elif not own_venv:
        status = "WARN"
        message = (
            f"Active venv ({active_path}) is not the project .venv "
            f"({canonical_venv}). Activate the correct venv for dependency isolation."
        )
    else:
        status = "OK"
        message = f"Project .venv active ({active_path})"
 
    return {
        "status": status,
        "active": in_venv,
        "venv_found": venv_found,
        "own_venv": own_venv,
        "active_path": active_path,
        "venv_path": str(canonical_venv) if canonical_venv else None,
        "message": message,
    }
 
 
# ============================================================================
# Git Health (Phase 4E — G-E5)
# ============================================================================
 
 
def check_git_health(project_root: Path) -> Dict[str, Any]:
    """Run git-related health checks.
 
    Returns a dict of checks, each with ``status`` (OK / WARN / SKIP)
    and ``detail``.  If git is not installed or the project is not a
    repo, all items return SKIP with an explanatory message.
    """
    import shutil
 
    checks: Dict[str, Dict[str, str]] = {}
 
    # Guard: git installed?
    if shutil.which("git") is None:
        skip = {"status": "SKIP", "detail": "Git is not installed"}
        return {
            "is_repo": skip,
            "branch": skip,
            "naming_conformant": skip,
            "clean_worktree": skip,
            "ahead_behind": skip,
            "hooks_installed": skip,
            "last_commit_conventional": skip,
        }
 
    try:
        from oct.core.git import (
            is_git_repo,
            current_branch,
            has_uncommitted_changes,
            last_commit_message,
            ahead_behind as _ahead_behind,
        )
    except ImportError:
        skip = {"status": "SKIP", "detail": "oct.core.git not available"}
        return {
            "is_repo": skip,
            "branch": skip,
            "naming_conformant": skip,
            "clean_worktree": skip,
            "ahead_behind": skip,
            "hooks_installed": skip,
            "last_commit_conventional": skip,
        }
 
    # is_repo
    if not is_git_repo(project_root):
        skip = {"status": "SKIP", "detail": "Not a git repository"}
        return {
            "is_repo": {"status": "FAIL", "detail": "Not a git repository. Run 'oct git init' to initialise."},
            "branch": skip,
            "naming_conformant": skip,
            "clean_worktree": skip,
            "ahead_behind": skip,
            "hooks_installed": skip,
            "last_commit_conventional": skip,
        }
 
    checks["is_repo"] = {"status": "OK", "detail": "Git repository detected"}
 
    # branch
    try:
        branch = current_branch(project_root)
        if branch == "HEAD":
            checks["branch"] = {"status": "WARN", "detail": "Detached HEAD"}
        else:
            checks["branch"] = {"status": "OK", "detail": branch}
    except Exception:
        branch = None
        checks["branch"] = {"status": "WARN", "detail": "Could not determine branch"}
 
    # naming_conformant
    try:
        from oct.git.policy import validate_branch_name
        valid, msg = validate_branch_name(branch, _load_octrc_for_health(project_root))
        if valid:
            checks["naming_conformant"] = {"status": "OK", "detail": "Branch name conforms to naming convention"}
        else:
            checks["naming_conformant"] = {"status": "WARN", "detail": msg}
    except Exception:
        checks["naming_conformant"] = {"status": "SKIP", "detail": "Could not validate branch name"}
 
    # clean_worktree
    try:
        dirty = has_uncommitted_changes(project_root)
        if dirty:
            checks["clean_worktree"] = {"status": "WARN", "detail": "Uncommitted changes present"}
        else:
            checks["clean_worktree"] = {"status": "OK", "detail": "Working tree is clean"}
    except Exception:
        checks["clean_worktree"] = {"status": "SKIP", "detail": "Could not check worktree"}
 
    # ahead_behind
    try:
        ahead, behind = _ahead_behind(project_root)
        if ahead == 0 and behind == 0:
            checks["ahead_behind"] = {"status": "OK", "detail": "Up to date with remote"}
        else:
            parts = []
            if ahead:
                parts.append(f"{ahead} ahead")
            if behind:
                parts.append(f"{behind} behind")
            checks["ahead_behind"] = {"status": "WARN", "detail": ", ".join(parts)}
    except Exception:
        checks["ahead_behind"] = {"status": "OK", "detail": "No upstream configured"}
 
    # hooks_installed
    config_path = project_root / ".pre-commit-config.yaml"
    if config_path.is_file():
        try:
            content = config_path.read_text(encoding="utf-8")
            oct_hooks = ["oct-quality-gate", "oct-secrets-check", "oct-commit-msg", "oct-pre-push"]
            found = [h for h in oct_hooks if f"id: {h}" in content]
            if len(found) == len(oct_hooks):
                checks["hooks_installed"] = {"status": "OK", "detail": f"All {len(oct_hooks)} hooks installed"}
            else:
                missing = [h for h in oct_hooks if h not in found]
                checks["hooks_installed"] = {"status": "WARN", "detail": f"Missing: {', '.join(missing)}"}
        except Exception:
            checks["hooks_installed"] = {"status": "WARN", "detail": "Could not read hooks config"}
    else:
        checks["hooks_installed"] = {"status": "WARN", "detail": "No .pre-commit-config.yaml found"}
 
    # last_commit_conventional
    try:
        from oct.git.conventional import parse_commit_message
        msg = last_commit_message(project_root)
        if not msg:
            checks["last_commit_conventional"] = {"status": "SKIP", "detail": "No commits yet"}
        elif parse_commit_message(msg) is not None:
            checks["last_commit_conventional"] = {"status": "OK", "detail": "Last commit follows Conventional Commits"}
        else:
            checks["last_commit_conventional"] = {"status": "WARN", "detail": "Last commit is not Conventional Commits format"}
    except Exception:
        checks["last_commit_conventional"] = {"status": "SKIP", "detail": "Could not check last commit"}
 
    return checks
 
 
def _load_octrc_for_health(project_root: Path) -> Optional[dict]:
    """Load ``.octrc.json`` for health checks (best-effort).
 
    OI-519: thin wrapper around :func:`oct.core.octrc.load_octrc_safe`;
    retains the historical ``None`` return on missing/invalid so existing
    callers keep their truthy-check semantics.
    """
    from oct.core.octrc import load_octrc_safe
    from oct.core.option_c_dir import resolve_octrc
    # FS-539: the octrc may live at .option_c/octrc.json (modern) or
    # .octrc.json (legacy) — resolve_octrc picks whichever exists and
    # returns the legacy path when neither does, giving us a truthy
    # existence check either way.
    if not resolve_octrc(project_root).is_file():
        return None
    data = load_octrc_safe(project_root)
    return data or None
 
 
# ============================================================================
# Output Formatting
# ============================================================================
 
 
# Lint checks shown in the health dashboard (subset of all lint rules).
_HEALTH_CHECKS = [
    "header", "docstring", "diagnostics_profile",
    "dbg_usage", "dbg_import", "func_pattern", "syntax_warnings",
]
 
# Fixable categories and their display labels.
_FIX_LABELS: Dict[str, str] = {
    "header": "Header blocks",
    "docstring": "Docstrings",
    "dbg_import": "_dbg imports",
    "func_pattern": "func patterns",
}
 
# Documentation files surfaced in the dashboard. CHANGELOG.md is required at
# Standard maturity; SECURITY.md is required only at Production maturity but is
# always shown in the dashboard so its absence is visible.
_DOC_FILES = [
    "ARCHITECTURE.md",
    "CHANGELOG.md",
    "Tests_README.md",
    "run_tests.py",
    "debug_config.json",
    "SECURITY.md",
]
 
# Git check keys and display labels.
_GIT_LABELS: Dict[str, str] = {
    "is_repo": "Repository",
    "branch": "Branch",
    "naming_conformant": "Branch naming",
    "clean_worktree": "Working tree",
    "ahead_behind": "Remote sync",
    "hooks_installed": "Hooks",
    "last_commit_conventional": "Last commit",
}
 
 
@dataclass
class _HealthLineMap:
    """Maps dashboard sections to line indices for in-place updates."""
    lint: int = 0
    lint_checks: Dict[str, int] = field(default_factory=dict)
    fixable: int = 0
    fixable_items: Dict[str, int] = field(default_factory=dict)
    docs: int = 0
    docs_files: Dict[str, int] = field(default_factory=dict)
    tests: int = 0
    compat: int = 0
    venv: int = 0
    git: int = 0
    git_checks: Dict[str, int] = field(default_factory=dict)
    footer: int = 0
 
 
def _build_health_template(
    project_name: str,
    excluded_dirs: List[str],
    disabled_rules: List[str],
    active_checks: List[str],
    fixable_names: List[str],
    use_color: bool,
) -> tuple:
    """Build the dashboard template lines and line-index map.
 
    Returns ``(lines, line_map)`` where *lines* is a list of strings and
    *line_map* is a :class:`_HealthLineMap` with indices into that list.
    """
    C = "\033[96m" if use_color else ""
    X = "\033[0m" if use_color else ""
    lm = _HealthLineMap()
    lines: List[str] = []
 
    def add(text: str = "") -> int:
        idx = len(lines)
        lines.append(text)
        return idx
 
    # Header
    add(f"{C}{'=' * 70}{X}")
    add(f"{C}OCT HEALTH REPORT -- {project_name}{X}")
    add(f"{C}{'=' * 70}{X}")
    add()
 
    # Config overrides
    if excluded_dirs:
        add(f"Excluded directories: {', '.join(excluded_dirs)} (via .octrc.json)")
    if disabled_rules:
        labels = [r.replace("_", " ") for r in disabled_rules]
        add(f"Disabled rules:       {', '.join(labels)} (via .octrc.json)")
    if excluded_dirs or disabled_rules:
        add()
 
    # Lint compliance
    lm.lint = add("[ ] Lint Compliance:")
    for ck in active_checks:
        label = ck.replace("_", " ").title()
        lm.lint_checks[ck] = add(f"  [ ] {label + ':':<20}")
    add()
 
    # Fixable violations
    lm.fixable = add("[ ] Fixable Violations:")
    for fn in fixable_names:
        lm.fixable_items[fn] = add(f"  [ ] {_FIX_LABELS.get(fn, fn) + ':':<20}")
    add()
 
    # Documentation
    lm.docs = add("[ ] Documentation:")
    for df in _DOC_FILES:
        lm.docs_files[df] = add(f"  [ ] {df}")
    add()
 
    # Tests
    lm.tests = add("[ ] Tests:")
    add()
 
    # Compatibility
    lm.compat = add("[ ] oc_diagnostics:")
    add()
 
    # Virtual environment
    lm.venv = add("[ ] Virtual Env:")
    add()
 
    # Git integration
    lm.git = add("[ ] Git Integration:")
    for gk, gl in _GIT_LABELS.items():
        lm.git_checks[gk] = add(f"  [ ] {gl + ':':<20}")
    add()
 
    # Footer
    lm.footer = add("  Waiting to start...")
    add()
    add(f"{C}{'=' * 70}{X}")
 
    return lines, lm
 
 
def _pct_str(count: int, total: int) -> str:
    """Format count/total with percentage."""
    if total == 0:
        return "0/0 (0.0%)"
    pct = round(count / total * 100, 1)
    return f"{count}/{total} ({pct}%)"
 
 
def _print_terminal_report(report: Dict[str, Any], verbose: bool) -> None:
    """Print human-readable terminal health report."""
    func = "_print_terminal_report"
 
    lint = report["lint"]
    fixable = report["fixable"]
    docs = report["docs"]
    tests = report["tests"]
    compat = report["compat"]
 
    print(f"\n{CYAN}{'=' * 70}{RESET}")
    print(f"{CYAN}OCT HEALTH REPORT -- {report['project']}{RESET}")
    print(f"{CYAN}{'=' * 70}{RESET}\n")
 
    # FS-504: prominent top-of-report banner when running outside a venv.
    # Kept as WARN (not FAIL) so CI consumers can still exit 0; the banner
    # is what turns "venv missing" from an easily-missed per-section note
    # into something the operator cannot overlook.
    venv_data = report.get("venv") or {}
    if venv_data.get("active") is False:
        print(f"{YELLOW}{'!' * 70}{RESET}")
        print(f"{YELLOW}WARNING: not running inside a virtual environment.{RESET}")
        print(f"{YELLOW}Create one with:  python -m venv .venv && activate{RESET}")
        print(f"{YELLOW}{'!' * 70}{RESET}\n")
 
    # Config overrides (from .octrc.json)
    excluded = report.get("excluded_dirs", [])
    disabled = report.get("disabled_rules", [])
    if excluded:
        print(f"Excluded directories: {YELLOW}{', '.join(excluded)}{RESET} (via .octrc.json)")
    if disabled:
        labels = [r.replace("_", " ") for r in disabled]
        print(f"Disabled rules:       {YELLOW}{', '.join(labels)}{RESET} (via .octrc.json)")
    if excluded or disabled:
        print()
 
    # Lint compliance
    total = lint["total_files"]
    compliant = lint["fully_compliant"]
    pct = lint["compliance_pct"]
    pct_color = GREEN if pct == 100.0 else RED
    print(f"Lint Compliance:      {pct_color}{pct}%{RESET} ({compliant}/{total} files fully compliant)")
 
    for check_name, check_data in lint["checks"].items():
        label = check_name.replace("_", " ").title()
        c = GREEN if check_data["pass"] == check_data["total"] else RED
        status = _pct_str(check_data["pass"], check_data["total"])
        print(f"  {label + ':':<22}{c}{status}{RESET}")
 
    # Fixable violations
    fix_total = fixable["total"]
    fix_color = GREEN if fix_total == 0 else YELLOW
    print(f"\nFixable Violations:   {fix_color}{fix_total} total{RESET}")
    if fix_total > 0:
        for fix_name in ("header", "docstring", "dbg_import", "func_pattern"):
            if fix_name in fixable:
                fix_labels = {
                    "header": "Header blocks",
                    "docstring": "Docstrings",
                    "dbg_import": "_dbg imports",
                    "func_pattern": "func patterns",
                }
                print(f"  {fix_labels[fix_name] + ':':<22}{YELLOW}{fixable[fix_name]}{RESET}")
 
    # Documentation
    doc_color = GREEN if docs["total_present"] == docs["total_required"] else RED
    doc_status = f"{docs['total_present']}/{docs['total_required']} present"
    print(f"\nDocumentation:        {doc_color}{doc_status}{RESET}")
    for file_info in docs["files"]:
        if file_info["present"]:
            print(f"  {file_info['name']:<22}{GREEN}[OK]{RESET}")
        else:
            print(f"  {file_info['name']:<22}{RED}[MISSING]{RESET}")
 
    # Tests
    test_label = tests["status"].upper().replace("_", " ")
    test_color = GREEN if tests["status"] == "pass" else RED
    test_summary = f" ({tests['summary']})" if tests["summary"] else ""
    print(f"\nTests:                {test_color}{test_label}{RESET}{test_summary}")
    for detail in tests.get("details", []):
        print(f"  {detail}")
 
    # Compatibility
    if compat["installed"]:
        if compat["compatible"]:
            print(f"\noc_diagnostics:       v{compat['version']} -- {GREEN}compatible{RESET}")
        else:
            print(f"\noc_diagnostics:       v{compat['version']} -- {RED}INCOMPATIBLE{RESET}")
    else:
        print(f"\noc_diagnostics:       {RED}NOT INSTALLED{RESET}")
    if compat["message"]:
        print(f"  {compat['message']}")
 
    # Virtual environment
    venv_data = report.get("venv")
    if venv_data:
        venv_color = GREEN if venv_data["status"] == "OK" else YELLOW
        venv_label = "[OK]" if venv_data["status"] == "OK" else "[WARN]"
        print(f"\nVirtual Env:          {venv_color}{venv_label}{RESET} {venv_data['message']}")
 
    # Git
    git_data = report.get("git")
    if git_data:
        print(f"\nGit Integration:")
        _STATUS_COLORS = {"OK": GREEN, "WARN": YELLOW, "FAIL": RED, "SKIP": YELLOW}
        _STATUS_LABELS = {
            "is_repo": "Repository",
            "branch": "Branch",
            "naming_conformant": "Branch naming",
            "clean_worktree": "Working tree",
            "ahead_behind": "Remote sync",
            "hooks_installed": "Hooks",
            "last_commit_conventional": "Last commit",
        }
        for key in _STATUS_LABELS:
            check = git_data.get(key)
            if check is None:
                continue
            label = _STATUS_LABELS[key]
            status = check["status"]
            detail = check["detail"]
            color = _STATUS_COLORS.get(status, RESET)
            print(f"  {label + ':':<22}{color}[{status}]{RESET} {detail}")
 
    # Verbose: per-file breakdown
    if verbose and "files" in lint:
        print(f"\n{CYAN}{'-' * 70}{RESET}")
        print(f"{CYAN}Per-file breakdown:{RESET}")
        print(f"{CYAN}{'-' * 70}{RESET}\n")
 
        for file_info in lint["files"]:
            if not file_info["compliant"]:
                failed = [k for k, v in file_info["checks"].items() if not v]
                print(f"  {file_info['path']}")
                print(f"    Failed: {RED}{', '.join(failed)}{RESET}")
 
    print(f"\n{CYAN}{'=' * 70}{RESET}\n")
 
 
def _print_json_report(report: Dict[str, Any]) -> None:
    """Print JSON health report."""
    print(json.dumps(report, indent=2))
 
 
# ============================================================================
# Main Entry Point
# ============================================================================
 
 
def run_health(
    project_root: Path,
    json_mode: bool = False,
    verbose: bool = False,
    test_timeout: int | None = None,
    log_output: bool = False,
) -> None:
    """
    Run the project health dashboard.
 
    Parameters
    ----------
    project_root : Path
        The detected Option C project root directory.
    json_mode : bool
        Output machine-readable JSON instead of terminal report.
    verbose : bool
        Show per-file details in addition to summary.
    test_timeout : int | None
        Maximum seconds to wait for pytest. Overrides ``health.test_timeout``
        in ``.octrc.json``. Defaults to 300 when neither is set (OI-413).
    """
    func = "run_health"
 
    # Build linter context for check functions
    diagnostics_dir = project_root / "oc_diagnostics"
    if not diagnostics_dir.is_dir():
        diagnostics_dir = project_root / "diagnostics"
        if diagnostics_dir.is_dir():
            print(
                "Warning: 'diagnostics/' is deprecated and will be removed in v1.0.0. "
                "Rename to 'oc_diagnostics/'.",
                file=sys.stderr,
            )
 
    ctx = LinterContext(
        project_root=project_root,
        project_name=project_root.name,
        diagnostics_dir=diagnostics_dir,
        tests_dir=project_root / "tests",
        docs_dir=project_root / "docs",
    )
 
    # Load per-project overrides from .octrc.json
    exclude_dirs = set(LINTER_EXCLUDE_DIRS)
    wildcard_exclude = list(WILDCARD_EXCLUDE_DIRS)
    excluded_by_config: List[str] = []
    active_rules = dict(_DEFAULT_RULES)
    disabled_rules: List[str] = []
 
    # Default timeout for tests; overridable via .octrc.json health.test_timeout
    # or explicit test_timeout parameter (OI-413).
    # OI-519: routed through central oct.core.octrc loader.
    effective_test_timeout: int = 300
    from oct.core.octrc import load_octrc_safe
    octrc = load_octrc_safe(project_root)
    linter_cfg = octrc.get("linter", {})
    if isinstance(linter_cfg, dict):
        for d in linter_cfg.get("exclude_dirs_add", []):
            exclude_dirs.add(d)
            excluded_by_config.append(d)
        for d in linter_cfg.get("exclude_dirs_remove", []):
            exclude_dirs.discard(d)
        for d in linter_cfg.get("wildcard_exclude_add", []):
            if d not in wildcard_exclude:
                wildcard_exclude.append(d)
        # Resolve rule profile and per-rule overrides
        profile_name = linter_cfg.get("profile", "default")
        active_rules = dict(_PROFILES.get(profile_name, _DEFAULT_RULES))
        rule_overrides = linter_cfg.get("rules", {})
        if isinstance(rule_overrides, dict):
            active_rules.update(rule_overrides)
        disabled_rules = [r for r, v in active_rules.items() if not v]
    health_cfg = octrc.get("health", {})
    if isinstance(health_cfg, dict):
        cfg_timeout = health_cfg.get("test_timeout")
        if isinstance(cfg_timeout, int) and cfg_timeout > 0:
            effective_test_timeout = cfg_timeout
 
    # Explicit parameter takes precedence over config
    if test_timeout is not None:
        effective_test_timeout = test_timeout
 
    # Compute dashboard parameters from loaded config
    active_checks = [c for c in _HEALTH_CHECKS if active_rules.get(c, True)]
    _fix_rule_map = {
        "header": "header", "docstring": "docstring",
        "dbg_import": "dbg_import", "func_pattern": "func_pattern",
    }
    fixable_names = [k for k in _fix_rule_map if active_rules.get(_fix_rule_map[k], True)]
 
    from oct.core.terminal import supports_ansi_on
    use_color = supports_ansi_on(sys.stdout) and not json_mode
    G = "\033[92m" if use_color else ""
    R = "\033[91m" if use_color else ""
    Y = "\033[93m" if use_color else ""
    X = "\033[0m" if use_color else ""
 
    template_lines, lm = _build_health_template(
        project_name=project_root.name,
        excluded_dirs=excluded_by_config,
        disabled_rules=disabled_rules,
        active_checks=active_checks,
        fixable_names=fixable_names,
        use_color=use_color,
    )
 
    dashboard = Dashboard(quiet=json_mode)
    dashboard.render(template_lines, footer_line=lm.footer, tasks_total=7)
 
    # --- Check 1: Lint compliance ---
    dashboard.set_task("Lint compliance")
    dashboard.update_line(lm.lint, f"{Y}[>]{X} Lint Compliance:  running...")
    lint_result = check_lint_health(
        project_root, ctx, verbose=verbose,
        exclude_dirs=exclude_dirs, wildcard_exclude=wildcard_exclude,
        active_rules=active_rules,
    )
    pct = lint_result["compliance_pct"]
    pc = G if pct == 100.0 else R
    dashboard.update_line(
        lm.lint,
        f"{G}[x]{X} Lint Compliance:      "
        f"{pc}{pct}%{X} ({lint_result['fully_compliant']}/{lint_result['total_files']}"
        f" files fully compliant)",
    )
    for ck, idx in lm.lint_checks.items():
        cd = lint_result["checks"].get(ck)
        label = ck.replace("_", " ").title()
        if cd:
            c = G if cd["pass"] == cd["total"] else R
            dashboard.update_line(
                idx, f"  {G}[x]{X} {label + ':':<20}{c}{_pct_str(cd['pass'], cd['total'])}{X}",
            )
        else:
            dashboard.update_line(idx, f"  {Y}[-]{X} {label + ':':<20}disabled")
    dashboard.complete_task()
 
    # --- Check 2: Fixable violations ---
    dashboard.set_task("Auto-fixable checks")
    dashboard.update_line(lm.fixable, f"{Y}[>]{X} Fixable Violations:  running...")
    fixable_result = check_fixable_health(
        project_root, ctx,
        exclude_dirs=exclude_dirs, wildcard_exclude=wildcard_exclude,
        active_rules=active_rules,
        verbose=verbose,
    )
    fix_total = fixable_result.get("total", 0)
    fc = G if fix_total == 0 else Y
    dashboard.update_line(lm.fixable, f"{G}[x]{X} Fixable Violations:   {fc}{fix_total} total{X}")
    for fn, idx in lm.fixable_items.items():
        val = fixable_result.get(fn, 0)
        vc = G if val == 0 else Y
        dashboard.update_line(
            idx, f"  {G}[x]{X} {_FIX_LABELS.get(fn, fn) + ':':<20}{vc}{val}{X}",
        )
    dashboard.complete_task()
 
    # --- Check 3: Documentation ---
    dashboard.set_task("Documentation")
    dashboard.update_line(lm.docs, f"{Y}[>]{X} Documentation:  running...")
    _octrc_cfg = load_octrc_safe(project_root)
    _production_mode = bool(
        (_octrc_cfg.get("health") or {}).get("production_mode", False)
    )
    docs_result = check_docs_health(project_root, production_mode=_production_mode)
    dc = G if docs_result["total_present"] == docs_result["total_required"] else R
    dashboard.update_line(
        lm.docs,
        f"{G}[x]{X} Documentation:        "
        f"{dc}{docs_result['total_present']}/{docs_result['total_required']} present{X}",
    )
    for fi in docs_result["files"]:
        idx = lm.docs_files.get(fi["name"])
        if idx is None:
            continue
        if fi["present"]:
            dashboard.update_line(idx, f"  {G}[x]{X} {fi['name']:<20}{G}[OK]{X}")
        elif fi.get("required", True):
            dashboard.update_line(idx, f"  {R}[!]{X} {fi['name']:<20}{R}[MISSING]{X}")
        else:
            dashboard.update_line(idx, f"  {Y}[-]{X} {fi['name']:<20}{Y}[OPTIONAL]{X}")
    dashboard.complete_task()
 
    # --- Check 4: Test suite ---
    dashboard.set_task("Test suite")
    dashboard.update_line(lm.tests, f"{Y}[>]{X} Tests:  running...")
    # FS-C3: read coverage threshold from .octrc.json health section.
    _health_cfg = _octrc_cfg.get("health") or {}
    _coverage_threshold_raw = _health_cfg.get("coverage_threshold")
    _coverage_threshold: Optional[float] = None
    if isinstance(_coverage_threshold_raw, (int, float)):
        _coverage_threshold = float(_coverage_threshold_raw)
    test_result = check_test_health(
        project_root,
        timeout=effective_test_timeout,
        coverage_threshold=_coverage_threshold,
        production_mode=_production_mode,
    )
    ts = test_result["status"]
    cov_pct = test_result.get("coverage_pct")
    cov_thr = test_result.get("coverage_threshold")
    cov_msg = test_result.get("coverage_message")
    cov_suffix = ""
    if cov_pct is not None and cov_thr is not None:
        cov_state = "OK" if cov_pct >= cov_thr else "below"
        cov_suffix = f" | cov {cov_pct:.1f}%/{cov_thr:.0f}% [{cov_state}]"
    elif cov_msg:
        cov_suffix = f" | {cov_msg}"
    tsm = f" ({test_result['summary']}{cov_suffix})" if test_result["summary"] else cov_suffix
    if ts == "pass":
        dashboard.update_line(lm.tests, f"{G}[x]{X} Tests:                {G}PASS{X}{tsm}")
    elif ts == "not_run":
        dashboard.update_line(lm.tests, f"{Y}[-]{X} Tests:                {Y}NOT RUN{X}{tsm}")
    else:
        dashboard.update_line(lm.tests, f"{R}[!]{X} Tests:                {R}{ts.upper()}{X}{tsm}")
    dashboard.complete_task()
 
    # --- Check 5: Compatibility ---
    dashboard.set_task("Compatibility check")
    dashboard.update_line(lm.compat, f"{Y}[>]{X} oc_diagnostics:  checking...")
    compat_result = check_compat_health()
    if compat_result["installed"]:
        if compat_result["compatible"]:
            dashboard.update_line(
                lm.compat,
                f"{G}[x]{X} oc_diagnostics:       v{compat_result['version']} -- {G}compatible{X}",
            )
        else:
            dashboard.update_line(
                lm.compat,
                f"{R}[!]{X} oc_diagnostics:       v{compat_result['version']} -- {R}INCOMPATIBLE{X}",
            )
    else:
        dashboard.update_line(lm.compat, f"{R}[!]{X} oc_diagnostics:       {R}NOT INSTALLED{X}")
    dashboard.complete_task()
 
    # --- Check 6: Virtual environment ---
    dashboard.set_task("Virtual environment")
    dashboard.update_line(lm.venv, f"{Y}[>]{X} Virtual Env:  checking...")
    venv_result = check_venv_health(project_root)
    if venv_result["status"] == "OK":
        dashboard.update_line(
            lm.venv, f"{G}[x]{X} Virtual Env:          {G}[OK]{X} {venv_result['message']}",
        )
    else:
        dashboard.update_line(
            lm.venv, f"{R}[!]{X} Virtual Env:          {Y}[WARN]{X} {venv_result['message']}",
        )
    dashboard.complete_task()
 
    # --- Check 7: Git integration ---
    dashboard.set_task("Git integration")
    dashboard.update_line(lm.git, f"{Y}[>]{X} Git Integration:  checking...")
    git_result = check_git_health(project_root)
    _GC = {"OK": G, "WARN": Y, "FAIL": R, "SKIP": Y}
    git_ok = 0
    git_total = 0
    for gk, gl in _GIT_LABELS.items():
        idx = lm.git_checks.get(gk)
        check = git_result.get(gk)
        if idx is None or check is None:
            continue
        git_total += 1
        status = check["status"]
        color = _GC.get(status, X)
        if status == "OK":
            git_ok += 1
            mk = f"{G}[x]{X}"
        elif status in ("WARN", "SKIP"):
            mk = f"{Y}[-]{X}"
        else:
            mk = f"{R}[!]{X}"
        dashboard.update_line(idx, f"  {mk} {gl + ':':<20}{color}[{status}]{X} {check['detail']}")
    gc = G if git_ok == git_total else Y
    dashboard.update_line(lm.git, f"{G}[x]{X} Git Integration:      {gc}{git_ok}/{git_total} checks OK{X}")
    dashboard.complete_task()
 
    dashboard.finish()
 
    # Build report dict for JSON output
    report = {
        "project": project_root.name,
        "oct_version": __version__,
        "timestamp": datetime.now().isoformat(),
        "excluded_dirs": excluded_by_config,
        "disabled_rules": disabled_rules,
        "lint": lint_result,
        "fixable": fixable_result,
        "docs": docs_result,
        "tests": test_result,
        "compat": compat_result,
        "venv": venv_result,
        "git": git_result,
    }
 
    if json_mode:
        _print_json_report(report)
 
    if log_output:
        from oct.core.log_writer import write_command_log
        log_path = write_command_log(project_root, "health", report)
        print(f"Log written to: {log_path}", file=sys.stderr)
 
    if verbose and not json_mode and "files" in lint_result:
        print(f"\n{Y}{'-' * 70}{X}")
        print(f"{Y}Per-file breakdown:{X}")
        print(f"{Y}{'-' * 70}{X}\n")
        for file_info in lint_result["files"]:
            if not file_info["compliant"]:
                failed = [k for k, v in file_info["checks"].items() if not v]
                print(f"  {file_info['path']}")
                print(f"    Failed: {R}{', '.join(failed)}{X}")
 
    if verbose and not json_mode and fixable_result.get("files"):
        print(f"\n{Y}{'-' * 70}{X}")
        print(f"{Y}Fixable violations per file:{X}")
        print(f"{Y}{'-' * 70}{X}\n")
        for file_info in fixable_result["files"]:
            print(f"  {file_info['path']}")
            print(f"    Fixable: {Y}{', '.join(file_info['fixes'])}{X}")