Module Governance & Imports Testing

Relevant source files

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

• tests/unit/test_module_governance.py
• tests/unit/test_imports.py
• AGENTS.md
• tests/__init__.py
• src/flext_dbt_oracle/__init__.py
• tests/unit/test_basic.py

Module Governance and Imports Testing within the flext-dbt-oracle project ensures that the codebase adheres to strict structural standards and maintainability rules. This system validates that the package structure remains clean, prevents anti-patterns such as module-level loggers or global functions in specific tiers, and ensures that the library remains importable even in environments lacking a full dbt runtime.

The governance framework is part of a broader "Continuous Green" philosophy where quality gates (Lint, Type, and Test) are applied with equal rigor to production source and test suites. This ensures that the project avoids technical debt and maintains a consistent architectural pattern across all modules.
Sources: AGENTS.md:57-73, tests/unit/test_module_governance.py:65-92

Architectural Governance Principles

The project follows a set of inviolable engineering laws that dictate how code should be structured and validated. Central to this is the requirement that tests must validate configuration changes by construction rather than hardcoding values.

Core Governance Rules

• No Module-Level Loggers: Production modules are forbidden from defining logger or _logger at the top level to avoid initialization side effects.
• No Top-Level Functions: Package modules must avoid top-level function definitions, favoring object-oriented patterns or specific namespace containers.
• Lazy Exports: To optimize performance and manage dependencies, the project heavily utilizes a lazy loading mechanism for imports.
• Zero-Tolerance Policy: Governance failures are treated as root-cause defects that must be fixed immediately; workarounds or suppressions are strictly prohibited.

Sources: tests/unit/test_module_governance.py:68-92, AGENTS.md:144-156, src/flext_dbt_oracle/init.py:57-62

Governance Validation Flow

The following diagram illustrates how the governance test suite inspects the package structure to enforce rules.

The governance suite recursively crawls the src directory, attempts to import each module, and inspects its attributes using the inspect and vars modules.
Sources: tests/unit/test_module_governance.py:16-63

Import Verification System

The import testing system ensures that the core components of the flext-dbt-oracle adapter are accessible and that there are no circular dependencies or broken paths.

Basic Import Integrity

The project validates that the following primary namespaces are always importable:

• flext_dbt_oracle.adapters
• flext_dbt_oracle.connections
• flext_dbt_oracle.models
• flext_dbt_oracle.settings

This validation is critical because it ensures the adapter can be initialized by dbt's discovery mechanism.
Sources: tests/unit/test_imports.py:17-27, tests/unit/test_basic.py:21-26

Lazy Loading Architecture

The project uses flext_core.lazy to manage exports. This allows the package to define a large public surface area without incurring the performance penalty of importing every sub-module immediately.

Component	Responsibility	Source
_LAZY_IMPORTS	Mapping of dotted names to their respective modules and attributes.	src/flext_dbt_oracle/init.py:22
install_lazy_exports	Function that binds lazy loaders to the module's __getattr__ and __dir__.	tests/init.py:117-122
_PUBLIC_EXPORTS	Explicit list of symbols exposed at the package root.	src/flext_dbt_oracle/init.py:36-53

Import Sequence Diagram

The following diagram shows the sequence of a lazy import resolution.

Governance Test Implementation details

Governance is enforced through programmatic inspection in tests/unit/test_module_governance.py.

Logger Enforcement

The system checks every top-level attribute in a module. If an attribute name matches "logger" or "_logger", it is flagged as a violation. This prevents modules from creating unmanaged logging instances that bypass the project's observability configuration.
Sources: tests/unit/test_module_governance.py:68-80

Function Enforcement

The test uses inspect.isfunction(value) to ensure that no logic is leaked into the top-level package scope as a standalone function. This maintains the project's requirement for structured, object-oriented domain models.
Sources: tests/unit/test_module_governance.py:82-92

# Example of governance inspection logic
def _module_top_level_attrs(module: ModuleType) -> Iterator[tuple[str, object]]:
    module_name = module.__name__
    for name, value in vars(module).items():
        if name.startswith("__") and name.endswith("__"):
            continue
        owner = getattr(value, "__module__", None)
        if owner is not None and owner != module_name:
            continue
        yield name, value

Sources: tests/unit/test_module_governance.py:53-63

Conclusion

Module Governance and Imports Testing serve as the primary defensive mechanism against architectural drift in flext-dbt-oracle. By automating the enforcement of structural rules (like the ban on module-level loggers) and verifying import integrity through lazy-loading patterns, the project ensures high reliability and a clean developer experience. These gates ensure that the "Continuous Green" state is maintained across the entire module lifecycle.
Sources: AGENTS.md:57-61, tests/unit/test_module_governance.py:1-5