Markdown Compliance

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_tests/_validator/markdown.py
• src/flext_tests/_validator/_markdown_parts/markdown_part_01.py
• src/flext_tests/_validator/_markdown_parts/markdown_part_02.py
• src/flext_tests/_fixtures/markdown_validation.py
• src/flext_tests/_constants/_validator_parts/validator_part_02.py
• src/flext_tests/_validator/_orchestration_parts/validator_part_02.py
• tests/unit/test_validator_layer_tests_markdown.py

Markdown Compliance is a specialized validation system within the FLEXT ecosystem designed to ensure that Python code blocks embedded in Markdown documentation adhere to strict architectural and syntax standards. It scans .md files to detect invalid Python syntax, forbidden imports, and improper type annotations, ensuring that documentation remains technically accurate and consistent with the project's coding standards.

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:1-13, src/flext_tests/_fixtures/markdown_validation.py:1-15

System Architecture

The Markdown compliance system is built on a multi-layered architecture involving file discovery, regex-based parsing, and a Pytest integration layer. The primary entry point is the FlextValidatorMarkdown class, which orchestrates the scanning of identified Markdown files.

The diagram shows the data flow from the test runner through the discovery phase to the granular validation checks.
Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:20-50, src/flext_tests/_validator/_markdown_parts/markdown_part_02.py:20-35

File Discovery

Files are collected from specific project locations including the root directory, .claude/skills, and docs. Only files with the .md extension are considered for scanning.

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_02.py:20-35

Validation Rules

The validator applies four primary rules to every Python code block found in Markdown files. These rules are identified by specific codes (MD-001 through MD-004).

Rule ID	Name	Description
MD-001	Syntax Error	Validates code using Python's compile() function to ensure it is executable.
MD-002	Forbidden Imports	Blocks imports of Any, Optional, and Union from typing (favoring t.* contracts).
MD-003	Future Annotations	Ensures from __future__ import annotations is present if type hints are used.
MD-004	Forbidden Annotations	Detects usage of object as a type annotation.

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:58-150, src/flext_tests/_constants/_validator_parts/validator_part_02.py:120-135

Technical Implementation

The validator uses a combination of Python's compile builtin and regular expressions to analyze code blocks.

• Syntax Validation: Code is passed to compile(code, str(file_path), "exec"). If a SyntaxError occurs, MD-001 is triggered.
• Import Scanning: The system looks for the prefix from typing import and checks for forbidden names defined in the validator constants.
• Annotation Logic: The system detects the presence of :, def, class, or -> to determine if annotations are being used, which then necessitates the __future__ import.

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:65-150, src/flext_tests/_constants/_validator_parts/validator_part_02.py:125-135

Pytest Integration

Markdown validation is integrated into the test suite via a Pytest plugin. This allows developers to run compliance checks as part of the standard testing workflow using the --markdown-docs flag.

The sequence shows how the Pytest collector identifies relevant Markdown files and delegates validation to the core Markdown validator.
Sources: src/flext_tests/_fixtures/markdown_validation.py:24-100

Configuration

The plugin behavior is controlled via CLI options:

• Flag: --markdown-docs
• Action: Enables the collection and validation of Python blocks in .md files.
• Dependency Check: The plugin automatically skips its own implementation if pytest-markdown-docs is already installed to avoid conflicts.

Sources: src/flext_tests/_fixtures/markdown_validation.py:24-38

Exception Handling and Approvals

While the validator enforces strict rules, it supports a mechanism for "approved exceptions." This allows specific files or specific rules within files to be bypassed if documented and approved. This is handled via the approved_exceptions mapping passed during the scan orchestration.

# Example of an approved exception mapping
approved = {
    "MD-002": ["docs/examples/legacy_code.md"],
    "MD-004": ["docs/api/generic_handler.md"]
}

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:100-110, src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:150-160

Summary

Markdown Compliance in the FLEXT project provides an automated safety net for documentation. By treating Markdown code blocks with the same rigor as source code, the system prevents the proliferation of broken examples and ensures that all documented type hints follow the project's modern Python standards (such as mandatory future annotations and use of internal type contracts).

Sources: src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:5-10, README.md:1-15