Module

health.validators.directives

Directive validator package - checks directive syntax, usage, and performance.

This package validates:

  • Directive syntax is well-formed
  • Required directive options present
  • Tab markers properly formatted
  • Nesting depth reasonable
  • Performance warnings for directive-heavy pages

Refactored from single 1,094-line file into focused modules. See RFC: plan/active/rfc-code-quality-improvements.md

Structure:

  • constants.py: Known directives, thresholds, configuration
  • analysis.py: DirectiveAnalyzer for extracting and analyzing directives
  • checkers.py: Validation check functions
View source
1 Class

Classes

DirectiveValidator
Validates directive syntax and usage across the site. Orchestrates validation by: 1. Analyzing dir…
1

Validates directive syntax and usage across the site.

Orchestrates validation by:

  1. Analyzing directives across all pages (DirectiveAnalyzer)
  2. Checking syntax validity (check_directive_syntax)
  3. Checking completeness (check_directive_completeness)
  4. Checking performance (check_directive_performance)
  5. Checking rendering output (check_directive_rendering)

Checks:

  • Directive blocks are well-formed (opening and closing)
  • Required options are present
  • Tab markers are properly formatted
  • Nesting depth is reasonable
  • Performance warnings for heavy directive usage
Inherits from BaseValidator

Attributes

Name Type Description
last_stats ValidatorStats | None

Methods 1

validate
Run directive validation checks. Uses cached content from build_context when a…
2 list[CheckResult] 
def validate(self, site: Site, build_context: Any = None) -> list[CheckResult]

Run directive validation checks.

Uses cached content from build_context when available to avoid redundant disk I/O (build-integrated validation).

Parameters 2
site Site

Site instance to validate
build_context Any

Optional BuildContext with cached page contents. When provided, uses cached content instead of reading from disk (~4 seconds saved for large sites).
Returns

list[CheckResult] —

List of CheckResult objects