Quality Gates & Governance

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• pyproject.toml
• tests/README.md
• tests/unit/test_module_governance.py
• mkdocs.yml

Quality Gates & Governance within the flext-target-oracle project represent the standardized enforcement of code quality, structural integrity, and architectural principles. These gates ensure that every contribution adheres to the "Engineering Law" defined in the FLEXT ecosystem, maintaining a zero-debt baseline and strict type safety across the integration service.

The governance model utilizes automated checks (via make verbs), a multi-tiered testing strategy, and specialized module-level inspections to prevent anti-patterns such as unauthorized top-level functions or module-level loggers. This framework provides a canonical checklist for developers to follow before submitting changes to the codebase.

Sources: README.md:38-46, CONTRIBUTING.md:158-164

Automated Quality Checks

The project employs a set of canonical make verbs that serve as the primary quality gates. These commands consolidate linting, formatting, and type-checking into a unified interface enforced during development and CI/CD pipelines.

Standard Quality Verbs

Command	Description	Tooling
make check	Runs all quality checks (linting, types, format)	Ruff, MyPy, Black
make format	Automatically formats code and docstrings	Black, Ruff, isort
make lint	Performs static analysis and security scanning	Ruff, Bandit, Pylint
make type-check	Enforces strict static typing	MyPy, Pyright
make val	Performs domain validation and schema checks	Pydantic

Sources: CONTRIBUTING.md:104-123, README.md:38-41, pyproject.toml:170-220

Code Style and Linting Standards

Governance is enforced through strict configuration in pyproject.toml. The project mandates:

• Strict Typing: All code must be fully typed; mypy is configured with strict_equality = true and warn_unreachable = true.
• Formatting: Uses Black + Ruff with a standard line length of 88 characters.
• Banned APIs: Governance prevents the use of certain libraries (e.g., simplejson, colorama, typer) in favor of internal flext_cli alternatives to maintain ecosystem consistency.

Sources: CONTRIBUTING.md:92-102, pyproject.toml:237-250, pyproject.toml:440-480

Testing Hierarchy

The testing suite is a critical quality gate, categorized by scope and dependency requirements. Integration and End-to-End (E2E) tests are gated by the availability of an Oracle Docker environment.

The diagram shows the categorization of tests and the specific dependencies required for each level of the quality gate.

Sources: tests/README.md:12-25, CONTRIBUTING.md:65-80

Coverage Requirements

The project enforces a minimum code coverage threshold as a non-negotiable quality gate.

• Target: 80% minimum coverage for new features.
• Reporting: Coverage is tracked via pytest-cov and reports are generated in HTML, JSON, and terminal formats.

Sources: tests/README.md:108-111, pyproject.toml:132-140

Module Governance and Structural Integrity

Specific governance tests inspect the live module objects to ensure they comply with the architectural design principles of the FLEXT ecosystem. This is implemented in tests/unit/test_module_governance.py.

Structural Rules

1. No Module-Level Loggers: Assignments of logger or _logger at the top level of a module are forbidden. This prevents initialization side effects.
2. Restricted Top-Level Functions: Functions defined outside of approved entrypoints are flagged as violations.
3. MRO Integrity: The target-oracle namespace must not directly wrap meltano or singer models; instead, it must use the proper MRO (Method Resolution Order) cascade.

Sources: tests/unit/test_module_governance.py:73-113, README.md:28-36

Architectural Compliance Flow

The following sequence illustrates how governance is verified during the import of a module.

This diagram visualizes the process used by the governance suite to inspect modules for architectural violations without parsing source code directly.

Sources: tests/unit/test_module_governance.py:46-71

Dependency and Vulnerability Scanning

Governance extends to the supply chain through automated dependency analysis.

• Vulnerability Checks: pip-audit and bandit are used to scan for known security flaws.
• Dependency Integrity: deptry is utilized to ensure that only declared dependencies are used and that no "dead" dependencies remain in pyproject.toml.
• Pre-commit Hooks: Automated checks are performed locally via pre-commit to catch formatting or linting errors before code is committed to version control.

Sources: pyproject.toml:68-120, CONTRIBUTING.md:125-130, pyproject.toml:144-150

Summary

Quality Gates & Governance in flext-target-oracle provide a rigorous framework that ensures the project remains maintainable, secure, and architecturally sound. By combining standard linting (make check), specialized structural tests (test_module_governance.py), and a multi-stage testing pipeline, the project enforces a high bar for technical excellence. Developers are required to pass all gates—from type safety to coverage thresholds—before contributions are merged into the main repository.

Sources: README.md:38-48, CONTRIBUTING.md:188-195