Health Check System

Bengal includes a comprehensive health check system that validates builds across all components.

Health Check (bengal/health/health_check.py)

• Purpose: Orchestrates validators and produces unified health reports
• Features:
  • Modular validator architecture
  • Fast execution (< 100ms per validator)
  • Configurable per-validator enable/disable
  • Console and JSON report formats
  • Integration with build stats
• Usage:

  1 2 3 4 5

  from bengal.health import HealthCheck health = HealthCheck(site) report = health.run(build_stats=stats) print(report.format_console())

Base Validator (bengal/health/base.py)

• Purpose: Abstract base class for all validators
• Interface:validate(site) -> List[CheckResult]
• Features:
  • Independent execution (no validator dependencies)
  • Error handling and crash recovery
  • Performance tracking per validator
  • Configuration-based enablement

Health Report (bengal/health/report.py)

• Purpose: Unified reporting structure for health check results
• Components:
  • CheckStatus: SUCCESS, INFO, WARNING, ERROR
  • CheckResult: Individual check result with recommendation
  • ValidatorReport: Results from a single validator
  • HealthReport: Aggregated report from all validators
• Formats:
  • Console output (colored, formatted)
  • JSON output (machine-readable)
  • Summary statistics (pass/warning/error counts)

Validators (bengal/health/validators/)

All Validators (14 total):

Basic Validation:

Content Validation:

Advanced Validation:

Production-Ready Validation:

Connectivity Validator

The Connectivity Validator uses a semantic link model with weighted scoring to provide nuanced page connectivity analysis beyond binary orphan detection.

Link Types and Weights:

Connectivity Levels:

Configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[health_check]
# Connectivity thresholds
isolated_threshold = 5      # Max isolated pages before error
lightly_linked_threshold = 20  # Max lightly-linked before warning

# Customize weights (optional)
[health_check.link_weights]
explicit = 1.0
menu = 10.0
taxonomy = 1.0
related = 0.75
topical = 0.5
sequential = 0.25

CLI Commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Full connectivity report
bengal graph report

# List isolated pages
bengal graph orphans --level isolated

# List lightly-linked pages
bengal graph orphans --level lightly

# CI mode with exit code
bengal graph report --ci --threshold-isolated 5

Configuration

Health checks can be configured viabengal.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

[health_check]
# Globally enable/disable health checks
validate_build = true

# Per-validator configuration (all enabled by default)
[health_check.validators]
# Phase 1: Basic
configuration = true
output = true
navigation_menus = true
links = true

# Phase 2: Content
navigation = true
taxonomies = true
rendering = true
directives = true

# Phase 3: Advanced
cache_integrity = true
performance = true

# Phase 4: Production-ready
rss_feed = true
sitemap = true
fonts = true
asset_processing = true

Integration

Health checks run automatically after builds in strict mode and can be triggered manually:

1
2
3
4
5
6
7
8

# Automatic validation in strict mode
site.config["strict_mode"] = True
stats = site.build()

# Manual validation
from bengal.health import HealthCheck
health = HealthCheck(site)
report = health.run(build_stats=stats)