Module

health.validators.cross_ref

Cross-reference validator for validating semantic references in content.

Validates that code references, configuration mentions, and other semantic links in documentation actually exist and are current.

Key Features:

  • Validate function/class references against source code
  • Validate configuration option references
  • Find broken anchor links to headings
  • Detect stale version references

Related Modules:

  • bengal.health.base: BaseValidator interface
  • bengal.health.report: CheckResult for reporting

See Also:

  • bengal/health/validators/links.py: URL link validation
  • bengal/debug/base.py: Debug tool infrastructure
View source
3 Classes 1 Function

Classes

CodeReference dataclass
A reference to code in documentation content.
1

A reference to code in documentation content.

Attributes

Name Type Description
ref_type str

Type of reference (function, class, config, variable)
name str

The referenced name
module str | None

Optional module path
raw str

Raw matched text
line int

Line number in content
file_path str

Path to the content file
Internal Methods 1
__str__
0 str 
def __str__(self) -> str
Returns

str

CodeIndex dataclass
Index of code symbols for validation.
2

Index of code symbols for validation.

Attributes

Name Type Description
functions set[str]

Set of function names
classes set[str]

Set of class names
constants set[str]

Set of constant names
config_options set[str]

Set of configuration option names
modules set[str]

Set of module paths

Methods 2

from_directory classmethod
Build code index from a source directory. Parses Python files to extract funct…
1 CodeIndex 
def from_directory(cls, source_dir: Path) -> CodeIndex

Build code index from a source directory.

Parses Python files to extract function, class, and constant names.

Parameters 1
source_dir Path

Directory containing Python source code
Returns

CodeIndex —

CodeIndex with discovered symbols

contains
Check if a reference exists in the index.
1 bool 
def contains(self, ref: CodeReference) -> bool

Check if a reference exists in the index.

Parameters 1
ref CodeReference
Returns

bool

CrossReferenceValidator
Validates semantic cross-references in documentation. Checks that code references (functions, clas…
7

Validates semantic cross-references in documentation.

Checks that code references (functions, classes, config options) in documentation actually exist in the source code.

Creation:

health_check.register(CrossReferenceValidator(source_dirs=[Path("src")]))
Inherits from BaseValidator

Attributes

Name Type Description
source_dirs —

Directories to search for source code
code_index —

Index of discovered code symbols
config_options —

Known configuration option names
current_version —

Current product version for version checks
deprecated_versions —

List of deprecated version strings

Methods 1

validate
Validate cross-references in all site pages.
2 list[CheckResult] 
def validate(self, site: Site, build_context: Any | None = None) -> list[CheckResult]

Validate cross-references in all site pages.

Parameters 2
site Site

Site to validate
build_context Any | None

Optional BuildContext (not used by this validator)
Returns

list[CheckResult] —

List of CheckResults for invalid references

Internal Methods 6
__init__
Initialize cross-reference validator.
4 None 
def __init__(self, source_dirs: list[Path] | None = None, config_options: set[str] | None = None, current_version: str | None = None, deprecated_versions: list[str] | None = None)

Initialize cross-reference validator.

Parameters 4
source_dirs list[Path] | None

Directories containing source code to index
config_options set[str] | None

Known configuration option names
current_version str | None

Current product version
deprecated_versions list[str] | None

List of deprecated versions to flag
_validate_page
Validate references in a single page.
1 list[CheckResult] 
def _validate_page(self, page: Any) -> list[CheckResult]

Validate references in a single page.

Parameters 1
page Any
Returns

list[CheckResult]

_extract_references
Extract code references from content. Looks for: - `function_name()` - functio…
2 list[CodeReference] 
def _extract_references(self, content: str, file_path: str) -> list[CodeReference]

Extract code references from content.

Looks for:

  • function_name()- function calls in backticks
  • ClassName- CamelCase names in backticks (classes)
  • config_option- snake_case names in backticks (config)
  • CONSTANT_NAME- UPPER_CASE names in backticks (constants)
Parameters 2
content str

Page content to search
file_path str

Path to the content file
Returns

list[CodeReference] —

List of CodeReference objects

_validate_reference
Validate a single code reference.
1 CheckResult | None 
def _validate_reference(self, ref: CodeReference) -> CheckResult | None

Validate a single code reference.

Parameters 1
ref CodeReference

Reference to validate
Returns

CheckResult | None —

CheckResult if invalid, None if valid

_validate_versions
Validate version references in content.
2 list[CheckResult] 
def _validate_versions(self, content: str, file_path: str) -> list[CheckResult]

Validate version references in content.

Parameters 2
content str

Page content
file_path str

Path to content file
Returns

list[CheckResult] —

List of CheckResults for deprecated versions

_validate_anchors
Validate anchor links to headings.
1 list[CheckResult] 
def _validate_anchors(self, page: Any) -> list[CheckResult]

Validate anchor links to headings.

Parameters 1
page Any

Page to validate
Returns

list[CheckResult] —

List of CheckResults for broken anchors

Functions

create_cross_ref_validator
Factory function to create a configured CrossReferenceValidator.
3 CrossReferenceValidator 
def create_cross_ref_validator(site_root: Path, source_dir: str = 'bengal', config_options: set[str] | None = None) -> CrossReferenceValidator

Factory function to create a configured CrossReferenceValidator.

Parameters 3

Name Type Default Description
site_root Path —

Root path of the site
source_dir str 'bengal'

Name of source code directory
config_options set[str] | None None

Optional set of known config option names

Returns

CrossReferenceValidator —

Configured CrossReferenceValidator