|
| Dict[str, Any] | check_lint_health (Path project_root, LinterContext ctx, bool verbose=False, Optional[set] exclude_dirs=None, Optional[list] wildcard_exclude=None, Optional[dict] active_rules=None) |
| Dict[str, Any] | check_fixable_health (Path project_root, LinterContext ctx, Optional[set] exclude_dirs=None, Optional[list] wildcard_exclude=None, Optional[dict] active_rules=None, bool verbose=False) |
| Dict[str, Any] | check_docs_health (Path project_root, *, bool production_mode=False) |
| Dict[str, Any] | check_test_health (Path project_root, int timeout=300, *, Optional[float] coverage_threshold=None, bool production_mode=False, Optional[str] coverage_target=None) |
| Dict[str, Any] | check_compat_health () |
| Dict[str, Any] | check_venv_health (Path project_root) |
| Dict[str, Any] | check_git_health (Path project_root) |
| Optional[dict] | _load_octrc_for_health (Path project_root) |
| tuple | _build_health_template (str project_name, List[str] excluded_dirs, List[str] disabled_rules, List[str] active_checks, List[str] fixable_names, bool use_color) |
| str | _pct_str (int count, int total) |
| None | _print_terminal_report (Dict[str, Any] report, bool verbose) |
| None | _print_json_report (Dict[str, Any] report) |
| None | run_health (Path project_root, bool json_mode=False, bool verbose=False, int|None test_timeout=None, bool log_output=False) |
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)
| Dict[str, Any] oct.health.oct_health.check_docs_health |
( |
Path | project_root, |
|
|
* | , |
|
|
bool | production_mode = False ) |
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.
Definition at line 280 of file oct_health.py.
| Dict[str, Any] oct.health.oct_health.check_test_health |
( |
Path | project_root, |
|
|
int | timeout = 300, |
|
|
* | , |
|
|
Optional[float] | coverage_threshold = None, |
|
|
bool | production_mode = False, |
|
|
Optional[str] | coverage_target = None ) |
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``.
Definition at line 333 of file oct_health.py.
| Dict[str, Any] oct.health.oct_health.check_venv_health |
( |
Path | project_root | ) |
|
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).
Definition at line 554 of file oct_health.py.
1.15.0