Validation Orchestration

Relevant source files

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

• src/flext_tests/_validator/_orchestration_parts/validator_part_01.py
• src/flext_tests/_validator/_orchestration_parts/validator_part_02.py
• src/flext_tests/_validator/models.py
• src/flext_tests/_validator/layer.py
• src/flext_tests/_validator/imports.py
• src/flext_tests/_validator/tests.py
• src/flext_tests/_validator/_settings_parts/settings_part_02.py

Validation Orchestration in the flext-tests infrastructure serves as the central coordination layer for architectural enforcement. It aggregates multiple specialized scanning engines—covering imports, type annotations, layer dependencies, test patterns, and configuration files—into a unified execution interface. This system ensures that the FLEXT ecosystem adheres to its defined engineering laws and architectural boundaries.

The primary entry point is the FlextTestsValidator class, which manages the lifecycle of a validation run, from file discovery and pattern exclusion to the aggregation of results into a standardized ScanResult model. Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_01.py, src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:30-35

Architectural Components

The orchestration logic is divided into specialized validators that handle specific domains of the codebase. Each validator implements a scan method that returns a Result[m.Tests.ScanResult].

Validator Engines

• Bypass Validator: Scans for suppression markers like # noqa or # pragma: no cover.
• Imports Validator: Enforces rules regarding lazy imports, sys.path manipulation, and internal module access.
• Layer Validator: Validates dependency hierarchies to prevent lower layers from importing upper layers.
• Types Validator: Detects wildcard types (Any), legacy typing annotations, and forbidden object usage.
• Tests Validator: Identifies prohibited test patterns, such as direct monkeypatch usage or standard unittest.mock calls.
• Settings Validator: Inspects pyproject.toml for strict mypy and pyright configurations.
• Markdown Validator: Validates Python code blocks within documentation for syntax and architectural compliance.

Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:46-95, src/flext_tests/_validator/tests.py:17-20

Orchestration Flow

The aggregate all() method coordinates the execution of these specialized scanners. It collects violations across all domains and combines them into a single report.

The diagram shows the parallel nature of the scanning process and the final aggregation step where individual results are merged into a comprehensive report. Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:43-85

Data Models and Configuration

Orchestration is driven by an options envelope that defines the scope and strictness of the scan.

AllValidationOptions

The configuration for a validation run is managed via AllValidationOptions.

Parameter	Type	Description
pyproject_path	Path | None	Path to pyproject.toml for settings validation.
exclude_patterns	t.StrSequence	Glob patterns to exclude files from discovery.
approved_exceptions	Mapping[str, StrSequence]	Rule-to-path allowlist for approved violations.
include_tests_validation	bool	Toggle for test-pattern scanning (defaults to False).

Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_01.py:22-44

ScanResult and Violations

The output of the orchestration is a ScanResult which encapsulates the health of the project at the time of the scan.

This relationship ensures that even aggregate scans provide granular details about the exact location and nature of every architectural breach. Sources: src/flext_tests/_models/validator.py:15-68

Logic and Execution

File Discovery

The orchestration logic includes a recursive file discovery mechanism that filters files based on the project's default exclusion patterns (e.g., .venv, __pycache__) and user-provided overrides.

@classmethod
def _discover_files(
    cls,
    path: Path,
    exclude_patterns: t.StrSequence | None = None,
) -> t.SequenceOf[Path]:
    """Discover Python files to scan."""
    excludes = exclude_patterns or list(c.Tests.VALIDATOR_EXCLUDE_PATTERNS)
    if path.is_file():
        return [path] if path.suffix == ".py" else []
    files: t.SequenceOf[Path] = [
        py_file
        for py_file in u.Infra.iter_matching_files(path, includes=["*.py"])
        if not any(fnmatch.fnmatch(str(py_file), pattern) for pattern in excludes)
    ]
    return files

Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_01.py:46-60

Exception Handling and Results

The all() method handles potential failures in individual validator engines. If a specific engine fails to execute (e.g., due to an unreadable file or syntax error), the entire orchestration returns a failure result immediately to ensure the integrity of the quality gate. Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:86-90

Conclusion

Validation Orchestration provides the necessary scaffolding to enforce complex architectural constraints across the FLEXT ecosystem. By unifying disparate checks into a single execution flow, it enables consistent quality enforcement through CI/CD gates and local development tools. The modular design allows for the independent evolution of scanning rules while maintaining a stable public interface for consumers.