Quality Gates & Governance Tests
Relevant source files
The following files were used as context for generating this wiki page:
Quality Gates and Governance Tests in the flext-target-oracle-wms project represent a multi-layered verification system designed to ensure code integrity, architectural compliance, and performance reliability. These gates act as automated checkpoints that enforce strict engineering standards across the codebase, from module-level organization to real-time performance metrics.
The system is governed by the Universal Agent Law, which mandates zero-tolerance for technical debt, root-cause resolution for defects, and strict adherence to established software patterns. This governance extends beyond logic tests to include static analysis, dependency validation, and documentation accuracy.
Sources: AGENTS.md:6-30, README.md:37-39
Architectural Governance
The project implements a strict structural contract to prevent architectural erosion. Governance tests ensure that modules do not deviate from the prescribed organizational patterns, such as the avoidance of global state and the enforcement of namespace isolation.
Module Structure Enforcement
Governance checks specifically target module-level behavior to ensure consistency across the project. Key constraints include:
- Prohibition of Module-Level Loggers: Loggers must not be assigned at the top level of modules; they should be fetched via specific patterns like
u.fetch_logger(__name__). - Restricted Top-Level Functions: Functions defined at the module level are forbidden unless they reside in approved entry points or utility modules.
- Namespace Isolation: Singer message models must not be redefined locally within the WMS namespace, ensuring a Single Source of Truth (SSOT) from the core libraries.
Sources: tests/unit/test_module_governance.py:65-103, tests/examples/test_examples.py:276-285
Governance Validation Flow
The following diagram illustrates how a code change is evaluated against governance and quality standards.
The flow ensures that any deviation from engineering law results in a hard failure, preventing sub-standard code from being merged.
Sources: AGENTS.md:16-25, tests/unit/test_module_governance.py
Quality Gate Tooling
The project leverages a comprehensive suite of static analysis tools configured within pyproject.toml to enforce coding standards and type safety.
| Tool | Purpose | Enforcement Level |
|---|---|---|
| Ruff | Linting and formatting | Strict (All rules enabled) |
| Mypy | Static type checking | Strict (3.13 configuration) |
| Pyright | Type analysis | Strict (Linux platform validation) |
| Deptry | Dependency management | Verification of known first-party libs |
| Coverage | Testing depth | Fail under 20% (Project specific) |
| Codespell | Documentation integrity | Filename and content spellcheck |
Sources: pyproject.toml:140-350
Component Quality Validation
Unit tests verify that core components such as the CatalogManager, WMSTableManager, and WMSDataTransformer can be instantiated and follow the target-oracle-wms naming conventions.
Sources: tests/unit/test_quality.py:65-95
Performance Gates
Performance is monitored through benchmarks that enforce maximum execution time thresholds for high-frequency operations. If a component's performance regresses beyond these thresholds, the quality gate fails.
- Iteration Scaling: Tests typically run for a defined number of iterations (
PERF_ITERATIONS). - Timing Thresholds: Components must complete operations within
PERF_THRESHOLD_SEC. - Scope: Operations include type conversion (string/integer), stream registration, schema mapping, and target creation.
Sources: tests/unit/test_benchmarks.py:35-105
Documentation and Example Governance
Examples provided in the repository are treated as production code and are subject to their own set of quality gates. This ensures that user-facing documentation remains functional and follows best practices.
- Real Import Enforcement: Examples must use real
flext-coreandflext-target-oracle-wmsimports rather than mocks or fallbacks. - Error Handling: Examples must implement visible error handling patterns, such as checking
.successor.is_failureon results. - Header Compliance: Every example file must contain a shebang, a copyright notice, and an MIT license notice.
- Docstring Coverage: At least 80% of functions within examples must be documented with comprehensive docstrings.
Sources: tests/examples/test_examples.py:100-245
Conclusion
The Quality Gates and Governance Tests within the flext-target-oracle-wms project form a defensive perimeter that guarantees architectural purity and operational performance. By combining structural constraints (no module loggers), strict typing (Mypy/Pyright), and performance thresholds, the project ensures that every commit adheres to the "Zero-Tolerance" policy for technical debt. This automated governance framework allows multiple agents to contribute while maintaining a consistent, production-grade baseline.