Module

health.validators.directives.analysis

Directive analysis module.

Extracts and analyzes directive blocks from markdown content.

Build-Integrated Validation: When a BuildContext with cached content is provided, the analyzer uses cached content instead of re-reading files from disk. This eliminates ~4 seconds of redundant disk I/O during health checks (773 files).

See: plan/active/rfc-build-integrated-validation.md
View source
1 Class

Classes

DirectiveAnalyzer
Analyzes directive usage across a site. Extracts directives from markdown content, validates their…
10

Analyzes directive usage across a site.

Extracts directives from markdown content, validates their structure, and collects statistics for reporting.

Build-Integrated Validation: When analyze_from_context() is used with cached content, the analyzer avoids disk I/O entirely, reducing health check time from ~4.6s to <100ms.

Methods 1

analyze
Analyze all directives in site source files. Uses cached content from build_co…
2 dict[str, Any] 
def analyze(self, site: Site, build_context: BuildContext | Any | None = None) -> dict[str, Any]

Analyze all directives in site source files.

Uses cached content from build_context when available to avoid redundant disk I/O (~4 seconds saved for 773-page sites).

Parameters 2
site Site

Site instance to analyze
build_context BuildContext | Any | None

Optional BuildContext with cached page contents. When provided, uses cached content instead of reading from disk (build-integrated validation).
Returns

dict[str, Any] —

Dictionary with directive statistics and issues

Internal Methods 9
_is_inside_code_block
Check if a position in content is inside a markdown code block.
2 bool 
def _is_inside_code_block(self, content: str, position: int) -> bool

Check if a position in content is inside a markdown code block.

Parameters 2
content str

Full markdown content
position int

Character position to check
Returns

bool —

True if position is inside a code block (..., ~~~...~~~, or indented 4+ spaces)

_check_code_block_nesting
Check for markdown code blocks that contain nested code blocks with the same fe…
2 list[dict[str, Any]] 
def _check_code_block_nesting(self, content: str, file_path: Path) -> list[dict[str, Any]]

Check for markdown code blocks that contain nested code blocks with the same fence length.

Parameters 2
content str
file_path Path
Returns

list[dict[str, Any]] —

List of warning dictionaries

_is_inside_colon_directive
Check if a position is inside a colon directive (:::{name}).
2 bool 
def _is_inside_colon_directive(self, content: str, position: int) -> bool

Check if a position is inside a colon directive (:::{name}).

Parameters 2
content str
position int
Returns

bool

_is_inside_inline_code
Check if a position in content is inside inline code (single backticks).
2 bool 
def _is_inside_inline_code(self, content: str, position: int) -> bool

Check if a position in content is inside inline code (single backticks).

Parameters 2
content str
position int
Returns

bool

_extract_directives
Extract all directive blocks from markdown content (colon fences only).
2 list[dict[str, Any]] 
def _extract_directives(self, content: str, file_path: Path) -> list[dict[str, Any]]

Extract all directive blocks from markdown content (colon fences only).

Parameters 2
content str

Markdown content
file_path Path

Path to file (for error reporting)
Returns

list[dict[str, Any]] —

List of directive dictionaries with metadata

_validate_tabs_directive
Validate tabs directive content.
1 None 
def _validate_tabs_directive(self, directive: dict[str, Any]) -> None

Validate tabs directive content.

Parameters 1
directive dict[str, Any]
_validate_code_tabs_directive
Validate code-tabs directive content.
1 None 
def _validate_code_tabs_directive(self, directive: dict[str, Any]) -> None

Validate code-tabs directive content.

Parameters 1
directive dict[str, Any]
_validate_dropdown_directive
Validate dropdown directive content.
1 None 
def _validate_dropdown_directive(self, directive: dict[str, Any]) -> None

Validate dropdown directive content.

Parameters 1
directive dict[str, Any]
_check_fence_nesting
Check for fence nesting issues.
1 None 
def _check_fence_nesting(self, directive: dict[str, Any]) -> None

Check for fence nesting issues.

Parameters 1
directive dict[str, Any]