Architecture Enforcement Validator
Relevant source files
The following files were used as context for generating this wiki page:
- src/flext_core/_constants/_enforcement_data/smells.json
- src/flext_core/_utilities/_enforcement_parts/enforcement_part_04.py
- src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_03.py
- src/flext_core/_constants/_enforcement_catalog_rows_parts/flextconstantsenforcementcatalogrows_part_04.py
- tests/integration/test_architecture.py
- tests/unit/test_enforcement_reports.py
- tests/unit/test_enforcement_apt_hooks.py
The Architecture Enforcement Validator is a core quality gate system within the FLEXT framework designed to enforce structural integrity, clean architecture principles, and code health. It operates by scanning project source code, package structures, and configurations against a predefined "Canonical Enforcement Catalog" of rules and thresholds. Sources: README.md:38-40, tests/integration/test_architecture.py:10-15
The system identifies architectural "smells" and violations across multiple domains including imports, type safety, and naming conventions. It provides automated feedback through a report-based system that can trigger warnings or build-time exceptions depending on the configured enforcement mode. Sources: src/flext_core/_constants/_enforcement_data/smells.json:2-10, tests/unit/test_enforcement_reports.py:126-140
Core Validation Logic and Workflow
The validator functions by executing a suite of specific "verbs" (methods) that target different aspects of the codebase. Each verb returns a ScanResult which encapsulates the findings and status of the validation. Sources: tests/integration/test_architecture.py:27-35
The diagram shows the high-level flow from initiating a validation check to the generation of a ScanResult. Sources: tests/integration/test_architecture.py:38-65, src/flext_core/_utilities/_enforcement_parts/enforcement_part_04.py:46-60
Validator Verbs
The system supports several public dispatch methods for targeted scanning:
imports: Detects circular dependencies and illegal cross-project imports.types: Enforces strict typing rules and usage of canonical type aliases.layer: Validates that modules adhere to the layered architecture (e.g., Models should not import Utilities).validate_config: Scans project metadata and configuration files.all: Aggregates the results from all individual validators into a single unified report.
Sources: tests/integration/test_architecture.py:53-65, tests/unit/test_enforcement_catalog.py:65-75
Enforcement Catalog and Rule Structure
The system is built around an EnforcementCatalog which acts as the Single Source of Truth (SSOT). This catalog is built from various "rows" of data representing different rule families. Sources: src/flext_core/_utilities/_enforcement_parts/enforcement_part_04.py:46-52
Rule Families
Rules are categorized by their source and detection mechanism:
| Rule Family | Source | Description |
|---|---|---|
| Infra Detector | c.INFRA_DETECTOR_ROWS | Rules for file presence, structural missing pieces, and project layout. |
| Beartype Hooks | c.BEARTYPE_ROWS | Runtime type-checking and syntax-based rules (e.g., no cast() outside core). |
| Code Smells | smells.json | Quantitative thresholds for cyclomatic complexity and nesting. |
| Ruff | c.RUFF_ROWS | Integration with Ruff linting rules for documentation-only catalog entries. |
| Tests Validator | c.TESTS_VALIDATOR_ROWS | Rules specifically enforced during test execution or CI gates. |
Sources: src/flext_core/_utilities/_enforcement_parts/enforcement_part_04.py:58-135, src/flext_core/_constants/_enforcement_data/smells.json:1-12
Violation Severity and Reporting
Every violation emitted by the validator includes specific metadata to assist in remediation.
The relationship between validation summaries and specific rule violations. Sources: tests/integration/test_architecture.py:115-130, tests/unit/test_enforcement_reports.py:61-75
Code Smells and Thresholds
The validator includes a dedicated module for detecting code smells based on quantitative metrics. These metrics are configurable via a central JSON specification. Sources: src/flext_core/_constants/_enforcement_data/smells.json:2-10
| Threshold Key | Value | Description |
|---|---|---|
params | 5 | Maximum allowed parameters for a single function. |
returns | 5 | Maximum allowed return statements in a function. |
nesting | 4 | Maximum allowed levels of nested control flow. |
fn_cx | 14 | Maximum cyclomatic complexity per function. |
file_cx | 49 | Maximum cyclomatic complexity per module/file. |
Sources: src/flext_core/_constants/_enforcement_data/smells.json:2-8
Automated Fix Strategies
The validator identifies whether a rule violation can be automatically corrected:
- Auto-fixable: Rules like
smell_boolean_logichave an associated fixer (boolean_logic) that can simplify expressions. - Manual Review: Structural issues like
smell_file_complexityorsmell_function_parametersrequire manual refactoring as no safe automated path exists.
Sources: src/flext_core/_constants/_enforcement_data/smells.json:13-45
Namespace Enforcement Rules
A specific subset of the validator focuses on "Namespace Integrity," ensuring that classes and modules are named and placed according to FLEXT conventions. Sources: src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_03.py:27-35
- Facade Prefixing: Classes within the core layers (Constants, Models, Protocols, Types, Utilities) must follow the
Flext<Project><Layer>naming pattern. Sources: tests/unit/test_enforcement_models.py:133-145 - Alias Enforcement: Consumer projects must use canonical short aliases (
c,m,p,t,u) when importing from facade layers. Sources: src/flext_core/_constants/_enforcement_catalog_rows_parts/flextconstantsenforcementcatalogrows_part_04.py:137-142 - MRO Linearization: Multi-parent facade classes must list the canonical alias as the first base to ensure correct C3 MRO linearization. Sources: src/flext_core/_constants/_enforcement_catalog_rows_parts/flextconstantsenforcementcatalogrows_part_04.py:80-85
Summary
The Architecture Enforcement Validator serves as the primary technical governance mechanism in FLEXT-Core. By combining static file analysis, runtime type hooks, and quantitative complexity metrics, it ensures that all extensions and consumer projects maintain the "Clean Architecture" standards required for enterprise foundation frameworks. Its report-driven design allows for flexible integration into CI/CD pipelines while providing developers with clear, actionable fix guidance. Sources: README.md:1-10, tests/integration/test_architecture.py:10-20