Refactor Governance Rulesets
Relevant source files
The following files were used as context for generating this wiki page:
Refactor Governance Rulesets represent a structured framework for automating code modernization, namespace enforcement, and architectural consistency across the FLEXT ecosystem. These rules define how code should be transformed, validated, and migrated to meet project standards, covering aspects from simple text replacements to complex AST-based class nesting and MRO (Method Resolution Order) migrations.
The system operates through an orchestration layer that coordinates rule loading, violation analysis, and safe execution. By codifying engineering standards into executable YAML mappings and Python-based logic, the project ensures that architectural patterns like facade-based namespaces and unified typing remain consistent across all governed packages.
Sources: src/flext_infra/refactor/orchestrator.py:28-40, src/flext_infra/_constants/refactor.py:44-67
Core Rule Architecture
The governance system categorizes refactor operations into two primary types: Text Rules (regex-based) and File Rules (Rope/AST-backed). These are managed by a central orchestrator that applies transformations in a specific sequence to ensure stability.
Refactor Rule Categories
The project identifies several canonical rule kinds that govern specific architectural areas:
| Rule Kind | Type | Description |
|---|---|---|
FUTURE_ANNOTATIONS | Text | Ensures from __future__ import annotations is present in all modules. |
MRO_CLASS_MIGRATION | AST | Migrates standalone symbols into facade classes (MRO chains). |
CLASS_NESTING | AST | Enforces hierarchical class structures based on namespace policies. |
IMPORT_MODERNIZER | Text | Replaces direct imports with canonical aliases or hoists symbols. |
LEGACY_REMOVAL | Text | Inlines or removes deprecated functions and models. |
PATTERN_CORRECTIONS | Text | Fixes common anti-patterns like redundant type casts or dict-to-mapping conversions. |
| Sources: src/flext_infra/_constants/refactor.py:101-131, src/flext_infra/_constants/refactor.py:192-196 |
Orchestration Flow
The refactor process follows a strict execution pipeline to prevent source corruption. The orchestrator first applies file-level (AST) transformations, followed by text-level replacements, and finally validates the result through a "Protected Source Write" mechanism.
The workflow ensures that any transformation that breaks syntax or violates "Quality Gates" is automatically rolled back or blocked.
Sources: src/flext_infra/refactor/orchestrator.py:80-116, src/flext_infra/refactor/_orchestrator_dispatch.py:109-125
Class Nesting & Namespace Enforcement
A significant part of the governance ruleset is dedicated to CLASS_NESTING. This enforces that top-level classes in private directories or those lacking proper prefixes are moved into their appropriate facade namespaces.
Nesting Policy
Rules are defined in class-nesting-mappings.yml, which maps "loose" class names to their target namespaces based on architectural classification (e.g., utility, models, decorators).
| Target Namespace | Prefix | Classification Priority |
|---|---|---|
FlextUtilities | FlextUtilities | Low (4) |
FlextModels | FlextModels | Medium (3) |
d | FactoryDecorators | High (2) |
FlextDispatcher | FlextDispatcher | Critical (1) |
| Sources: src/flext_infra/_constants/refactor.py:456-464, src/flext_infra/rules/class-nesting-mappings.yml:4-40 |
Violation Detection
The FlextInfraRefactorLooseClassScanner identifies violations based on confidence levels (High, Medium, Low) and scores. Reasons for violation include:
top_level_class_in_private_directory: Classes defined at the module level inside folders like_utilities/.top_level_class_without_namespace_prefix: Classes likeMetadataorHandlethat lack the project-standard prefix.nested_class_inside_FlextModelsBase: Classes that should be promoted or further nested.
Sources: src/flext_infra/_models/refactor.py:149-163, src/flext_infra/rules/class-nesting-mappings.yml:4-60
MRO and Symbol Propagation
Governance rules facilitate the transition from flat module structures to MRO-based facade classes. This involves moving functions and constants into specific facade families: c (Constants), t (Types), p (Protocols), m (Models), and u (Utilities).
Facade Family Mapping
The system uses standardized suffixes and directories for these families to maintain workspace consistency.
Symbol Relocation Logic
When a symbol is moved to a facade, the FlextInfraRefactorMROImportRewriter propagates these changes across the entire workspace. This ensures that all consumer imports are updated from from pkg.module import symbol to from pkg import c (and usage c.symbol).
Sources: src/flext_infra/refactor/mro_import_rewriter.py:34-70, src/flext_infra/_utilities/namespace_moves.py:349-385
Safety and Validation Mechanisms
To maintain a "zero-debt baseline," all refactor operations are subject to quality gates.
Protected Source Writes
Before any file is written to disk, the ProtectedSourceWritesRequest performs:
- Syntax Verification: Ensures the transformed code is valid Python.
- Gate Checks: Runs canonical
makeverbs (check,test,val). - Backup Creation: Generates
.bakfiles to allow for manual recovery.
Sources: src/flext_infra/refactor/orchestrator.py:177-202, src/flext_infra/_utilities/namespace_moves.py:532-550
Confidence Ranking
Violations detected by the rulesets are ranked to prioritize architectural fixes:
- High (Score 0.95): Direct violations of core engineering law (e.g.,
AGENTS.md§9). - Medium (Score 0.75): Naming inconsistencies and non-canonical aliases.
- Low (Score 0.55): Potential improvements or ambiguous loose objects.
Sources: src/flext_infra/_constants/refactor.py:437-446, src/flext_infra/_models/refactor.py:155-163
Refactor Governance Rulesets are the primary mechanism for maintaining the structural integrity of the FLEXT project, enabling large-scale migrations with high confidence and minimal manual intervention.