Quality Gates & Makefile
Relevant source files
The following files were used as context for generating this wiki page:
Quality Gates and the Makefile architecture provide a standardized, automated validation pipeline for the flext-grpc platform. These systems ensure that all code contributions adhere to strict engineering standards, including type safety, linting compliance, and testing thresholds. The infrastructure is designed to provide rapid feedback to developers and enforce a "Zero-Debt Baseline" across the repository.
The system relies on a set of canonical make verbs that trigger specific validation phases. These gates are mandatory and must pass in their entirety before any code is committed or deployed. This structured approach facilitates Clean Architecture compliance and Domain-Driven Design (DDD) integrity by ensuring that technical debt is addressed as it appears.
Sources: README.md:32-34, src/README.md:144-149, AGENTS.md:27-33
Automated Quality Pipeline
The project utilizes a Makefile to orchestrate a multi-stage validation pipeline. This pipeline covers everything from code formatting to advanced static analysis and comprehensive test execution.
Canonical Make Verbs
The following table summarizes the primary commands used to interface with the Quality Gates:
| Command | Purpose | Scope |
|---|---|---|
make check | Quick health check | Linting and basic type checking |
make test | Run test suite | Executes tests and enforces coverage minimums |
make val | Full validation | Complete pipeline including all gates |
make docs | Generate documentation | Builds enterprise-grade documentation |
make mod | Modernize dependencies | Regenerates managed pyproject.toml sections |
Sources: README.md:32, tests/README.md:204-208, pyproject.toml:3-5
Validation Logic Flow
The Quality Gate execution follows a specific sequence to ensure that faster, shallow checks (like linting) block more expensive operations (like full E2E test suites).
This diagram illustrates the hierarchical nature of the gates, where failures in early linting or typing phases prevent the execution of subsequent testing phases.
Sources: src/README.md:144-154, tests/README.md:195-201
Static Analysis Gates
Static analysis is enforced through a combination of strict linting rules and "most-restrictive" typing protocols.
Linting Standards (Ruff)
The project adopts a "zero tolerance" policy for linting errors. The configuration in pyproject.toml enables the ALL rule set for Ruff, with specific exclusions documented to maintain balance between strictness and practical development.
- Line Length: Enforced at 88 characters.
- Docstring Format: Enforced for 100% coverage across modules.
- Target Version: Python 3.13.
Sources: src/README.md:151, pyproject.toml:390-410, src/flext_grpc/README.md:155-160
Type Safety (MyPy & Pyright)
The project utilizes both MyPy and Pyright for deep static type checking.
- MyPy Strict Mode: All parameters and return types must be explicitly typed.
- No Fallbacks: Use of
Anyorobjectis forbidden unless accompanied by a one-line documented justification. - Protocol Validation: Strict protocol definitions are used for external library integration (e.g., gRPC stubs).
Sources: src/README.md:118-121, AGENTS.md:88-91, pyproject.toml:98-115
Testing Gates and Coverage
Testing is a critical gate that must be cleared before any scoped work is "Done." The project enforces a multi-tier testing architecture with explicit performance and coverage thresholds.
Coverage Requirements
The target for code coverage is 90% across the entire project. Currently, certain modules have identified gaps that must be addressed during development:
- Target: 90%+ Minimum.
- Enforcement:
make testfails if thefail_underthreshold (currently set to 25 inpyproject.tomlbut functionally targeted higher) is not met during specific CI runs.
| Module | Current Coverage | Status |
|---|---|---|
types.py | 100% | Excellent |
api.py | 82% | Good |
entities.py | 76% | Needs Improvement |
platform.py | 68% | Critical Gap |
Sources: tests/README.md:27-28, tests/README.md:109-119, pyproject.toml:79-84
Test Execution Categories
Tests are categorized using Pytest markers to allow for selective gate execution:
@pytest.mark.unit: Fast, isolated tests (< 100ms per test).@pytest.mark.integration: Component interaction tests (< 1s per test).@pytest.mark.e2e: Complete workflow validation (< 10s per test).
Sources: tests/README.md:86-96, tests/README.md:179-183
Engineering Principles (Universal Agent Law)
The Quality Gates are underpinned by the Universal Agent Law, a set of inviolable rules for engineering conduct. These rules dictate that a gate is not "passed" if a symptom is merely hidden.
- Zero-Tolerance: Never classify a failure as "acceptable legacy." If it surfaces in your flow, you own the fix.
- Fix-Forward-Only: Reverting shared work to pass a gate is forbidden.
- No Workarounds: Suppression directives like
# type: ignoreoreslint-disableare defects. - Evidence Mandatory: "Done" requires objective evidence (command output + exit code 0).
Sources: AGENTS.md:14-25, AGENTS.md:40-45, AGENTS.md:58-63
Summary
The Quality Gates and Makefile infrastructure in flext-grpc serve as the primary enforcement mechanism for high-performance enterprise standards. By automating linting, strict typing, and multi-tier testing, the project ensures that Clean Architecture and DDD principles remain intact. Developers must utilize the canonical make commands to validate their work, ensuring that every contribution maintains the project's zero-debt baseline.
Sources: src/README.md:144-155, AGENTS.md:8-12