Type Correctness Validation

Relevant source files

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

• src/flext_tests/_validator/_types_parts/types_part_01.py
• src/flext_tests/_validator/_types_parts/types_part_02.py
• src/flext_tests/_validator/_orchestration_parts/validator_part_02.py
• src/flext_tests/_constants/_validator_parts/validator_part_02.py
• src/flext_tests/_utilities/validator.py
• tests/unit/test_validator_types.py

Type Correctness Validation is a specialized subsystem within the FLEXT test infrastructure designed to enforce modern Python typing standards and prevent anti-patterns in source code. It performs static analysis on Python files to detect legacy typing constructs, forbidden wildcard types, and unsafe type manipulation practices.

The system operates as part of the broader FlextTestsValidator facade, providing specific rules (prefixed with TYPE-) that ensure codebase alignment with PEP 695 and other modern Python 3.13+ typing features. It identifies issues ranging from simple # type: ignore comments to complex legacy generic syntax and improper use of object or Any annotations.

Architecture and Orchestration

The validation logic is encapsulated in the FlextValidatorTypes class, which leverages a shared scanning infrastructure. The validation process is triggered through the public validator facade, typically via the tv.types() method.

The orchestration layer handles file discovery and combines individual file scan results into a unified ScanResult.
Sources: src/flext_tests/_validator/_orchestration_parts/validator_part_02.py:126-130, src/flext_tests/_validator/_types_parts/types_part_02.py:118-135

Core Validation Rules

The system enforces several distinct categories of type correctness. Each category is backed by regex-based scanners that analyze code lines while accounting for string literals to avoid false positives.

Legacy and Forbidden Types

The validator actively flags legacy PEP 484 typing constructs that have been superseded by newer syntax (such as PEP 695 type aliases).

Rule ID	Name	Description
TYPE-001	Type Ignore	Detects # type: ignore comments in code.
TYPE-002	Any Types	Detects wildcard Any annotations in arguments, returns, or variables.
TYPE-004	Legacy Factories	Detects usage of TypeVar(), ParamSpec(), or Generic[] base classes.
TYPE-005	Legacy Annotations	Detects legacy typing containers like List, Dict, Optional, and Union.
TYPE-006	Object Annotations	Detects the use of object as a type annotation (recommends t.* contracts).

Sources: src/flext_tests/_validator/_types_parts/types_part_01.py:27-124, src/flext_tests/_validator/_types_parts/types_part_02.py:15-116, src/flext_tests/_constants/_validator_parts/validator_part_02.py:20-35

Boolean Helper Validation

A specific check (TYPE-007) ensures that helper functions starting with is_ do not return a raw bool. The project encourages using more descriptive type guards like TypeIs or TypeGuard for such helpers to improve type narrowing.

# Disallowed (TYPE-007)
def is_ready(value: str) -> bool:
    return bool(value)

# Recommended
def is_ready(value: str) -> TypeIs[str]:
    return len(value) > 0

Sources: src/flext_tests/_validator/_types_parts/types_part_02.py:18-35, tests/unit/test_validator_types.py:58-69

Implementation Details

Regex-Based Scanning

The validator uses a suite of compiled regular expressions to identify violations. To ensure accuracy, the utility method u.Tests.code_match is used to verify that a regex match occurs in actual code and not inside a string literal.

Exception Handling and Approvals

Violations can be suppressed using an "approved exceptions" mechanism. This allows specific files to bypass certain rules if they are mapped in the validator configuration. The approved() utility checks the file_path against patterns defined for a specific rule_id.

if u.Tests.approved("TYPE-003", file_path, approved, c.Tests.VALIDATOR_APPROVED_CAST_PATTERNS):
    return []

Sources: src/flext_tests/_utilities/validator.py:72-91, src/flext_tests/_validator/_types_parts/types_part_02.py:73-78

Summary

Type Correctness Validation serves as a strict enforcer of modern Python typing within the FLEXT ecosystem. By automating the detection of legacy syntax and anti-patterns like wildcard types, it ensures that the codebase remains highly maintainable and compatible with advanced static analysis tools. The system is designed to be extensible, utilizing a centralized repository of regex patterns and violation messages to maintain consistency across the project.