oct.health.oct_health module

oct.health.oct_health module#

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)

oct.health.oct_health.check_compat_health() → Dict[str, Any][source]#

Check oc_diagnostics version compatibility.

oct.health.oct_health.check_docs_health(project_root: Path, *, production_mode: bool = False) → Dict[str, Any][source]#

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.

oct.health.oct_health.check_fixable_health(project_root: Path, ctx: LinterContext, exclude_dirs: set | None = None, wildcard_exclude: list | None = None, active_rules: dict | None = None, verbose: bool = False) → Dict[str, Any][source]#

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.

oct.health.oct_health.check_git_health(project_root: Path) → Dict[str, Any][source]#

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.

oct.health.oct_health.check_lint_health(project_root: Path, ctx: LinterContext, verbose: bool = False, exclude_dirs: set | None = None, wildcard_exclude: list | None = None, active_rules: dict | None = None) → Dict[str, Any][source]#

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.

oct.health.oct_health.check_test_health(project_root: Path, timeout: int = 300, *, coverage_threshold: float | None = None, production_mode: bool = False, coverage_target: str | None = None) → Dict[str, Any][source]#

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.

oct.health.oct_health.check_venv_health(project_root: Path) → Dict[str, Any][source]#

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).

  1. 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).

oct.health.oct_health.run_health(project_root: Path, json_mode: bool = False, verbose: bool = False, test_timeout: int | None = None, log_output: bool = False) → None[source]#

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).