Module

health.report

Health check report formatting and data structures.

Provides structured reporting of health check results with multiple output formats.

View source
5 Classes

Classes

CheckStatus
Status of a health check. Severity levels (from most to least critical): - ERROR: Blocks builds, m…
0

Status of a health check.

Severity levels (from most to least critical):

  • ERROR: Blocks builds, must fix
  • WARNING: Don't block, but should fix
  • SUGGESTION: Quality improvements (collapsed by default)
  • INFO: Contextual information (hidden unless verbose)
  • SUCCESS: Check passed
Inherits from Enum
CheckResult dataclass
Result of a single health check.
9

Result of a single health check.

Attributes

Name Type Description
status CheckStatus

Status level (success, info, warning, error)
message str

Human-readable description of the check result
recommendation str | None

Optional suggestion for how to fix/improve (shown for warnings/errors)
details list[str] | None

Optional additional context (list of strings)
validator str

Name of validator that produced this result
metadata dict[str, Any] | None

Methods 9

success classmethod
Create a success result.
2 CheckResult 
def success(cls, message: str, validator: str = '') -> CheckResult

Create a success result.

Parameters 2
message str
validator str
Returns

CheckResult

info classmethod
Create an info result.
5 CheckResult 
def info(cls, message: str, recommendation: str | None = None, details: list[str] | None = None, validator: str = '', metadata: dict[str, Any] | None = None) -> CheckResult

Create an info result.

Parameters 5
message str
recommendation str | None
details list[str] | None
validator str
metadata dict[str, Any] | None
Returns

CheckResult

suggestion classmethod
Create a suggestion result (quality improvement, not a problem).
5 CheckResult 
def suggestion(cls, message: str, recommendation: str | None = None, details: list[str] | None = None, validator: str = '', metadata: dict[str, Any] | None = None) -> CheckResult

Create a suggestion result (quality improvement, not a problem).

Parameters 5
message str
recommendation str | None
details list[str] | None
validator str
metadata dict[str, Any] | None
Returns

CheckResult

warning classmethod
Create a warning result.
5 CheckResult 
def warning(cls, message: str, recommendation: str | None = None, details: list[str] | None = None, validator: str = '', metadata: dict[str, Any] | None = None) -> CheckResult

Create a warning result.

Parameters 5
message str
recommendation str | None
details list[str] | None
validator str
metadata dict[str, Any] | None
Returns

CheckResult

error classmethod
Create an error result.
5 CheckResult 
def error(cls, message: str, recommendation: str | None = None, details: list[str] | None = None, validator: str = '', metadata: dict[str, Any] | None = None) -> CheckResult

Create an error result.

Parameters 5
message str
recommendation str | None
details list[str] | None
validator str
metadata dict[str, Any] | None
Returns

CheckResult

is_problem
Check if this is a warning or error (vs success/info/suggestion).
0 bool 
def is_problem(self) -> bool

Check if this is a warning or error (vs success/info/suggestion).

Returns

bool

is_actionable
Check if this requires action (error, warning, or suggestion).
0 bool 
def is_actionable(self) -> bool

Check if this requires action (error, warning, or suggestion).

Returns

bool

to_cache_dict
Serialize CheckResult to JSON-serializable dict for caching.
0 dict[str, Any] 
def to_cache_dict(self) -> dict[str, Any]

Serialize CheckResult to JSON-serializable dict for caching.

Returns

dict[str, Any] —

Dictionary with all fields as JSON-serializable types

from_cache_dict classmethod
Deserialize CheckResult from cached dict.
1 CheckResult 
def from_cache_dict(cls, data: dict[str, Any]) -> CheckResult

Deserialize CheckResult from cached dict.

Parameters 1
data dict[str, Any]

Dictionary from cache
Returns

CheckResult —

CheckResult instance

ValidatorStats dataclass
Observability metrics for a validator run. These stats help diagnose performance issues and valida…
5

Observability metrics for a validator run.

These stats help diagnose performance issues and validate that optimizations (like caching) are working correctly.

This class follows the ComponentStats pattern from bengal.utils.observability but maintains page-specific naming for validator contexts.

Attributes

Name Type Description
pages_total int

Total pages in site
pages_processed int

Pages actually validated
pages_skipped dict[str, int]

Dict of skip reasons and counts
cache_hits int

Number of cache hits (if applicable)
cache_misses int

Number of cache misses (if applicable)
sub_timings dict[str, float]

Dict of sub-operation names to duration_ms
metrics dict[str, int | float | str]

Custom metrics (component-specific)

Methods 5

cache_hit_rate property
Cache hit rate as percentage (0-100).
float 
def cache_hit_rate(self) -> float

Cache hit rate as percentage (0-100).

Returns

float

skip_rate property
Skip rate as percentage (0-100).
float 
def skip_rate(self) -> float

Skip rate as percentage (0-100).

Returns

float

total_skipped property
Total number of skipped items across all reasons.
int 
def total_skipped(self) -> int

Total number of skipped items across all reasons.

Returns

int

format_summary
Format stats for debug output.
0 str 
def format_summary(self) -> str

Format stats for debug output.

Returns

str

to_log_context
Convert to flat dict for structured logging.
0 dict[str, int | flo… 
def to_log_context(self) -> dict[str, int | float | str]

Convert to flat dict for structured logging.

Returns

dict[str, int | float | str] —

Flat dictionary suitable for structured logging kwargs.

ValidatorReport dataclass
Report for a single validator's checks.
7

Report for a single validator's checks.

Attributes

Name Type Description
validator_name str

Name of the validator
results list[CheckResult]

List of check results from this validator
duration_ms float

How long the validator took to run
stats ValidatorStats | None

Optional observability metrics

Methods 7

passed_count property
Count of successful checks.
int 
def passed_count(self) -> int

Count of successful checks.

Returns

int

info_count property
Count of info messages.
int 
def info_count(self) -> int

Count of info messages.

Returns

int

warning_count property
Count of warnings.
int 
def warning_count(self) -> int

Count of warnings.

Returns

int

suggestion_count property
Count of suggestions (quality improvements).
int 
def suggestion_count(self) -> int

Count of suggestions (quality improvements).

Returns

int

error_count property
Count of errors.
int 
def error_count(self) -> int

Count of errors.

Returns

int

has_problems property
Check if this validator found any warnings or errors.
bool 
def has_problems(self) -> bool

Check if this validator found any warnings or errors.

Returns

bool

status_emoji property
Get emoji representing overall status.
str 
def status_emoji(self) -> str

Get emoji representing overall status.

Returns

str

HealthReport dataclass
Complete health check report for a build.
16

Complete health check report for a build.

Attributes

Name Type Description
validator_reports list[ValidatorReport]

Reports from each validator
timestamp datetime

When the health check was run
build_stats dict[str, Any] | None

Optional build statistics

Methods 13

total_passed property
Total successful checks across all validators.
int 
def total_passed(self) -> int

Total successful checks across all validators.

Returns

int

total_info property
Total info messages across all validators.
int 
def total_info(self) -> int

Total info messages across all validators.

Returns

int

total_warnings property
Total warnings across all validators.
int 
def total_warnings(self) -> int

Total warnings across all validators.

Returns

int

total_suggestions property
Total suggestions (quality improvements) across all validators.
int 
def total_suggestions(self) -> int

Total suggestions (quality improvements) across all validators.

Returns

int

total_errors property
Total errors across all validators.
int 
def total_errors(self) -> int

Total errors across all validators.

Returns

int

total_checks property
Total number of checks run.
int 
def total_checks(self) -> int

Total number of checks run.

Returns

int

has_errors
Check if any errors were found.
0 bool 
def has_errors(self) -> bool

Check if any errors were found.

Returns

bool

has_warnings
Check if any warnings were found.
0 bool 
def has_warnings(self) -> bool

Check if any warnings were found.

Returns

bool

has_problems
Check if any errors or warnings were found.
0 bool 
def has_problems(self) -> bool

Check if any errors or warnings were found.

Returns

bool

build_quality_score
Calculate build quality score (0-100). Uses a penalty-based system where: - Ba…
0 int 
def build_quality_score(self) -> int

Calculate build quality score (0-100).

Uses a penalty-based system where:

  • Base score is 100 (no problems = perfect)
  • Errors subtract significantly (blockers)
  • Warnings subtract moderately (should fix)
  • Diminishing returns prevent extreme scores for many small issues

This ensures same problems always give the same score, regardless of how many checks ran.

Returns

int —

Score from 0-100 (100 = perfect)

quality_rating
Get quality rating based on score. Thresholds aligned with penalty-based scori…
0 str 
def quality_rating(self) -> str

Get quality rating based on score.

Thresholds aligned with penalty-based scoring:

  • Excellent (90+): No errors, 0-2 warnings
  • Good (75-89): 1 error or 3-5 warnings
  • Fair (50-74): 2-3 errors or many warnings
  • Needs Improvement (<50): 4+ errors
Returns

str

format_console
Format report for console output.
3 str 
def format_console(self, mode: str = 'auto', verbose: bool = False, show_suggestions: bool = False) -> str

Format report for console output.

Parameters 3
mode str

Display mode - "auto", "quiet", "normal", "verbose" auto = quiet if no problems, normal if warnings/errors
verbose bool

Legacy parameter, sets mode to "verbose"
show_suggestions bool

Whether to show suggestions (quality improvements)
Returns

str —

Formatted string ready to print

format_json
Format report as JSON-serializable dictionary.
0 dict[str, Any] 
def format_json(self) -> dict[str, Any]

Format report as JSON-serializable dictionary.

Returns

dict[str, Any] —

Dictionary suitable for json.dumps()

Internal Methods 3
_format_quiet
Minimal output - perfect builds get one line, problems shown clearly.
1 str 
def _format_quiet(self, show_suggestions: bool = False) -> str

Minimal output - perfect builds get one line, problems shown clearly.

Parameters 1
show_suggestions bool

Whether to show suggestions (ignored in quiet mode)
Returns

str

_format_normal
Balanced output with progressive disclosure - problems first, then successes. R…
1 str 
def _format_normal(self, show_suggestions: bool = False) -> str

Balanced output with progressive disclosure - problems first, then successes. Reduces cognitive load by prioritizing actionable information.

Parameters 1
show_suggestions bool

Whether to show suggestions (collapsed by default)
Returns

str

_format_verbose
Full audit trail with progressive disclosure - problems first, then all details.
1 str 
def _format_verbose(self, show_suggestions: bool = True) -> str

Full audit trail with progressive disclosure - problems first, then all details.

Parameters 1
show_suggestions bool

Whether to show suggestions (default True in verbose mode)
Returns

str