docs: clarify why external filtering only applies to dynamic imports

Dunqing · claude · Dunqing · commit 786f663f683a · 2026-03-13T08:48:15.000+08:00
User-defined and emitted entries are already guaranteed non-external by
`load_entry_module()` which rejects them with `entry_cannot_be_external`.
Added inline comment and updated design doc to explain this invariant.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/crates/rolldown/src/module_loader/module_loader.rs b/crates/rolldown/src/module_loader/module_loader.rs
@@ -458,6 +458,10 @@ impl<'a, Fs: FileSystem + Clone + 'static> ModuleLoader<'a, Fs> {
             if let Some(usage) = dynamic_import_rec_exports_usage.remove(&rec_idx) {
               dynamic_import_exports_usage_pairs.push((idx, usage));
             }
+            // External modules are excluded here to preserve the bit-position-to-ChunkIdx
+            // invariant in code splitting. User-defined and emitted entries are already
+            // guaranteed non-external by `load_entry_module()` which rejects them with
+            // `entry_cannot_be_external`.
             if matches!(raw_rec.kind, ImportKind::DynamicImport)
               && !is_external
               && !user_defined_entry_ids.contains(&idx)
diff --git a/meta/design/code-splitting.md b/meta/design/code-splitting.md
@@ -76,7 +76,7 @@ entry_index 2  →  plugin.js       →  bit 2  →  ChunkIdx(2)
 
 Dynamic imports are treated as entry points — they get bit positions and entry chunks just like static entries. This matches Rollup and esbuild behavior: a dynamic `import()` creates a new loading boundary, so the imported module needs its own chunk (or must be merged into an existing one).
 
-External modules are filtered out at the source — they never appear in `link_output.entries`. This is done in `module_loader.rs` where dynamic imports are collected as entry points: external modules are excluded from `dynamic_import_entry_ids`. This matches esbuild's approach where external modules never enter the entry list, and ensures that **bit positions directly equal chunk indices** — `ChunkIdx::from_raw(bit_position)` is always valid.
+External modules are filtered out at the source — they never appear in `link_output.entries`. This is done in `module_loader.rs` where dynamic imports are collected as entry points: external modules are excluded from `dynamic_import_entry_ids`. User-defined and emitted entries are also safe because `load_entry_module()` rejects external resolutions with `entry_cannot_be_external`. This matches esbuild's approach where external modules never enter the entry list, and ensures that **bit positions directly equal chunk indices** — `ChunkIdx::from_raw(bit_position)` is always valid.
 
 See #8595 for the bug that motivated this filtering.
 
