Static Type Checking Gates
Relevant source files
The following files were used as context for generating this wiki page:
Static Type Checking Gates are automated quality assurance components within the flext-infra ecosystem designed to enforce type safety across projects. These gates wrap industry-standard tools like Mypy and Pyright, integrating them into the workspace's unified check and fix workflow. By providing a standardized interface for execution, output parsing, and reporting, these gates ensure that type-related regressions are caught early in the development lifecycle.
The system relies on a base abstraction that handles common tasks such as directory discovery, command execution, and result formatting. This allows specific type-checking implementations to focus solely on tool-specific CLI arguments and output serialization (typically JSON).
Sources: src/flext_infra/gates/base_gate.py:16-25, src/flext_infra/gates/mypy.py:14-20, src/flext_infra/gates/pyright.py:14-20
Architecture and Inheritance
The type checking gates follow a strict class hierarchy. Every gate inherits from FlextInfraGate, which defines the template method for the check() and check_files() workflows.
The diagram shows the inheritance relationship where specific gates implement tool-specific logic while sharing the core execution engine.
Sources: src/flext_infra/gates/base_gate.py:16-50, src/flext_infra/gates/mypy.py:14-20, src/flext_infra/gates/pyright.py:14-20
Implementation Details
Execution Flow
The check() method follows a deterministic sequence to validate a project. It first discovers relevant Python directories, then builds and executes the tool-specific command.
The flow ensures that gates only run on projects containing Python source code or type stubs.
Sources: src/flext_infra/gates/base_gate.py:34-59, tests/unit/check/extended_gate_mypy_pyright_tests.py:59-86
Gate Configurations
Gates utilize centralized constants for tool identifiers and metadata.
| Gate ID | Tool Name | Tool URL | Source File |
|---|---|---|---|
mypy | Mypy | https://mypy.readthedocs.io/ | src/flext_infra/_constants/check.py:35 |
pyright | Pyright | `https://github.com/microsoft/pyright%60 | src/flext_infra/_constants/check.py:36 |
Output Parsing and Models
Both Mypy and Pyright gates are configured to output results in JSON format to facilitate reliable parsing into the FlextInfraModelsCheck.Issue model.
Issue Model Structure
The Issue model captures standardized diagnostic information regardless of the source tool.
class Issue(m.ContractModel):
file: str # Source file path
line: int # Line number
column: int # Column number
code: str # Rule or error code (e.g., "assignment", "reportPrivateUsage")
message: str # Human-readable description
severity: str = "error" # error, warning, or note
Sources: src/flext_infra/_models/check.py:168-185, src/flext_infra/gates/pyright.py:73-85
Parsing Logic
- Mypy: Uses
--output-jsonand parses the resulting JSON lines. It extracts standard fields includingmessage,file, andcode. - Pyright: Uses
--outputjsonand looks for thegeneralDiagnosticskey in the JSON response.
Sources: src/flext_infra/gates/mypy.py:46-73, src/flext_infra/gates/pyright.py:73-95
Reporting and Severity
The infrastructure supports different enforcement postures via GateMode. While most type checks are treated as STRICT (failing on error), the system can be configured to WARN, which reports issues without failing the pipeline.
| Severity Level | Description | Constant |
|---|---|---|
error | Fail-inducing diagnostic | GateSeverity.ERROR |
warning | Advisory diagnostic | GateSeverity.WARNING |
note | Informational diagnostic | GateSeverity.NOTE |
Sources: src/flext_infra/_constants/check.py:19-25, src/flext_infra/validate/gate_contract_report.py:42-49
Status Determination
The reporting mixin determines the final status of a check run based on the aggregate of violations found. Errors result in a FAIL status, while warnings result in a WARN status if no errors are present.
Sources: src/flext_infra/validate/gate_contract_report.py:75-81
Conclusion
Static Type Checking Gates provide a robust and extensible framework for maintaining type integrity in the workspace. By abstracting the complexities of tool execution and result parsing, the system allows for consistent enforcement of type standards across diverse projects while providing clear, actionable feedback to developers through standardized issue models and reporting.
Sources: src/flext_infra/gates/base_gate.py:16-25, src/flext_infra/_models/check.py:223-231