Check & Validation Gates
Relevant source files
The following files were used as context for generating this wiki page:
Check and Validation Gates represent the fundamental governance and quality control mechanism within the FLEXT ecosystem. These gates ensure that every contribution adheres to strictly typed contracts, architectural constraints, and operational standards before promotion or deployment. The system is divided into two primary categories: Check Gates, which focus on static analysis and standardization (e.g., linting, type-checking, Docker centralization), and Validation Gates, which execute behavioral verification across project and workspace scopes.
Sources: AGENTS.md:52-67, scripts/cmd/val/all.py:1-20
Architecture Overview
The gate system is built upon a registry-driven dispatcher that translates high-level make commands into specific validation logic. This architecture ensures that all quality actions are centralized, reproducible, and verifiable.
Command Dispatch Flow
When an operator triggers a gate (e.g., make check or make val), the Dispatch system identifies the target scope, validates environment-backed options, and executes the corresponding private Make targets or Python scripts.
The diagram shows the hierarchical flow from a user action through the registry-driven dispatch system to specific gate executions.
Sources: scripts/cmd/val/all.py:44-77, scripts/lib/surface_validation.py:17-38, scripts/tests/test_registry_contract.py:38-51
Validation Gates (val)
Validation gates are responsible for enforcing project-level and workspace-level contracts. They are orchestrated by the FlextRootValAllCommand, which consumes the VALIDATE_SCOPE environment variable to determine the execution path.
Validation Scopes
| Scope | Target | Description |
|---|---|---|
workspace | _val_workspace | Runs gates encompassing the entire monorepo. |
project | _val_project | Runs gates scoped to a specific PROJECT. |
all | Both | Executes both workspace and project validation (default). |
Sources: scripts/cmd/val/all.py:34-42, scripts/cmd/val/all.py:72-77
Implementation Logic
The validation system uses Pydantic models to normalize and validate input options (like VALIDATE_SCOPE) before dispatching to Make targets.
class Options(m.Value):
scope: Annotated[
Literal["project", "workspace", "all"],
u.Field(description="Validation scope to execute."),
] = "all"
@property
def targets(self) -> tuple[str, ...]:
if self.scope == "workspace":
return ("_val_workspace",)
if self.scope == "project":
return ("_val_project",)
return ("_val_workspace", "_val_project")
Sources: scripts/cmd/val/all.py:34-56
Check Gates (check)
Check gates focus on static quality metrics and standardization compliance. One of the most critical gates is Docker Standardization, which prevents the proliferation of rogue infrastructure configurations.
Docker Standardization Checks
The _DockerStandardizationChecker validates that all Docker artifacts are centralized in the docker/ directory and that shared testing fixtures are importable.
- Duplicate Detection: Scans for
docker-compose.ymlorDockerfileinstances outside ofdocker/anddocker/images/. - Centralization Count: Ensures at least 15 centralized compose files and 20 Dockerfiles exist.
- Fixture Availability: Verifies that the
tk(test kit) and centralized fixtures (e.g.,oracle_container,ldap_container) are importable fromflext_tests. - Deprecated Patterns: Detects usage of legacy
parallel_dockermodules.
Sources: scripts/cmd/check/docker_standardization.py:38-164
Quality Tools (Lint/Type)
FLEXT mandates a "Continuous Green" policy, requiring several static gates to pass for all code, including examples and scripts:
- Ruff: Primary linter and formatter.
- Pyright / Mypy: Strict type-checking gates.
- Pyrefly: Structural and type-safe analysis.
Sources: AGENTS.md:52-67, pyproject.toml:211-380
Surface Validation
Surface validation is a specialized gate that ensures the integrity of the Makefile command surface. It prevents "broken" or "target-missing" routes from being promoted to the public CLI.
Verification Sequence
The sequence demonstrates how the SurfaceValidator cross-references the discovered Python command registry against the actual targets defined in the root Makefile.
Sources: scripts/lib/surface_validation.py:22-54
Validation Metrics
The SurfaceValidator provides a summary of the validated surface, reporting the total number of public verbs and specific WHAT routes successfully verified.
Sources: scripts/lib/surface_validation.py:34-37
Governance Constraints
The gate system is governed by the "Universal Agent Law" and "FLEXT Canonical Engineering Law." These rules are non-negotiable:
- Zero-Tolerance for Bypass: Every gate failure is an incident that must be fixed at the root. Workarounds or suppression are prohibited.
- Continuous Green: Completion is not declared until all gates (Ruff, Pyrefly, Pyright, Mypy, and Pytest) are green.
- Typed Boundaries: Untrusted inputs (like environment variables for
make val) must be parsed once into canonical types using Pydantic.
Sources: AGENTS.md:52-67, AGENTS.md:144-162, AGENTS.md:209-222
Summary
Check and Validation Gates provide the "inviolable governance chain" for the FLEXT ecosystem. By combining static analysis (Check) with behavioral and architectural verification (Validation), the project ensures that all packages (flext-*) maintain strict typing and architectural parity. The system’s reliance on a centralized registry and surface validation guarantees that the developer experience remains consistent and that quality standards are enforced automatically across the entire monorepo.
Sources: AGENTS.md:89-100, README.md:5-10