feat: opt-in bundling of pure-Python third-party dependencies

.gitignore

@@ -35,7 +35,11 @@ __pycache__/
 build/
 dist/
 *.egg-info/
+# Test fixtures simulate legacy installs and must keep their egg-info metadata
+!crates/cribo/tests/fixtures/**/*.egg-info/
 *.so
+# Test fixtures simulate native-extension installs with fake .so artifacts
+!crates/cribo/tests/fixtures/**/*.so
 +*.whl
 +venv/
 +.venv/

crates/cribo/src/analyzers/module_classifier.rs

@@ -206,7 +206,28 @@ impl<'a> ModuleClassifier<'a> {
             let has_invalid_identifier =
                 !ruff_python_stdlib::identifiers::is_identifier(module_base_name);
 
-            if has_side_effects || has_invalid_identifier || needs_wrapping_for_circular {
+            // Modules inspecting sys.modules (e.g. `sys.modules[__name__]`, even
+            // inside function bodies) need a real module object registered under
+            // their original name: the wrapper approach provides one and its init
+            // registers it in sys.modules. Targets of preserved import_module calls
+            // need the same registration so the runtime call resolves them, and so
+            // do modules whose sys.modules entry a CONSUMER observes
+            // (`sys.modules[dep.__name__]`). ANCESTOR packages of preserved dotted
+            // targets are imported by the machinery too (parents load before
+            // children), so they need a real init for reload/eviction semantics.
+            let accesses_own_sys_modules =
+                crate::visitors::utils::accesses_own_sys_modules_entry(&ast.body)
+                    || self.resolver.is_preserved_importlib_target(&module_name)
+                    || self
+                        .resolver
+                        .is_preserved_importlib_target_ancestor(&module_name)
+                    || self.resolver.is_sys_modules_observed_target(&module_name);
+
+            if has_side_effects
+                || has_invalid_identifier
+                || needs_wrapping_for_circular
+                || accesses_own_sys_modules
+            {
                 if has_invalid_identifier {
                     debug!(
                         "Module '{module_name}' has invalid Python identifier - using wrapper \
@@ -216,8 +237,13 @@ impl<'a> ModuleClassifier<'a> {
                     debug!(
                         "Module '{module_name}' is in circular dependency - using wrapper approach"
                     );
-                } else {
+                } else if has_side_effects {
                     debug!("Module '{module_name}' has side effects - using wrapper approach");
+                } else {
+                    debug!(
+                        "Module '{module_name}' inspects sys.modules - using wrapper approach so \
+                         it is registered under its original name"
+                    );
                 }
 
                 wrapper_modules.push((

crates/cribo/src/ast_builder/expressions.rs

@@ -408,6 +408,72 @@ pub(crate) fn bool_op(op: BoolOp, values: Vec<Expr>) -> Expr {
     })
 }
 
+/// Creates the runtime identity guard for stamping a DECORATED definition:
+///
+/// ```python
+/// getattr(<binding>, '__name__', None) == '<expected_name>' and
+///     getattr(<binding>, '__module__', None) == (lambda: None).__module__
+/// ```
+///
+/// A decorator may return an unrelated object — in particular an IMPORTED
+/// shared callable whose `__name__` happens to equal the decorated binding.
+/// Such an object must keep its defining module's attribution, so the guard
+/// requires BOTH the definition's `__name__` AND creation provenance: a
+/// locally created result (the original `def`, or a `functools.wraps`-style
+/// copy of it) carries the creating scope's module name, which the inline
+/// lambda probe reproduces exactly (both draw it from the enclosing
+/// `globals()['__name__']` at execution time), while an imported callable
+/// carries its own module's name (bundled modules stamp it right after the
+/// definition, before any importer can observe the object).
+pub(crate) fn decorated_identity_guard(binding: &str, expected_name: &str) -> Expr {
+    use ruff_python_ast::ExprLambda;
+
+    let name_check = compare(
+        call(
+            name("getattr", ExprContext::Load),
+            vec![
+                name(binding, ExprContext::Load),
+                string_literal("__name__"),
+                none_literal(),
+            ],
+            vec![],
+        ),
+        CmpOp::Eq,
+        string_literal(expected_name),
+    );
+    let probe = Expr::Lambda(ExprLambda {
+        node_index: AtomicNodeIndex::NONE,
+        range: TextRange::default(),
+        parameters: None,
+        body: Box::new(none_literal()),
+    });
+    let provenance_check = compare(
+        call(
+            name("getattr", ExprContext::Load),
+            vec![
+                name(binding, ExprContext::Load),
+                string_literal("__module__"),
+                none_literal(),
+            ],
+            vec![],
+        ),
+        CmpOp::Eq,
+        attribute(probe, "__module__", ExprContext::Load),
+    );
+    bool_op(BoolOp::And, vec![name_check, provenance_check])
+}
+
+/// Creates a comparison expression node with a single operator.
+fn compare(left: Expr, op: CmpOp, right: Expr) -> Expr {
+    Expr::Compare(ExprCompare {
+        node_index: AtomicNodeIndex::NONE,
+        range: TextRange::default(),
+        left: Box::new(left),
+        ops: Box::new([op]),
+        comparators: Box::new([right]),
+    })
+}
+
 /// Creates an if-expression (ternary conditional) node.
 ///
 /// # Arguments

crates/cribo/src/ast_builder/mod.rs

@@ -54,10 +54,13 @@ pub(crate) mod expressions;
 pub(crate) mod module_attr_merge;
 pub(crate) mod module_wrapper;
 pub(crate) mod other;
+pub(crate) mod preserved_finder;
 pub(crate) mod proxy_generator;
 pub(crate) mod statements;
 
 /// Internal namespace prefix used for hoisted stdlib access.
 pub(crate) const CRIBO_PREFIX: &str = "_cribo";
+/// Alias under which the proxy prelude imports `sys` (`import sys as _sys`).
+pub(crate) const CRIBO_SYS_ALIAS: &str = "_sys";
 
 // Re-export commonly used functions for convenience

crates/cribo/src/ast_builder/module_wrapper.rs

@@ -1,4 +1,4 @@
-use ruff_python_ast::{ExprContext, Stmt};
+use ruff_python_ast::{Expr, ExprContext, Stmt};
 
 use crate::{
     ast_builder::{expressions, statements},
@@ -72,6 +72,22 @@ pub(crate) fn create_wrapper_module(
     );
     stmts.push(namespace_stmt);
 
+    // 1b. Capture the namespace OBJECT in the meta-path finder: runtime imports
+    // must resolve it even when user code later rebinds the bundle-global name
+    // (`globals()["helper"] = sentinel` before a preserved import)
+    stmts.push(statements::expr(expressions::call(
+        expressions::attribute(
+            expressions::name("_cribo_finder", ExprContext::Load),
+            "bind",
+            ExprContext::Load,
+        ),
+        vec![
+            expressions::string_literal(module_name),
+            expressions::name(&module_var, ExprContext::Load),
+        ],
+        vec![],
+    )));
+
     // 2. Add the init function definition and __init__ assignment if provided
     if let Some(init_body) = init_function_body {
         let init_stmts = create_init_function_statements(module_name, init_func_name, init_body);
@@ -108,3 +124,95 @@ pub(crate) fn create_wrapper_module_init_call(module_name: &str) -> Stmt {
         ),
     )
 }
+
+/// Wrap a bundled-module access expression with a `sys.modules` consult:
+///
+/// ```python
+/// _cribo.importlib.import_module("pkg.sub") \
+///     if "pkg" in _cribo.sys.modules or "pkg.sub" in _cribo.sys.modules \
+///     else <access>
+/// ```
+///
+/// CPython's `_find_and_load` returns an existing `sys.modules` entry before
+/// invoking any finder or loader, and resolves DOTTED names through the
+/// parent's `__path__` — so a preloaded replacement of the target OR of any
+/// ancestor package must route through the real machinery rather than the
+/// bundled access. When no component is preloaded, the direct bundled access
+/// is used. The conditional (rather than `or`) also honors falsy replacement
+/// objects.
+pub(crate) fn sys_modules_consult_or(module_name: &str, access: Expr) -> Expr {
+    use ruff_python_ast::BoolOp;
+
+    let cribo_attribute = |attribute: &str| {
+        expressions::attribute(
+            expressions::name(super::CRIBO_PREFIX, ExprContext::Load),
+            attribute,
+            ExprContext::Load,
+        )
+    };
+    let sys_modules =
+        || expressions::attribute(cribo_attribute("sys"), "modules", ExprContext::Load);
+
+    // "pkg" in _cribo.sys.modules or "pkg.mid" in ... or "pkg.mid.sub" in ...
+    let mut component_tests = Vec::new();
+    let mut boundary = 0_usize;
+    loop {
+        match module_name[boundary..].find('.') {
+            Some(offset) => boundary += offset,
+            None => boundary = module_name.len(),
+        }
+        component_tests.push(expressions::in_op(
+            expressions::string_literal(&module_name[..boundary]),
+            sys_modules(),
+        ));
+        if boundary == module_name.len() {
+            break;
+        }
+        boundary += 1;
+    }
+    let any_component_preloaded = if component_tests.len() == 1 {
+        component_tests
+            .pop()
+            .expect("one component test must exist")
+    } else {
+        expressions::bool_op(BoolOp::Or, component_tests)
+    };
+
+    expressions::if_exp(
+        any_component_preloaded,
+        expressions::call(
+            expressions::attribute(
+                cribo_attribute("importlib"),
+                "import_module",
+                ExprContext::Load,
+            ),
+            vec![expressions::string_literal(module_name)],
+            vec![],
+        ),
+        access,
+    )
+}
+
+/// Creates a wrapper module initialization call that honors preloaded
+/// `sys.modules` entries, for modules whose entries consumer code observably
+/// manipulates:
+///
+/// `module = <consult> else module.__init__(module)`
+pub(crate) fn create_wrapper_module_init_call_honoring_sys_modules(
+    module_var: &str,
+    original_module_name: &str,
+) -> Stmt {
+    let init_call = expressions::call(
+        expressions::attribute(
+            expressions::name(module_var, ExprContext::Load),
+            MODULE_INIT_ATTR,
+            ExprContext::Load,
+        ),
+        vec![expressions::name(module_var, ExprContext::Load)],
+        vec![],
+    );
+    statements::assign(
+        vec![expressions::name(module_var, ExprContext::Store)],
+        sys_modules_consult_or(original_module_name, init_call),
+    )
+}