Quality Gates & Make Contract
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Quality Gates & Make Contract" defines the mandatory engineering standards, validation requirements, and automated workflows ensuring the integrity of the flext-tap-ldap project. It establishes a "Zero-Debt Baseline" where every contribution must pass a predefined set of canonical checks before being considered "Done." This system is primarily governed by the Universal Agent Law and executed via standardized make verbs.
These gates encompass static analysis, type safety, security auditing, and comprehensive testing suites. The project utilizes a Make Contract to provide a consistent interface for both human developers and AI agents to trigger these validations, ensuring that root causes are addressed generically and code is validated against the Single Source of Truth (SSOT).
Sources: README.md:46-51, AGENTS.md:12-25
Engineering Law & Conduct
The core of the Quality Gates is the Universal Agent Law, an inviolable set of rules that bind all participants in the repository. This law mandates a "Zero-Tolerance" approach to technical debt and workarounds.
Core Principles
- SSOT (Single Source of Truth): One authoritative source per fact; reference it without duplication and fail loud if absent.
- Zero-Tolerance: Classifying surfaced failures as "unrelated" or "acceptable legacy" is strictly forbidden.
- Root Cause Only: Bypassing symptoms with
TODOs, stubs, or suppression directives (e.g.,# type: ignore) is prohibited unless accompanied by a one-line justification. - Evidence Before Done: Validation must be objective, including the exact command, exit code, and relevant output.
Sources: AGENTS.md:16-36, AGENTS.md:92-106
The Make Contract
The project provides canonical make verbs that act as the interface for Quality Gates. These commands are the entry points for the validation thresholds required for any code landing.
| Verb | Description | Thresholds / Selectors |
|---|---|---|
check | Static analysis, linting, and formatting checks. | ruff, black, isort, codespell |
test | Execution of unit and integration test suites. | pytest with pytest-cov |
val | Deep validation including type checking and security. | mypy, pyright, bandit, deptry |
docs | Documentation generation and integrity check. | mkdocs |
mod | Managed dependency and pyproject modernization. | flext_infra.deps.modernizer |
Sources: README.md:51-54, pyproject.toml:1-5
Automated Validation Flow
The following diagram illustrates the sequence an agent or developer must follow to satisfy the Quality Gates contract before landing work.
The flow emphasizes the Fix-Forward-Only rule, where reverting shared state is forbidden; all failures must be resolved in the current working tree.
Sources: AGENTS.md:38-45, AGENTS.md:55-60
Validation Specifications
The Quality Gates are backed by specific tool configurations defined in pyproject.toml. These tools enforce the technical standards required by the project.
Type Safety & Static Analysis
The project enforces strict typing using mypy and pyright.
- Mypy: Configured with
strict_equality = trueandcheck_untyped_defs = true. It forbids implicit re-exports and requires proper return type annotations. - Pyright: Set to
stricttype checking mode with specific environments forsrc(enforcing private usage errors) andtests. - Ruff: Used for linting with the
ALLselection, though specific rules likeANN202(missing return type for private functions) are ignored to balance productivity.
Sources: pyproject.toml:142-167, pyproject.toml:343-379, pyproject.toml:476-488
Security & Dependency Integrity
- Bandit: Used for identifying common security issues in Python code.
- Deptry: Ensures dependency health by checking for missing, obsolete, or transitive dependencies.
- Pip-audit: Scans dependencies for known vulnerabilities.
Sources: pyproject.toml:68-115
Coverage Thresholds
The project tracks testing coverage via pytest-cov. While specific modules may have varying requirements, the global configuration requires a minimum threshold and precision for reporting.
[tool.coverage.report]
fail_under = 20
precision = 2
show_missing = true
Sources: pyproject.toml:127-133
LDIF & Data Processing Gates
For LDAP-specific data handling, the u.TapLdap.Validator and Processor classes within src/flext_tap_ldap/_utilities/_processor.py act as internal quality gates for data integrity.
Validation Logic
The Validator class leverages the flext-ldif library to ensure entries comply with LDAP standards before they are processed by the tap.
Statistics Reporting
The Processor tracks quality metrics during execution, which can be retrieved via the statistics() method.
processed_entries: Successfully parsed entries.skipped_entries: Entries that failed coercion or validation.errors: A list of specific failure messages encountered.
Sources: src/flext_tap_ldap/_utilities/_processor.py:175-185
Conclusion
Quality Gates and the Make Contract in flext-tap-ldap serve as the foundation for reliable, debt-free engineering. By requiring strict type safety, zero-workaround fixes, and objective evidence for "Done," the project maintains a high standard of code quality that is resistant to regression and compatible with multi-agent coordination.
Sources: AGENTS.md:16-25, README.md:46-51