Module Governance Tests

Relevant source files

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

• tests/unit/test_module_governance.py
• tests/constants.py
• AGENTS.md
• README.md
• pyproject.toml
• tests/init.py

Module Governance Tests serve as automated structural quality gates within the flext-target-oracle-oic repository. Their primary purpose is to enforce strict architectural standards, ensuring that the codebase remains modular, predictable, and free from common anti-patterns such as module-level global loggers or unauthorized top-level functions. These tests are part of the broader Quality Gates described in the project documentation.

The governance framework operates by dynamically introspecting the package structure and inspecting the attributes of imported modules against a defined set of "approved" configurations. This ensures that every module adhering to the FLEXT ecosystem standards maintains a consistent behavioral contract.

Sources: tests/unit/test_module_governance.py:1-10, README.md:38-40

Governance Architecture

The governance testing system relies on a combination of path discovery and dynamic module inspection. It targets the src/flext_target_oracle_oic directory to validate all internal components of the package.

Component Interaction

The following diagram illustrates the flow from file discovery to final assertion in the governance test suite:

This flow ensures that no module is bypassed during the quality check.
Sources: tests/unit/test_module_governance.py:15-84

Core Discovery Logic

The system utilizes several internal helper functions to resolve package paths and map file system structures to Python dotted-module names:

Function	Purpose
_package_root()	Resolves the absolute path to the src/flext_target_oracle_oic directory using project constants.
_iter_package_modules()	Performs a recursive glob search for all .py files within the package root.
_module_dotted_name()	Converts a file path into a standard Python import string (e.g., flext_target_oracle_oic.utilities).
_import_package_module()	Dynamically imports modules using importlib for runtime inspection.
_module_top_level_attrs()	Filters module attributes to identify only those owned by the module (excluding dunders and imports).

Sources: tests/unit/test_module_governance.py:15-50

Structural Enforcement Rules

The governance suite currently enforces two critical architectural constraints: the prohibition of module-level loggers and the restriction of top-level functions.

Module-Level Logger Restriction

The test test_package_modules_do_not_define_module_level_loggers ensures that no module defines a global logger or _logger at the top level. This aligns with FLEXT engineering principles which favor dependency injection or standardized observability over hidden globals.

def test_package_modules_do_not_define_module_level_loggers(self) -> None:
    violations: list[str] = []
    for module_path in _iter_package_modules():
        module = _import_package_module(module_path)
        if module is None:
            continue
        for name, _ in _module_top_level_attrs(module):
            if name in {"logger", "_logger"}:
                violations.append(str(module_path.relative_to(_package_root().parent)))
                break
    assert not violations, f"Module-level logger assignments are forbidden: {violations}"

Sources: tests/unit/test_module_governance.py:56-70, AGENTS.md:96-100

Function Approved-List

The test_package_modules_do_not_define_unapproved_top_level_functions test prevents the proliferation of top-level functions unless they are explicitly registered in the project's test constants. This forces developers to use classes or approved entrypoints for logic organization.

Approved Module	Allowed Functions
cli.py	main
All Others	None (unless specified in ALLOWED_MODULE_FUNCTIONS)

Sources: tests/unit/test_module_governance.py:72-88, tests/constants.py:28-30

Integration with Universal Engineering Principles

These tests directly implement the Universal Agent Law and Universal Engineering Principles defined in the project:

• SSOT (Single Source of Truth): The package structure is the only source used for discovery, avoiding separate manifest files.
• DI / DIP (Dependency Inversion): By forbidding module-level loggers and globals, the system mandates that collaborators must be injected, facilitating better testability.
• Zero-Tolerance: The tests are configured as hard gates; any violation results in a loud failure during the make test or make check cycles.

Sources: AGENTS.md:21-25, AGENTS.md:92-100, README.md:38-40

Conclusion

Module Governance Tests are essential for maintaining the "enterprise-grade" structural integrity of the flext-target-oracle-oic project. By automating the detection of globals and unapproved function patterns, they ensure the code remains compliant with the project's strict engineering laws without requiring manual review for these specific anti-patterns.

Sources: tests/unit/test_module_governance.py:1-5, AGENTS.md:12-16