Architecture & Imports Validation

Relevant source files

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

• src/flext_tests/_validator/imports.py
• src/flext_tests/_validator/layer.py
• src/flext_tests/_validator/tests.py
• src/flext_tests/_validator/_orchestration_parts/validator_part_02.py
• src/flext_tests/_validator/_markdown_parts/markdown_part_01.py
• src/flext_tests/_constants/_validator_parts/validator_part_02.py
• src/flext_tests/_models/validator.py
• src/flext_tests/_utilities/validator.py

The Architecture & Imports Validation system is a core component of the FLEXT test infrastructure designed to enforce structural integrity, dependency boundaries, and coding standards across the ecosystem. It provides a suite of specialized validators that scan Python source files and Markdown documentation to detect violations of project-specific architectural rules, such as improper layer dependencies, forbidden import patterns, and restricted test utilities.

The system is orchestrated through a central facade that aggregates results from multiple scanners into a unified report. This ensures that all components within a FLEXT project adhere to the prescribed "Engineering Law" and quality gates defined in the project's governance documentation.

Validation Orchestration

The validation process is managed by the FlextTestsValidator class, which serves as the primary entry point for running architectural checks. It utilizes an orchestration layer to execute various specialized validators either individually or as a combined suite.

The diagram shows the orchestration flow where FlextTestsValidator coordinates multiple sub-validators to produce an aggregated scan result.
Sources: [src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:44-118](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_validator/_orchestration_parts/validator_part_02.py#L44-L118)

Core Data Models

Validation results are encapsulated in structured models that provide detailed information about every detected issue.

• Violation: Captures specific details of a rule breach, including the file path, line number, rule ID, severity, and a code snippet.
• ScanResult: Aggregates a collection of violations, providing a summary of the validator name, total files scanned, and an overall pass/fail status.

Sources: [src/flext_tests/_models/validator.py:15-68](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_models/validator.py#L15-L68)

Import Validation

The FlextValidatorImports class enforces constraints on how modules are imported within the project. This prevents common anti-patterns and maintains a clean dependency graph.

Validated Patterns

• Lazy Imports (IMPORT-001): Detects imports placed inside functions or classes (indented imports), which are generally discouraged in favor of top-level imports.
• ImportError Handling (IMPORT-003): Flags improper handling of ImportError or ModuleNotFoundError.
• Sys Path Manipulation (IMPORT-004): Identifies attempts to modify sys.path dynamically, which can lead to unpredictable import behavior.
• Internal Module Access (IMPORT-006): Prevents importing from internal modules (prefixed with _) of other flext-* packages, enforcing the use of public surfaces.

Sources: [src/flext_tests/_validator/imports.py:22-140](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_validator/imports.py#L22-L140)

Layer Dependency Validation

The FlextValidatorLayer enforces a strict hierarchy between different modules. It ensures that "lower" layers (higher priority/core) do not import from "upper" layers (lower priority/specialized).

This diagram illustrates the directional flow of valid imports; imports from a lower level (e.g., L5) to a higher level (e.g., L6) trigger a LAYER-001 violation.
Sources: [src/flext_tests/_validator/layer.py:20-80](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_validator/layer.py#L20-L80), [tests/unit/test_validator_layer_tests_markdown.py:30-55](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/tests/unit/test_validator_layer_tests_markdown.py#L30-L55)

The validator uses a layer_hierarchy mapping where module stems are assigned integer levels. A violation occurs if imported_layer > current_layer.
Sources: [src/flext_tests/_validator/layer.py:90-110](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_validator/layer.py#L90-L110)

Test Infrastructure Validation

The FlextValidatorTests class targets specific anti-patterns in test files to ensure consistency in mocking and patching strategies.

Rule ID	Name	Description
TEST-001	Monkeypatch Usage	Detects usage of the monkeypatch fixture in parameters or calls.
TEST-002	Mock/MagicMock Usage	Flags direct usage of unittest.mock objects instead of FLEXT-approved alternatives.
TEST-003	@patch Decorator	Detects usage of the @patch decorator, favoring explicit dependency injection or specialized builders.

Sources: [src/flext_tests/_validator/tests.py:28-132](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_validator/tests.py#L28-L132)

Markdown Code Block Validation

To maintain the quality of documentation, the FlextValidatorMarkdown scanner extracts and validates Python code blocks found in .md files (typically READMEs).

Validation Steps

1. Syntax Check (MD-001): Uses the compile() function to ensure the code block is valid Python syntax.
2. Forbidden Imports (MD-002): Prevents usage of Any, Optional, or Union from the standard typing module, encouraging project-specific contracts (e.g., t.*).
3. Future Annotations (MD-003): Enforces the presence of from __future__ import annotations if type hints are used.
4. Object Annotations (MD-004): Flags the use of the generic object type in annotations.

Sources: [src/flext_tests/_validator/_markdown_parts/markdown_part_01.py:27-140](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_validator/_markdown_parts/markdown_part_01.py#L27-L140)

Technical Implementation Details

Regex Engine

Validation is primarily driven by complex regular expressions defined in the constants module. These patterns are used to identify function definitions, import statements, and bypass pragmas like # noqa or # pragma: no cover.

Sources: [src/flext_tests/_constants/_validator_parts/validator_part_02.py:46-160](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_constants/_validator_parts/validator_part_02.py#L46-L160)

Exemption Mechanism

The system supports an approved_exceptions mechanism. Files can be exempted from specific rules by providing patterns in the validator configuration. The u.Tests.approved() utility checks if a given file path matches these exclusion patterns before flagging a violation.

Sources: [src/flext_tests/_utilities/validator.py:73-94](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_utilities/validator.py#L73-L94)

Code Context Awareness

The u.Tests.code_match() utility ensures that validators do not trigger false positives for patterns found inside strings or comments. It performs a character-by-character scan to track whether a match position is "active" or enclosed in quotes.

Sources: [src/flext_tests/_utilities/validator.py:96-140](https://github.com/flext-sh/flext-tests/blob/64b5766451223fdc2a50e68b7ddb1fbb95164c82/src/flext_tests/_utilities/validator.py#L96-L140)

Conclusion

The Architecture & Imports Validation system provides a robust framework for maintaining technical debt and architectural consistency. By automating the detection of layer violations, improper imports, and discouraged testing patterns, it allows the FLEXT ecosystem to scale while ensuring that developers adhere to core structural principles. The combination of static analysis via regex and dynamic orchestration makes it a critical gate in the FLEXT quality assurance pipeline.