Quality Gates & Make Contracts

Relevant source files

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

• README.md
• AGENTS.md
• pyproject.toml
• rules.json
• tests/unit/test_module_governance.py
• tests/unit/_config_parts/validation.py

Quality Gates and Make Contracts represent the enforcement layer of the flext-dbt-oracle project, ensuring that every change meets the strict architectural and operational standards defined in the project's governance. This system relies on a "Continuous Green" philosophy where no task is considered complete unless all canonical gates—ranging from static linting and type checking to unit and integration testing—pass without exception.

The core of this enforcement is the Make Contract, a set of canonical make verbs that serve as the only authorized entry points for building, checking, and validating the project. These gates ensure that configuration changes are validated by construction and that the project remains free of architectural debt, such as unauthorized top-level functions or module-level loggers.
Sources: README.md:37-39, AGENTS.md:65-71, AGENTS.md:154-162

Canonical Make Contract

All validation and development actions must be executed through the project's canonical make verbs. Invoking tools directly (e.g., calling pytest or ruff manually) is prohibited as it bypasses the guards, locks, and evidence-gathering mechanisms built into the make surface.

Primary Quality Verbs

The project defines several key verbs for quality enforcement:

• make check: Runs static analysis, including linting and formatting checks.
• make test: Executes the full test suite, including unit and integration tests.
• make val: Performs validation of configurations and settings.
• make docs: Generates and validates project documentation and executable snippets.
  Sources: README.md:37-39, AGENTS.md:154-160

Execution Flow of Quality Gates

The following diagram illustrates the flow from code modification to the final "Done" state through the Make Contract.

Static Analysis Gates

The project implements a zero-tolerance policy for static analysis violations. This includes strict typing and the prohibition of suppression directives (e.g., # type: ignore) unless accompanied by documented justification.

Tooling and Thresholds

Static gates cover all directories, including examples/, scripts/, and tests/, with the same rigor as the src/ directory.

Tool	Purpose	Configuration Source
Ruff	Linting and formatting	pyproject.toml [tool.ruff]
Pyright / Mypy	Static type checking	pyproject.toml [tool.pyright]
Pyrefly	Advanced Python static analysis	pyproject.toml [tool.pyrefly]
Coverage	Minimum 20% total coverage	pyproject.toml [tool.coverage.report]
Sources: pyproject.toml:98-103, pyproject.toml:130-153, AGENTS.md:65-74

Module Governance Gates

Specialized governance tests ensure that the internal structure of the Python package adheres to architectural constraints. These tests prevent the accumulation of patterns that complicate maintenance or testing.

Prohibited Patterns

1. Module-level Loggers: Packages modules are forbidden from defining logger or _logger at the top level.
2. Top-level Functions: Package modules must use classes or other structured entities; naked top-level functions are prohibited.
3. PostgreSQL Dependencies: As an Oracle-specific adapter, any inclusion of psycopg2 or dbt-postgres is strictly forbidden.
   Sources: rules.json:118-122, tests/unit/test_module_governance.py:65-98

Configuration Validation Gates

Configuration is treated as a first-class citizen. Tests are designed to validate that changes to FlextDbtOracleSettings do not break the system, while ensuring that the settings themselves are internally consistent.

Validation Rules for Settings

• Mandatory Fields: host, username, password, and schema are required for Oracle integration.
• Range Validation: Numeric fields like pool_max_size must be greater than pool_min_size.
• Type Constraints: Enums for materialization (table, view, incremental, snapshot) and protocol (tcp, tcps) are strictly enforced via Pydantic.
  Sources: rules.json:19-21, tests/unit/_config_parts/validation.py:58-95

Validation Logic Flow

Conclusion

Quality Gates and Make Contracts in flext-dbt-oracle ensure that the project remains technically sound and architecturally consistent. By mandating that all changes pass through canonical make verbs and strict static/dynamic validation, the project enforces a high bar for engineering excellence, preventing regressions and ensuring that the Oracle adapter remains robust and maintainable.