feat(di): enforce NestJS-style module encapsulation at build time

Previously every provider from every module landed in one flat injector
pool — a service in module A could inject a service from module B even
when A never imported B and B never exported the service. Encapsulation
was a documentation-only contract, not a check.

Now PyNestContainer.build() runs a validation pass after cycle detection:

- Each module gets a 'visible' set:
    own providers + own controllers
    + transitively-resolved exports of its imports (re-exports supported)
    + every provider from any @module(is_global=True)
- Every consumer's __init__ annotations are walked; class-typed deps that
  are registered providers but not in the consumer's visible set raise
  ProviderNotExportedException listing every violation with a concrete
  fix ('add imports=[X] to A and exports=[Y] to X, or move Y into A').

Updated test_imported_module_providers_are_resolvable to declare the
export it was implicitly relying on. Added 8 new tests covering:
same-module deps, proper import+export, global modules, module re-exports,
missing import, missing export, controller violations, and unrelated
sibling modules.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ItayTheDar

nest/common/exceptions.py

@@ -24,6 +24,14 @@ def __init__(self, message: str = "Non-injectable class detected"):
         super().__init__(message)
 
 
+class ProviderNotExportedException(Exception):
+    """Raised when a class depends on a provider that lives in another module
+    which either isn't imported, or doesn't export that provider."""
+
+    def __init__(self, message: str = "Provider not visible across module boundary"):
+        super().__init__(message)
+
+
 class HttpException(Exception):
     def __init__(self, message: str = "Internal Server Error", status_code: int = 500):
         self.message = message

nest/core/encapsulation.py

@@ -0,0 +1,150 @@
+"""NestJS-style module encapsulation validation.
+
+Enforces that a class can only inject providers visible to its owning module:
+its own providers, providers exported by imported modules (transitively through
+re-exports), and providers from globally-scoped modules.
+"""
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any, Dict, List, Set
+
+from nest.common.exceptions import ProviderNotExportedException
+
+if TYPE_CHECKING:
+    from nest.core.pynest_container import ModuleRef
+
+
+_PRIMITIVE_TYPES = {
+    int, str, float, bool, bytes, bytearray, complex,
+    list, dict, tuple, set, frozenset, type(None),
+}
+
+
+def validate_module_encapsulation(modules: Dict[str, "ModuleRef"]) -> None:
+    """Validate that every cross-module dependency goes through proper imports/exports.
+
+    Raises ProviderNotExportedException listing every violation with a suggested fix.
+    """
+    if not modules:
+        return
+
+    # Map every provider token (and controller class) to the module that owns it.
+    provider_owner: Dict[Any, "ModuleRef"] = {}
+    for mref in modules.values():
+        for desc in mref.compiled.provider_descriptors:
+            provider_owner[desc.provide] = mref
+        for ctrl in mref.compiled.controllers:
+            provider_owner[ctrl] = mref
+
+    # Class → its ModuleRef (so we can look up imported modules by their metatype).
+    metatype_to_ref: Dict[type, "ModuleRef"] = {
+        mref.metatype: mref for mref in modules.values()
+    }
+
+    def resolved_exports(mref: "ModuleRef", _seen: Set[str] = None) -> Set[Any]:
+        """Return the set of provider tokens that `mref` exposes to importers,
+        following module re-exports recursively."""
+        if _seen is None:
+            _seen = set()
+        if mref.token in _seen:
+            return set()
+        _seen = _seen | {mref.token}
+        result: Set[Any] = set()
+        for exp in mref.compiled.exports:
+            # If the export is a Module class, re-export everything it exports.
+            if isinstance(exp, type) and getattr(exp, "__is_module__", False):
+                child = metatype_to_ref.get(exp)
+                if child is not None:
+                    result |= resolved_exports(child, _seen)
+            else:
+                result.add(exp)
+        return result
+
+    # Anything provided by an @Module(is_global=True) module is visible everywhere.
+    global_providers: Set[Any] = set()
+    for mref in modules.values():
+        if getattr(mref.metatype, "__is_global__", False):
+            for desc in mref.compiled.provider_descriptors:
+                global_providers.add(desc.provide)
+
+    # Per-module visibility set: own providers + imported exports + globals.
+    visible: Dict[str, Set[Any]] = {}
+    for mref in modules.values():
+        s: Set[Any] = set()
+        for desc in mref.compiled.provider_descriptors:
+            s.add(desc.provide)
+        for ctrl in mref.compiled.controllers:
+            s.add(ctrl)
+        for imp in mref.compiled.imports:
+            child = metatype_to_ref.get(imp)
+            if child is not None:
+                s |= resolved_exports(child)
+        s |= global_providers
+        visible[mref.token] = s
+
+    # Walk every consumer's __init__ signature and check each annotated dependency.
+    errors: List[str] = []
+    for mref in modules.values():
+        consumers: List[type] = list(mref.compiled.controllers)
+        for desc in mref.compiled.provider_descriptors:
+            if desc.use_class is not None:
+                consumers.append(desc.use_class)
+
+        for consumer_cls in consumers:
+            try:
+                sig = inspect.signature(consumer_cls.__init__)
+            except (ValueError, TypeError):
+                continue
+
+            for param_name, param in sig.parameters.items():
+                if param_name == "self":
+                    continue
+                ann = param.annotation
+                if ann is inspect.Parameter.empty:
+                    continue
+
+                # Resolve string forward refs against known providers (best effort).
+                if isinstance(ann, str):
+                    matches = [
+                        p for p in provider_owner
+                        if isinstance(p, type) and p.__name__ == ann
+                    ]
+                    if len(matches) != 1:
+                        continue
+                    ann = matches[0]
+
+                if ann in _PRIMITIVE_TYPES:
+                    continue
+
+                # Only check tokens that are actually registered somewhere — unknown
+                # types are someone else's problem (FastAPI body params, externals, etc).
+                if ann not in provider_owner:
+                    continue
+
+                if ann not in visible[mref.token]:
+                    owner = provider_owner[ann]
+                    errors.append(_format_violation(consumer_cls, mref, ann, owner))
+
+    if errors:
+        raise ProviderNotExportedException(
+            "Module encapsulation violation(s) detected:\n\n"
+            + "\n\n".join(errors)
+        )
+
+
+def _format_violation(consumer_cls: type, consumer_module, dep, owner_module) -> str:
+    consumer_name = consumer_cls.__name__
+    consumer_mod = consumer_module.metatype.__name__
+    dep_name = getattr(dep, "__name__", str(dep))
+    owner_mod = owner_module.metatype.__name__
+    return (
+        f"  ✗ {consumer_name} (in module {consumer_mod}) depends on {dep_name},\n"
+        f"    but {dep_name} is provided by {owner_mod}.\n"
+        f"\n"
+        f"    To fix, do BOTH:\n"
+        f"      1. add 'imports=[{owner_mod}]'   to {consumer_mod}\n"
+        f"      2. add 'exports=[{dep_name}]'   to {owner_mod}\n"
+        f"\n"
+        f"    Or move {dep_name} into {consumer_mod} if it doesn't belong in {owner_mod}."
+    )

nest/core/pynest_container.py

@@ -8,6 +8,7 @@
 from nest.common.module import CompiledModule, ModuleCompiler, ModuleTokenFactory
 from nest.common.provider import InjectionToken, ProviderDescriptor
 from nest.core.dependency_graph import DependencyGraph
+from nest.core.encapsulation import validate_module_encapsulation
 from nest.core.injector_module import build_injector, _to_key
 
 
@@ -79,6 +80,7 @@ def build(self) -> None:
         Must be called once after all add_module() calls, before any get() calls.
         """
         self._validate_dependency_graph()
+        validate_module_encapsulation(self._modules)
 
         # Controller classes need singleton bindings too so the injector can resolve them
         all_descriptors = self._all_descriptors + self._make_controller_descriptors()