Module

health.health_check

Main health check orchestrator.

Coordinates all validators and produces unified health reports. Supports parallel execution of validators for improved performance.

View source
2 Classes

Classes

HealthCheckStats dataclass
Statistics about health check execution. Provides observability into parallel execution performance.
3

Statistics about health check execution.

Provides observability into parallel execution performance.

Attributes

Name Type Description
total_duration_ms float
execution_mode str
validator_count int
worker_count int
cpu_count int
sum_validator_duration_ms float

Methods 3

speedup property
Calculate speedup from parallel execution. Returns ratio of sum(individual dur…
float 
def speedup(self) -> float

Calculate speedup from parallel execution.

Returns ratio of sum(individual durations) / total duration. A speedup of 2.0 means parallel was 2x faster than sequential would be.

Returns

float

efficiency property
Calculate parallel efficiency (0.0 to 1.0). efficiency = speedup / worker_coun…
float 
def efficiency(self) -> float

Calculate parallel efficiency (0.0 to 1.0).

efficiency = speedup / worker_count 1.0 = perfect scaling, 0.5 = 50% efficiency

Returns

float

format_summary
Format a human-readable summary.
0 str 
def format_summary(self) -> str

Format a human-readable summary.

Returns

str

HealthCheck
Orchestrates health check validators and produces unified health reports. By default, registers al…
13

Orchestrates health check validators and produces unified health reports.

By default, registers all standard validators. You can disable auto-registration by passing auto_register=False, then manually register validators.

Usage:

# Default: auto-registers all validators
health = HealthCheck(site)
report = health.run()
print(report.format_console())

# Manual registration:
health = HealthCheck(site, auto_register=False)
health.register(ConfigValidator())
health.register(OutputValidator())
report = health.run()

Attributes

Name Type Description
last_stats HealthCheckStats | None

Methods 3

register
Register a validator to be run.
1 None 
def register(self, validator: BaseValidator) -> None

Register a validator to be run.

Parameters 1
validator BaseValidator

Validator instance to register
run
Run all registered validators and produce a health report. Validators run in p…
8 HealthReport 
def run(self, build_stats: dict[str, Any] | None = None, verbose: bool = False, profile: BuildProfile | None = None, incremental: bool = False, context: list[Path] | None = None, cache: Any = None, build_context: Any = None, tier: str = 'build') -> HealthReport

Run all registered validators and produce a health report.

Validators run in parallel when there are 3+ enabled validators, falling back to sequential execution for smaller workloads.

Parameters 8
build_stats dict[str, Any] | None

Optional build statistics to include in report
verbose bool

Whether to show verbose output during validation
profile BuildProfile | None

Build profile to use for filtering validators
incremental bool

If True, only validate changed files (requires cache)
context list[Path] | None

Optional list of specific file paths to validate (overrides incremental)
cache Any

Optional BuildCache instance for incremental validation and result caching
build_context Any

Optional BuildContext with cached artifacts (e.g., knowledge graph, cached content) that validators can use to avoid redundant computation. When build_context has cached content, validators like DirectiveValidator skip disk I/O, reducing health check time from ~4.6s to <100ms.
tier str

Validation tier to run: - "build": Fast validators only (<100ms) - default - "full": + Knowledge graph validators (~500ms) - "ci": All validators including external checks (~30s)
Returns

HealthReport —

HealthReport with results from all validators

run_and_print
Run health checks and print console output.
2 HealthReport 
def run_and_print(self, build_stats: dict[str, Any] | None = None, verbose: bool = False) -> HealthReport

Run health checks and print console output.

Parameters 2
build_stats dict[str, Any] | None

Optional build statistics
verbose bool

Whether to show all checks (not just problems)
Returns

HealthReport —

HealthReport

Internal Methods 10
__init__
Initialize health check system.
2 None 
def __init__(self, site: Site, auto_register: bool = True)

Initialize health check system.

Parameters 2
site Site

The Site object to validate
auto_register bool

Whether to automatically register all default validators
_register_default_validators
Register all default validators.
0 None 
def _register_default_validators(self) -> None

Register all default validators.

_get_optimal_workers
Calculate optimal worker count based on system resources and workload. Auto-sc…
1 int 
def _get_optimal_workers(self, validator_count: int) -> int

Calculate optimal worker count based on system resources and workload.

Auto-scales based on:

  • Available CPU cores (uses ~50% to leave headroom)
  • Number of validators (no point having more workers than tasks)
  • Minimum of 2 workers (for any parallelism benefit)
  • Maximum of 8 workers (diminishing returns beyond this)
Parameters 1
validator_count int

Number of validators to run
Returns

int —

Optimal number of worker threads

_is_validator_in_tier
Check if a validator should run based on the validation tier. Tiered validatio…
2 bool 
def _is_validator_in_tier(self, validator: BaseValidator, tier: str) -> bool

Check if a validator should run based on the validation tier.

Tiered validation allows fast builds by default with thorough checks available when needed.

Tiers (cumulative):

  • "build": Fast validators only (<100ms)
  • "full": + Knowledge graph validators (~500ms)
  • "ci": All validators including external checks (~30s)
Parameters 2
validator BaseValidator

The validator to check
tier str

One of "build", "full", or "ci"
Returns

bool —

True if validator should run for this tier

_is_validator_enabled
Check if a validator should run based on profile and config.
3 bool 
def _is_validator_enabled(self, validator: BaseValidator, profile: BuildProfile | None, verbose: bool) -> bool

Check if a validator should run based on profile and config.

Parameters 3
validator BaseValidator

The validator to check
profile BuildProfile | None

Optional build profile for filtering
verbose bool

Whether to show skip messages
Returns

bool —

True if validator should run

_get_files_to_validate
Determine which files to validate for incremental/context modes.
3 set[Path] | None 
def _get_files_to_validate(self, context: list[Path] | None, incremental: bool, cache: Any) -> set[Path] | None

Determine which files to validate for incremental/context modes.

Parameters 3
context list[Path] | None

Optional explicit file list
incremental bool

Whether incremental mode is enabled
cache Any

BuildCache instance
Returns

set[Path] | None —

Set of paths to validate, or None for full validation

_run_single_validator
Run a single validator and return its report. This method is used by both sequ…
4 ValidatorReport 
def _run_single_validator(self, validator: BaseValidator, build_context: BuildContext | Any | None, cache: Any, files_to_validate: set[Path] | None) -> ValidatorReport

Run a single validator and return its report.

This method is used by both sequential and parallel execution.

Parameters 4
validator BaseValidator

The validator to run
build_context BuildContext | Any | None

Optional BuildContext with cached artifacts
cache Any

Optional BuildCache for result caching
files_to_validate set[Path] | None

Set of files to validate (for incremental mode)
Returns

ValidatorReport —

ValidatorReport with results and timing

_run_validators_sequential
Run validators sequentially (for small workloads).
6 None 
def _run_validators_sequential(self, validators: list[BaseValidator], report: HealthReport, build_context: BuildContext | Any | None, verbose: bool, cache: Any, files_to_validate: set[Path] | None) -> None

Run validators sequentially (for small workloads).

Parameters 6
validators list[BaseValidator]

List of validators to run
report HealthReport

HealthReport to add results to
build_context BuildContext | Any | None

Optional BuildContext with cached artifacts
verbose bool

Whether to show per-validator output
cache Any

Optional BuildCache for result caching
files_to_validate set[Path] | None

Set of files to validate (for incremental mode)
_run_validators_parallel
Run validators in parallel using ThreadPoolExecutor. Uses as_completed() to pr…
7 None 
def _run_validators_parallel(self, validators: list[BaseValidator], report: HealthReport, build_context: BuildContext | Any | None, verbose: bool, cache: Any, files_to_validate: set[Path] | None, worker_count: int | None = None) -> None

Run validators in parallel using ThreadPoolExecutor.

Uses as_completed() to process results as they finish, providing better UX for verbose mode. Output is printed in the main thread to prevent garbled console output.

Parameters 7
validators list[BaseValidator]

List of validators to run
report HealthReport

HealthReport to add results to
build_context BuildContext | Any | None

Optional BuildContext with cached artifacts
verbose bool

Whether to show per-validator output
cache Any

Optional BuildCache for result caching
files_to_validate set[Path] | None

Set of files to validate (for incremental mode)
worker_count int | None

Number of worker threads (auto-detected if None)
__repr__
0 str 
def __repr__(self) -> str
Returns

str