Type Checking Boundary Generation
Relevant source files
The following files were used as context for generating this wiki page:
Type Checking Boundary Generation is a core architectural component of the FLEXT infrastructure, responsible for managing how types are exposed and imported across project boundaries without creating runtime overhead. It primarily focuses on generating if TYPE_CHECKING: blocks and enforcing namespace rules that govern how public symbols are accessed.
This system ensures that complex type relationships remain navigable by static analysis tools (like Mypy or Pyright) while maintaining strict abstraction boundaries between different project layers. It utilizes automated code generation to maintain consistency across the workspace, particularly for lazy-initialization patterns and facade modules.
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:12-14, src/flext_infra/validate/namespace_rules.py:165-175
Core Logic and Architecture
The generation process relies on a mixin-based architecture that processes import groups, collapses them based on project hierarchy, and formats them into stable, sorted import blocks.
Type Checking Block Generation
The primary entry point for this logic is generate_type_checking. It processes a mapping of module paths to sequences of export/attribute pairs. The generator normalizes module paths and rejects non-absolute imports to ensure consistency within the project root.
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:108-115
Import Group Collapsing
To manage complexity, the system collapses imports into configured child packages. This prevents the generation of excessively granular import lines when multiple sub-modules are imported from the same project boundary.
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:22-38
The flow diagram illustrates the transformation of raw import requirements into a structured if TYPE_CHECKING: block.
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:108-154
Namespace Enforcement Rules
Type checking boundaries are not just generated; they are also validated against specific namespace rules (NS-000 to NS-003).
Rule NS-003: Runtime Boundary Enforcement
Rule NS-003 is critical for boundary integrity. It mandates that runtime modules must use namespaced MRO (Method Resolution Order) aliases (such as c, m, p, t, u) instead of direct imports for symbols belonging to the same project's facade modules.
Sources: src/flext_infra/validate/namespace_rules.py:276-299
| Rule ID | Name | Focus |
|---|---|---|
| NS-000 | Prefix Enforcement | Ensures classes in facade modules use the project prefix. |
| NS-001 | Constant Centralization | Validates inheritance from Constants base and prevents loose enums. |
| NS-002 | Type Centralization | Validates inheritance from Types and prevents loose TypeVar usage. |
| NS-003 | MRO Alias Enforcement | Forces use of aliases (c, m, p, t, u) at runtime boundaries. |
| Sources: src/flext_infra/validate/namespace_rules.py:92-300 |
Implementation Details
Module Export Filtering
The system includes logic to skip redundant module exports during type-checking generation. For example, it avoids re-exporting modules that match the base name or specific reserved identifiers unless they are explicitly required for the facade surface.
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:59-71
# Example of a generated type checking block
if TYPE_CHECKING:
from flext_core import FlextTypes
from flext_infra.models import m as _m
from flext_infra.typings import t as _t
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:117-124
Model Configuration for Codegen
The LazyInitPlan model manages the state for generating __init__.py files, which often include these type-checking boundaries. It tracks lazy_map, type_checking_map, and eager_dunders.
Sources: src/flext_infra/_models/codegen.py:236-260
The class diagram shows the relationship between the generation plan and the discovered package context.
Sources: src/flext_infra/_models/codegen.py:214-260
Conclusion
Type Checking Boundary Generation is essential for maintaining a clean separation between static analysis metadata and runtime logic. By enforcing alias-based access and automating the generation of typing blocks, the system ensures that the FLEXT infrastructure remains scalable and strictly typed without sacrificing runtime performance.
Sources: src/flext_infra/codegen/_codegen_generation_type_checking.py:140-154, src/flext_infra/validate/namespace_rules.py:276-285