fix(compiler): require.main is the process entry module only

changelog.d/10749-require-main-entry-only.md

@@ -0,0 +1,32 @@
+Fixed `require.main === module` being trivially `true` in **every** compiled
+CommonJS module, not just the process entry point (#10735).
+`cjs_wrap`'s preamble unconditionally emitted `require.main = module;`, so
+the standard "am I the entry, or merely imported?" idiom took its CLI
+branch in every dependency that used it — including bundled packages
+(dotenv 18.0.1's `dist/index.cjs` is a confirmed real-world example).
+
+The fix threads the compiler's existing entry-module knowledge (the same
+comparison `import.meta.main` uses) through `cjs_wrap`, but that alone is
+insufficient: `cjs_wrap` transpiles a statically-known
+`require('./relative')` into a hoisted ESM import, and ESM import
+evaluation runs a module's static-import dependencies *before* the
+importing module's own top-level code. So a CJS entry's own dependencies
+initialize before the entry's own preamble runs, which means "the entry
+publishes `require.main` in its own preamble" is too late for any
+dependency reached via a hoisted static import. Fixed by publishing a
+placeholder object as the shared "main module" from the program's `main()`
+itself, before any module's `__init` runs at all (gated on the entry being
+CJS-wrapped, so an ESM entry correctly leaves `require.main` `undefined`
+for CJS modules it imports); the entry later reclaims that exact object
+and fills in its real fields, preserving identity for dependencies that
+captured `require.main` before the entry's own code ran.
+
+The new runtime-side cache backing this (`CJS_MAIN_MODULE`) is registered
+with the GC's mutable-root-scanner machinery and verified under forced
+evacuation (`PERRY_GC_SCHEDULE_SEED`/`PERRY_GC_FORCE_EVACUATE`/
+`PERRY_GC_PROTECT_FROMSPACE`): the placeholder moved, the cache followed
+it, and every identity assertion held across 8,006 forced collections. A
+new test (`gc::tests::cjs_main_module`) asserts the rewrite counter is
+non-zero under a real evacuating minor, so a future regression that stops
+rewriting the cache fails a test instead of silently reintroducing this
+bug's failure mode.

crates/perry-codegen/src/codegen/entry.rs

@@ -749,6 +749,14 @@ pub(super) fn compile_module_entry(
                     ],
                 );
             }
+            // #10735: publish the shared `require.main` placeholder before
+            // ANY module's `__init` below runs (those are this CJS entry's
+            // OWN static imports, which ESM eval order runs before the
+            // entry's own preamble). See the callee's doc comment. Skipped
+            // for an ESM entry, which must leave `require.main` `undefined`.
+            if crate::collectors::is_cjs_wrapped_module(hir) {
+                blk.call_void("js_bootstrap_cjs_main_module_placeholder", &[]);
+            }
             for (index, prefix) in non_entry_module_prefixes.iter().enumerate() {
                 if cross_module.deferred_module_prefixes.contains(prefix) {
                     continue;

crates/perry-codegen/src/lower_call/native/native_runtime_branch.rs

@@ -173,6 +173,23 @@
                     .block()
                     .call(DOUBLE, "js_has_path_module", &[(DOUBLE, &path)]));
             }
+            // #10735: publish/read the shared CJS "main module" —
+            // `require.main` for the process entry module vs. for every
+            // other CJS-wrapped module. See `cjs_wrap/wrap.rs` and
+            // `perry-runtime::module_require::{js_set_cjs_main_module,
+            // js_get_cjs_main_module}`.
+            "setCjsMainModule" => {
+                let module = args.first().map_or_else(
+                    || Ok(double_literal(f64::from_bits(crate::nanbox::TAG_UNDEFINED))),
+                    |arg| lower_expr(ctx, arg),
+                )?;
+                ctx.block()
+                    .call_void("js_set_cjs_main_module", &[(DOUBLE, &module)]);
+                return Ok(double_literal(f64::from_bits(crate::nanbox::TAG_UNDEFINED)));
+            }
+            "getCjsMainModule" => {
+                return Ok(ctx.block().call(DOUBLE, "js_get_cjs_main_module", &[]));
+            }
             // #10360: seeded into every module init under `--platform bun`
             // so the runtime can follow Bun where its Web APIs differ from
             // Node's (e.g. the Response null-body-status check).

crates/perry-codegen/src/runtime_decls/objects.rs

@@ -409,6 +409,15 @@ pub fn declare_phase_b_objects(module: &mut LlModule) {
     module.declare_function("js_has_path_module", DOUBLE, &[DOUBLE]);
     // #10360: `--platform bun` marker (see `__perry_runtime.setBunPlatform`).
     module.declare_function("js_set_bun_platform", VOID, &[]);
+    // #10735: shared CJS "main module" (`require.main`) — the entry module
+    // publishes, every other CJS module reads back. See
+    // `__perry_runtime.setCjsMainModule` / `.getCjsMainModule`.
+    module.declare_function("js_set_cjs_main_module", VOID, &[DOUBLE]);
+    module.declare_function("js_get_cjs_main_module", DOUBLE, &[]);
+    // #10735: allocates and publishes the placeholder `require.main` object
+    // BEFORE any module's `__init` runs (called directly from `main()`, not
+    // from generated module JS — see `codegen::entry::compile_module_entry`).
+    module.declare_function("js_bootstrap_cjs_main_module_placeholder", VOID, &[]);
     // Next.js wall 54 (part 2): register a Deferred module's `__init` address by
     // path so a runtime `require(absolutePath)` can trigger its lazy init.
     module.declare_function("js_register_path_init", VOID, &[PTR, I64, I64]);

crates/perry-hir/src/lower/expr_call/globals.rs

@@ -351,6 +351,38 @@ pub(super) fn try_global_builtins(
                     args: vec![path],
                 }));
             }
+            // #10735: `require.main` must be the process ENTRY module only —
+            // equal to `module` there, unequal (or `undefined`, when the
+            // process entry is ESM) everywhere else. The CJS preamble
+            // (`cjs_wrap/wrap.rs`) emits exactly one of these two calls per
+            // module depending on whether IT is the compile-time entry:
+            // the entry publishes its own `module` record as the shared
+            // "main module"; every other CJS module reads it back instead of
+            // assigning its OWN `module` (which is the bug — it made
+            // `require.main === module` trivially true everywhere).
+            "__perry_set_cjs_main_module" => {
+                let module = if !args.is_empty() {
+                    args.remove(0)
+                } else {
+                    Expr::Undefined
+                };
+                return Ok(Ok(Expr::NativeMethodCall {
+                    module: "__perry_runtime".to_string(),
+                    class_name: None,
+                    object: None,
+                    method: "setCjsMainModule".to_string(),
+                    args: vec![module],
+                }));
+            }
+            "__perry_get_cjs_main_module" => {
+                return Ok(Ok(Expr::NativeMethodCall {
+                    module: "__perry_runtime".to_string(),
+                    class_name: None,
+                    object: None,
+                    method: "getCjsMainModule".to_string(),
+                    args: vec![],
+                }));
+            }
             "Symbol" => {
                 // Symbol() / Symbol(description)
                 if args.is_empty() {

crates/perry-runtime/src/gc/mod.rs

@@ -999,6 +999,11 @@ pub fn gc_init() {
     // Runtime path-module exports and cached initialization errors live in a
     // per-heap Rust registry, so moving GC must mark and rewrite them.
     reg_scanner!(crate::module_require::scan_module_path_roots_mut);
+    // #10735: the shared CJS "main module" (`require.main` / Node's
+    // `process.mainModule`) is a raw heap pointer cached in a thread-local
+    // outside any shadow frame — a moving collection must mark and rewrite
+    // it like any other mutable root.
+    reg_scanner!(crate::module_require::scan_cjs_main_module_root_mut);
     reg_budgeted_scanner!(
         promise_mutable_root_scanner,
         crate::promise::scan_promise_roots_mut_step,

crates/perry-runtime/src/gc/tests/cjs_main_module.rs

@@ -0,0 +1,58 @@
+//! #10735 witness: `scan_cjs_main_module_root_mut`'s rewrite counter is a
+//! diagnostic nothing else reads, which is exactly the kind of thing that
+//! rots silently -- a future change that stops rewriting the cache would
+//! report `total_rewrites=0` forever while looking perfectly healthy. This
+//! test forces a REAL evacuating collection (not a passive scan that never
+//! sees a move) and asserts both that the placeholder's address actually
+//! changed and that the counter tracked it, per CLAUDE.md's "a gate must
+//! assert its subject was live" rule.
+//!
+//! Lives here rather than in `module_require.rs` because a real evacuating
+//! minor needs `CopyingNurseryTestGuard`'s preflight setup (generated write
+//! barriers reporting "active", the conservative-full-scan test default
+//! turned off, a clean shadow stack / remembered set) -- machinery private
+//! to this `gc::tests` tree. That guard also clears the thread's mutable
+//! scanner registry so unrelated GC tests see only the roots they install,
+//! which would remove the very scanner under test, so this file
+//! re-registers it explicitly after constructing the guard.
+
+use super::super::*;
+use super::support::CopyingNurseryTestGuard;
+
+#[test]
+fn placeholder_move_under_forced_evacuation_increments_the_rewrite_counter() {
+    let _nursery = CopyingNurseryTestGuard::new(0);
+    let _evac = knob_overrides::ForcedEvacuationTestGuard::on();
+    let _diag = GcDiagTestGuard::force_on();
+    // `CopyingNurseryTestGuard::new` clears the thread's scanner registry so
+    // this collection sees exactly the roots the test installs -- put the
+    // one under test back.
+    gc_register_mutable_root_scanner(crate::module_require::scan_cjs_main_module_root_mut);
+
+    crate::module_require::js_bootstrap_cjs_main_module_placeholder();
+    let before_bits =
+        crate::module_require::test_cjs_main_module_bits().expect("placeholder must be published");
+    let rewrites_before = crate::module_require::test_cjs_main_module_rewrite_count();
+
+    js_gc_collect();
+
+    let after_bits = crate::module_require::test_cjs_main_module_bits()
+        .expect("placeholder must survive the collection");
+    let rewrites_after = crate::module_require::test_cjs_main_module_rewrite_count();
+
+    assert_ne!(
+        before_bits, after_bits,
+        "forced evacuation must have moved the placeholder -- if the \
+         address is unchanged, this test's premise (a real move happened) \
+         is false, and the counter assertion below would be checking \
+         nothing (before={before_bits:#x} after={after_bits:#x})"
+    );
+    assert!(
+        rewrites_after > rewrites_before,
+        "scan_cjs_main_module_root_mut must have counted the rewrite \
+         (before={rewrites_before} after={rewrites_after}); a zero delta \
+         here means the cache stopped following the object it caches -- \
+         the exact regression #10735's identity guarantee depends on never \
+         happening"
+    );
+}

crates/perry-runtime/src/gc/tests/mod.rs

@@ -15,6 +15,7 @@ mod buffer_side_tables;
 mod census;
 mod census_block_windows;
 mod census_whole_block;
+mod cjs_main_module;
 mod concat_site;
 mod contract;
 mod copy_slot_decode;

crates/perry-runtime/src/module_require.rs

@@ -23,6 +23,158 @@ fn undefined() -> f64 {
     f64::from_bits(TAG_UNDEFINED)
 }
 
+crate::perry_thread_local! {
+    /// The process ENTRY module's own CJS `module` record — Node's
+    /// `require.main` / `process.mainModule`. Set exactly once, by the entry
+    /// module's own preamble (see `cjs_wrap::wrap_commonjs_with_body_offset`
+    /// in the compiler), before that module's body runs any `require()` of
+    /// its own — so every dependency it (transitively) requires observes
+    /// this already published. Every OTHER CJS-wrapped module reads it back
+    /// via [`js_get_cjs_main_module`] instead of assigning its own local
+    /// `module`, which is the #10735 bug this replaces (`require.main ===
+    /// module` was trivially true in every compiled CommonJS module, not
+    /// just the real entry point).
+    ///
+    /// Stays `None` (JS `undefined`) for the lifetime of the heap when the
+    /// process entry is ESM — matching Node, where a CJS module reached only
+    /// via `import` from an ESM entry has `require.main === undefined`
+    /// (there is no CommonJS "main" in that process).
+    static CJS_MAIN_MODULE: std::cell::RefCell<Option<u64>> = const { std::cell::RefCell::new(None) };
+}
+
+/// Codegen FFI: publish the process entry module's own CJS `module` record as
+/// the shared "main module". Emitted ONCE, in the entry module's preamble,
+/// before its body runs any `require()` of a dependency — so every later read
+/// on this heap sees it already set. First call wins (idempotent): there
+/// should never be a second, but a re-entrant load must not let a later
+/// module overwrite the true entry.
+#[no_mangle]
+pub extern "C" fn js_set_cjs_main_module(module_value: f64) {
+    CJS_MAIN_MODULE.with(|slot| {
+        let mut slot = slot.borrow_mut();
+        if slot.is_none() {
+            *slot = Some(module_value.to_bits());
+        }
+    });
+}
+
+/// Codegen FFI: `require.main` for a NON-entry CJS module — the value
+/// [`js_set_cjs_main_module`] published, or JS `undefined` if this heap's
+/// process entry never called it (an ESM entry, or a heap whose entry point
+/// was never CommonJS-wrapped).
+#[no_mangle]
+pub extern "C" fn js_get_cjs_main_module() -> f64 {
+    CJS_MAIN_MODULE.with(|slot| slot.borrow().map(f64::from_bits).unwrap_or_else(undefined))
+}
+
+/// Codegen FFI: emitted ONCE, in `main()`, before ANY module's `__init` runs
+/// — including the entry's own, since ESM's static-import evaluation order
+/// runs every hoisted dependency's top-level code before the importing
+/// module's (see `cjs_wrap`'s `require('./x')` -> `import` hoist). Node's
+/// loader sets up `require.main`/`process.mainModule` before invoking the
+/// entry's script body at all, so no CommonJS module - not even one loaded
+/// before the entry's own preamble textually runs - ever observes it unset.
+/// Perry can't replicate that ordering directly (the entry's real `module`
+/// record is built by JS the entry's own preamble emits, which necessarily
+/// runs LAST among a CJS entry's static imports), so this allocates a bare
+/// placeholder object and publishes THAT via [`js_set_cjs_main_module`]
+/// up front. Every non-entry module's `require.main` resolves to this same
+/// object from heap birth. When the entry's own preamble finally runs, it
+/// reclaims this exact object (via [`js_get_cjs_main_module`]) and fills in
+/// its real fields in place — same identity throughout, so a dependency that
+/// captured `require.main` before the entry ran still `===`-matches the
+/// entry's `module` afterward (JS identity survives mutation).
+///
+/// Codegen emits the call only when the entry module is itself CJS-wrapped
+/// (`collectors::is_cjs_wrapped_module`); an ESM entry never calls this, so
+/// [`js_get_cjs_main_module`] stays `undefined` for the lifetime of the heap
+/// — matching Node, where a CJS module reached only via `import` from an ESM
+/// entry has no CommonJS "main" at all.
+#[no_mangle]
+pub extern "C" fn js_bootstrap_cjs_main_module_placeholder() {
+    let placeholder = object_value(js_object_alloc(0, 0));
+    js_set_cjs_main_module(placeholder);
+}
+
+/// GC root scanner for [`CJS_MAIN_MODULE`]: a raw heap pointer cached outside
+/// any shadow frame, so a moving collection must mark and rewrite it like any
+/// other mutable root. Registered in `gc::gc_init` beside
+/// `scan_module_path_roots_mut`.
+pub fn scan_cjs_main_module_root_mut(visitor: &mut crate::gc::RuntimeRootVisitor<'_>) {
+    CJS_MAIN_MODULE.with(|slot| {
+        if let Some(bits) = slot.borrow_mut().as_mut() {
+            let rewritten = visitor.visit_nanbox_u64_slot(bits);
+            // #10735: `visit_nanbox_u64_slot` returns true only when it
+            // actually rewrote the slot (the cached object moved this
+            // cycle). A diagnostic-only counter distinguishing "the
+            // placeholder happened never to move" from "it moved and the
+            // cache followed it" -- the load-bearing question for this
+            // holder's identity guarantee, not visible from the generic
+            // per-cycle counters.
+            if rewritten && crate::gc::gc_diag_enabled() {
+                CJS_MAIN_MODULE_REWRITES.with(|c| c.set(c.get() + 1));
+                eprintln!(
+                    "[cjs-main-module] rewritten: new_bits={:#018x} total_rewrites={}",
+                    *bits,
+                    CJS_MAIN_MODULE_REWRITES.with(std::cell::Cell::get)
+                );
+            }
+        }
+    });
+}
+
+crate::perry_thread_local! {
+    /// Diagnostic-only (`PERRY_GC_DIAG=1`) count of how many times
+    /// [`scan_cjs_main_module_root_mut`] actually rewrote the cached
+    /// placeholder's bits (i.e. the object moved while cached). Never
+    /// read for behaviour.
+    static CJS_MAIN_MODULE_REWRITES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
+}
+
+#[cfg(test)]
+mod cjs_main_module_tests {
+    use super::*;
+
+    // Each `#[test]` fn runs on its own harness-spawned thread, so
+    // `CJS_MAIN_MODULE` (thread-local) starts fresh here regardless of test
+    // execution order — no explicit reset needed.
+
+    #[test]
+    fn defaults_to_undefined_when_no_entry_has_published() {
+        assert_eq!(js_get_cjs_main_module().to_bits(), TAG_UNDEFINED);
+    }
+
+    #[test]
+    fn published_value_reads_back_identically() {
+        let entry_module = string_value("entry-module-marker");
+        js_set_cjs_main_module(entry_module);
+        assert_eq!(js_get_cjs_main_module().to_bits(), entry_module.to_bits());
+    }
+
+    #[test]
+    fn first_publication_wins_a_later_call_cannot_overwrite_it() {
+        let first = string_value("first-entry");
+        let second = string_value("second-entry-should-be-ignored");
+        js_set_cjs_main_module(first);
+        js_set_cjs_main_module(second);
+        assert_eq!(js_get_cjs_main_module().to_bits(), first.to_bits());
+    }
+}
+
+/// Test-only accessors used from `gc::tests::cjs_main_module` (a sibling
+/// module tree that cannot see `cjs_main_module_tests`'s items, and needs
+/// its own file to reach the `CopyingNurseryTestGuard` apparatus a real
+/// forced-evacuation witness test requires -- see that file for why).
+#[cfg(test)]
+pub(crate) fn test_cjs_main_module_bits() -> Option<u64> {
+    CJS_MAIN_MODULE.with(|s| *s.borrow())
+}
+
+#[cfg(test)]
+pub(crate) fn test_cjs_main_module_rewrite_count() -> u64 {
+    CJS_MAIN_MODULE_REWRITES.with(std::cell::Cell::get)
+}
+
 fn null() -> f64 {
     f64::from_bits(TAG_NULL)
 }

crates/perry/src/commands/compile/cjs_wrap/parcel_watcher_tests.rs

@@ -14,6 +14,7 @@ module.exports = binding
         src,
         &PathBuf::from("/tmp/node_modules/opencode/watcher.js"),
         Some("linux-x86_64-musl"),
+        false,
     );
     assert!(
         wrapped.contains("from '@parcel/watcher-linux-x64-musl'")