Stub Supply Chain Validation
Relevant source files
The following files were used as context for generating this wiki page:
The Stub Supply Chain Validation system is a core infrastructure service designed to manage and verify typing stubs and typing dependencies across workspace projects. It ensures the integrity of the development environment by coordinating mypy stub hints, identifying missing imports via pyrefly, and validating the presence of internal and external types packages.
Sources: src/flext_infra/validate/stub_chain.py:1-26
Architecture and Components
The system is centered around the FlextInfraStubSupplyChain class, which inherits from FlextInfraProjectSelectionServiceBase. This service provides a declarative approach to validating stub availability and identifying gaps in the supply chain for both internal project modules and third-party dependencies.
Core Service Components
| Component | Description |
|---|---|
FlextInfraStubSupplyChain | The primary orchestrator for stub validation logic and CLI flow execution. |
CommandRunner | An abstraction for executing external tools like mypy and pyrefly. |
StubAnalysisReport | A data model containing the results of a project-level stub analysis. |
ValidationReport | A summary model indicating overall pass/fail status and specific violations for the workspace. |
Sources: src/flext_infra/validate/stub_chain.py:29-37, tests/unit/validate/stub_chain_tests.py:100-112
Logic Flow Diagram
The following diagram illustrates the internal logic used to analyze a project's stub status.
This flow shows how the system distinguishes between internal modules (prefixed with flext_) and external modules, and then verifies if stubs exist for the latter.
Sources: src/flext_infra/validate/stub_chain.py:118-142
Validation Logic
The validation process involves two primary external tools to gather data:
- Mypy Hints: The system executes
mypywith specific flags to extract "install-package" hints (e.g., suggestions to installtypes-requests). - Pyrefly Check: The system uses
pyreflyto detect missing imports within the source code.
Classification of Imports
Missing imports are categorized into two groups:
- Internal: Modules that belong to the workspace (detected via name prefixes or project naming conventions).
- Unresolved External: Third-party modules that lack corresponding
.pyistub files in the workspacetypingsortypings/generateddirectories.
Sources: src/flext_infra/validate/stub_chain.py:144-164, src/flext_infra/validate/stub_chain.py:223-268
Stub Directory Lookup
The validator searches for stubs in the following locations relative to the workspace root:
typings/{module_name}.pyitypings/{module_name}/__init__.pyitypings/generated/{module_name}.pyitypings/generated/{module_name}/__init__.pyi
Sources: src/flext_infra/validate/stub_chain.py:72-84
CLI Integration
Stub validation is exposed through the flext-infra CLI under the validate group as the stub-validate route.
CLI Command Configuration
| Option | Type | Default | Description |
|---|---|---|---|
all | bool | False | When True, validates all discovered projects in the workspace. |
projects | StrSequence | None | A list of specific project names to target for validation. |
Sources: src/flext_infra/validate/stub_chain.py:38-41, src/flext_infra/_constants/cli_routes.py:276-281
Execution Result
The execute() method runs the validation and returns a Result[bool]. If violations are found (e.g., internal missing imports or unresolved external imports), the command fails and provides a summary of the issues.
# Example of failure summary format
"stub chain: 1 projects, 2 issues"
Sources: src/flext_infra/validate/stub_chain.py:208-221, tests/unit/validate/stub_chain_tests.py:175-188
Implementation Details
The system relies on regex patterns defined in the infrastructure constants to parse tool output.
- Mypy Hint Parsing: Uses
MYPY_HINT_REto find strings like "note: hint: install stub packagetypes-requests". - Missing Import Parsing: Uses
MISSING_IMPORT_REto extract module names from error messages.
Sources: src/flext_infra/validate/stub_chain.py:223-268
Dependency and Project Discovery
The service identifies projects participating in stub checks by locating directories that contain a pyproject.toml and a src/ subdirectory. Project names are normalized (e.g., replacing dashes with underscores) to match Python module naming conventions during the internal module check.
Sources: src/flext_infra/validate/stub_chain.py:53-70
Summary
Stub Supply Chain Validation provides an automated mechanism to maintain high-quality type information across a multi-project workspace. By integrating mypy and pyrefly, it bridges the gap between static analysis and environment configuration, ensuring that both internal dependencies and external libraries are correctly typed and accounted for.