feat: emit ECMA-426 source map scopes behind experimental flag (#11582)

## Summary

Implements ECMA-426 source map scope emission behind a new opt-in flag:

- Adds `jsc.experimental.emitSourceMapScopes` (default `false`)
- Emits `scopes` metadata in output source maps when enabled
- Includes both original scope trees and generated range trees
- Includes variable lists and generated range bindings (`G`)
- Keeps behavior unchanged unless explicitly enabled

## What changed

### Config and API wiring

- Added `emit_source_map_scopes` to SWC config/build pipeline
- Added `emit_source_map_scopes` to compiler-base `PrintArgs`
- Added `emitSourceMapScopes?: boolean` to `packages/types`

### Codegen scope collection

- Extended `WriteJs` with scope hooks:
  - `start_scope`
  - `end_scope`
  - `add_scope_variable`
- Added forwarding in wrappers (`Box<W>`, `&mut W`, omit-trailing-semi
writer)
- Added scope model (`ScopeKind`, `BindingStorage`, `ScopeRecord`,
`ScopeBindingRecord`)
- Implemented collection in `JsWriter` with:
  - nested scope stack tracking
  - hoisted vs lexical placement
  - per-scope variable dedup by name

### Emitter instrumentation

- Instrumented module/script roots, function-like scopes, block scopes,
and catch scopes
- Collected bindings for params, var/let/const declarations,
function/class declarations
- Added helper module for pattern/parameter binding extraction

### Source map integration

- Added `SourceMapGenConfig::for_each_additional_name` hook
- Pre-registers additional scope-related names before mappings are
encoded
- Added scope encoder in compiler-base (`source_map_scopes.rs`) to
encode ECMA-426 tags (`B/C/D/E/F/G`)
- `scopes` is only emitted when:
  - source maps are enabled
  - `emitSourceMapScopes` is enabled
  - no input sourcemap composition (`orig.is_none()`)

## Tests

Added/updated tests for:

- codegen writer scope collection and wrapper forwarding
- compiler-base scope encoder behavior
- compiler-base print integration (enabled/disabled/orig composition)
- swc e2e source-map test for this issue
(`issue_11424_emit_source_map_scopes_opt_in`)

## Verification run

- `git submodule update --init --recursive`
- `cargo fmt --all`
- `cargo clippy --all --all-targets -- -D warnings`
- `cargo test -p swc_ecma_codegen`
- `cargo test -p swc_compiler_base`
- `cargo test -p swc_sourcemap`
- `cargo test -p swc`

Note: `cargo test -p swc` still has pre-existing environment-dependent
failures in `tests/source_map.rs` where Node cannot resolve
`sourcemap-validator` in this environment. The new
`issue_11424_emit_source_map_scopes_opt_in` test passes.

Fixes #11424

Author: kdy1

.changeset/big-owls-remember.md

@@ -0,0 +1,5 @@
+---
+swc_sourcemap: major
+---
+
+feat: emit ECMA-426 source map scopes behind experimental flag

crates/swc/src/config/mod.rs

@@ -976,6 +976,7 @@ impl Options {
             emit_assert_for_import_attributes: experimental
                 .emit_assert_for_import_attributes
                 .into_bool(),
+            emit_source_map_scopes: experimental.emit_source_map_scopes.into_bool(),
             codegen_inline_script,
             emit_isolated_dts: experimental.emit_isolated_dts.into_bool(),
             unresolved_mark,
@@ -1295,6 +1296,7 @@ pub struct BuiltInput<P: Pass> {
 
     pub output: JscOutputConfig,
     pub emit_assert_for_import_attributes: bool,
+    pub emit_source_map_scopes: bool,
     pub codegen_inline_script: bool,
 
     pub emit_isolated_dts: bool,
@@ -1331,6 +1333,7 @@ where
             emit_source_map_columns: self.emit_source_map_columns,
             output: self.output,
             emit_assert_for_import_attributes: self.emit_assert_for_import_attributes,
+            emit_source_map_scopes: self.emit_source_map_scopes,
             codegen_inline_script: self.codegen_inline_script,
             emit_isolated_dts: self.emit_isolated_dts,
             unresolved_mark: self.unresolved_mark,
@@ -1433,6 +1436,9 @@ pub struct JscExperimental {
 
     #[serde(default)]
     pub emit_assert_for_import_attributes: BoolConfig<false>,
+
+    #[serde(default)]
+    pub emit_source_map_scopes: BoolConfig<false>,
     /// Location where swc may stores its intermediate cache.
     /// Currently this is only being used for wasm plugin's bytecache.
     /// Path should be absolute directory, which will be created if not exist.

crates/swc/src/lib.rs

@@ -925,6 +925,7 @@ impl Compiler {
                     orig,
                     comments: Some(&comments),
                     emit_source_map_columns: opts.emit_source_map_columns,
+                    emit_source_map_scopes: false,
                     preamble: &opts.format.preamble,
                     codegen_config: swc_ecma_codegen::Config::default()
                         .with_target(target)
@@ -1083,6 +1084,7 @@ impl Compiler {
                     orig,
                     comments: config.comments.as_ref().map(|v| v as _),
                     emit_source_map_columns: config.emit_source_map_columns,
+                    emit_source_map_scopes: config.emit_source_map_scopes,
                     preamble: &config.output.preamble,
                     codegen_config: swc_ecma_codegen::Config::default()
                         .with_target(config.target)

crates/swc/tests/source_map.rs

@@ -12,7 +12,8 @@ use std::{
 use anyhow::{Context, Error};
 use swc::{
     config::{
-        Config, InputSourceMap, IsModule, JscConfig, ModuleConfig, Options, SourceMapsConfig,
+        Config, InputSourceMap, IsModule, JscConfig, JscExperimental, ModuleConfig, Options,
+        SourceMapsConfig,
     },
     Compiler,
 };
@@ -441,6 +442,83 @@ fn should_work_with_emit_source_map_columns() {
     });
 }
 
+#[test]
+fn issue_11424_emit_source_map_scopes_opt_in() {
+    Tester::new().print_errors(|cm, handler| {
+        let c = Compiler::new(cm.clone());
+        let path = canonicalize("tests/srcmap/issue-11424-scopes/input.js")
+            .expect("failed to canonicalize fixture");
+        let fm = cm.load_file(&path).expect("failed to load fixture");
+
+        let output = c
+            .process_js_file(
+                fm,
+                &handler,
+                &Options {
+                    swcrc: false,
+                    source_maps: Some(SourceMapsConfig::Bool(true)),
+                    config: Config {
+                        inline_sources_content: true.into(),
+                        jsc: JscConfig {
+                            experimental: JscExperimental {
+                                emit_source_map_scopes: true.into(),
+                                ..Default::default()
+                            },
+                            ..Default::default()
+                        },
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                },
+            )
+            .expect("failed to process fixture");
+
+        let map_text = output.map.expect("source map should be emitted");
+        let map = swc_sourcemap::SourceMap::from_slice(map_text.as_bytes())
+            .expect("failed to deserialize sourcemap");
+        let scopes = map.get_scopes().expect("scopes should be emitted");
+        assert!(!scopes.is_empty());
+        assert!(scopes.contains('B'));
+        assert!(scopes.contains('E'));
+        assert!(scopes.contains('G'));
+
+        Ok(())
+    });
+}
+
+#[test]
+fn issue_11424_emit_source_map_scopes_default_off() {
+    Tester::new().print_errors(|cm, handler| {
+        let c = Compiler::new(cm.clone());
+        let path = canonicalize("tests/srcmap/issue-11424-scopes/input.js")
+            .expect("failed to canonicalize fixture");
+        let fm = cm.load_file(&path).expect("failed to load fixture");
+
+        let output = c
+            .process_js_file(
+                fm,
+                &handler,
+                &Options {
+                    swcrc: false,
+                    source_maps: Some(SourceMapsConfig::Bool(true)),
+                    config: Config {
+                        inline_sources_content: true.into(),
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                },
+            )
+            .expect("failed to process fixture");
+
+        let map_text = output.map.expect("source map should be emitted");
+        let map = swc_sourcemap::SourceMap::from_slice(map_text.as_bytes())
+            .expect("failed to deserialize sourcemap");
+        assert!(map.get_scopes().is_none());
+
+        Ok(())
+    });
+}
+
 #[test]
 fn issue_4578() {
     file(

crates/swc/tests/srcmap/issue-11424-scopes/input.js

@@ -0,0 +1,17 @@
+export function outer(param) {
+    var hoisted = param;
+    let lexical = hoisted + 1;
+
+    function inner(innerParam) {
+        const nested = innerParam + lexical;
+
+        if (nested > 0) {
+            let blockVar = nested;
+            return blockVar;
+        }
+
+        return hoisted;
+    }
+
+    return inner(lexical);
+}

crates/swc_common/src/source_map.rs

@@ -1293,6 +1293,14 @@ pub fn build_source_map(
     config: &impl SourceMapGenConfig,
 ) -> swc_sourcemap::SourceMap {
     let mut builder = SourceMapBuilder::new(None);
+    if orig.is_none() {
+        config.for_each_additional_name(&mut |name| {
+            builder.add_name(unsafe {
+                // Safety: `name` is `&str`, so it's valid UTF-8.
+                BytesStr::from_utf8_slice_unchecked(name.as_bytes())
+            });
+        });
+    }
 
     let mut src_id = 0u32;
 
@@ -1507,6 +1515,11 @@ pub trait SourceMapGenConfig {
         None
     }
 
+    /// Iterates over additional names that should be inserted into
+    /// `SourceMap.names` even if they are not directly referenced by mapping
+    /// tokens.
+    fn for_each_additional_name(&self, _op: &mut dyn FnMut(&str)) {}
+
     /// You can override this to control `sourceContents`.
     fn inline_sources_content(&self, f: &FileName) -> bool {
         !matches!(

crates/swc_compiler_base/src/lib.rs

@@ -20,7 +20,10 @@ use swc_common::{
 };
 use swc_config::{file_pattern::FilePattern, is_module::IsModule, types::BoolOr};
 use swc_ecma_ast::{EsVersion, Ident, IdentName, Program};
-use swc_ecma_codegen::{text_writer::WriteJs, Emitter, Node};
+use swc_ecma_codegen::{
+    text_writer::{ScopeRecord, WriteJs},
+    Emitter, Node,
+};
 use swc_ecma_minifier::js::JsMinifyCommentOption;
 use swc_ecma_parser::{
     parse_file_as_commonjs, parse_file_as_module, parse_file_as_program, parse_file_as_script,
@@ -29,6 +32,8 @@ use swc_ecma_parser::{
 use swc_ecma_visit::{noop_visit_type, Visit, VisitWith};
 use swc_timer::timer;
 
+mod source_map_scopes;
+
 #[cfg(feature = "node")]
 #[napi_derive::napi(object)]
 #[derive(Debug, Serialize)]
@@ -123,6 +128,7 @@ pub struct PrintArgs<'a> {
     pub orig: Option<swc_sourcemap::SourceMap>,
     pub comments: Option<&'a dyn Comments>,
     pub emit_source_map_columns: bool,
+    pub emit_source_map_scopes: bool,
     pub preamble: &'a str,
     pub codegen_config: swc_ecma_codegen::Config,
     pub output: Option<FxHashMap<String, String>>,
@@ -144,6 +150,7 @@ impl Default for PrintArgs<'_> {
             orig: None,
             comments: None,
             emit_source_map_columns: false,
+            emit_source_map_scopes: false,
             preamble: "",
             codegen_config: Default::default(),
             output: None,
@@ -176,6 +183,7 @@ pub fn print<T>(
         orig,
         comments,
         emit_source_map_columns,
+        emit_source_map_scopes,
         preamble,
         codegen_config,
         output,
@@ -189,11 +197,13 @@ where
     let _timer = timer!("Compiler::print");
 
     let mut src_map_buf = Vec::new();
+    let should_emit_scope_map = source_map.enabled() && emit_source_map_scopes && orig.is_none();
+    let mut scope_buf = should_emit_scope_map.then(Vec::<ScopeRecord>::new);
 
     let mut src = {
         let mut buf = std::vec::Vec::new();
         {
-            let mut w = swc_ecma_codegen::text_writer::JsWriter::new(
+            let mut w = swc_ecma_codegen::text_writer::JsWriter::new_with_scopes(
                 cm.clone(),
                 "\n",
                 &mut buf,
@@ -202,6 +212,7 @@ where
                 } else {
                     None
                 },
+                scope_buf.as_mut(),
             );
             w.preamble(preamble).unwrap();
             let mut wr = Box::new(w) as Box<dyn WriteJs>;
@@ -233,6 +244,11 @@ where
         panic!("The module contains only dummy spans\n{src}");
     }
 
+    let additional_scope_names = scope_buf
+        .as_deref()
+        .map(source_map_scopes::collect_additional_names)
+        .unwrap_or_default();
+
     let mut map = if source_map.enabled() {
         Some(cm.build_source_map(
             &src_map_buf,
@@ -241,6 +257,7 @@ where
                 source_file_name,
                 output_path: output_path.as_deref(),
                 names: source_map_names,
+                additional_names: &additional_scope_names,
                 inline_sources_content,
                 emit_columns: emit_source_map_columns,
                 ignore_list: source_map_ignore_list,
@@ -251,6 +268,19 @@ where
     };
 
     if let Some(map) = &mut map {
+        if should_emit_scope_map {
+            if let Some(scope_buf) = scope_buf.as_deref() {
+                let encoded_scopes =
+                    source_map_scopes::encode_scopes(scope_buf, &cm, map, |file_name| {
+                        map_file_name_to_source(source_file_name, output_path.as_deref(), file_name)
+                    });
+
+                if let Some(scopes) = encoded_scopes {
+                    map.set_scopes(Some(scopes));
+                }
+            }
+        }
+
         if let Some(source_root) = source_root {
             map.set_source_root(Some(BytesStr::from_str_slice(source_root)))
         }
@@ -306,6 +336,7 @@ struct SwcSourceMapConfig<'a> {
     output_path: Option<&'a Path>,
 
     names: &'a FxHashMap<BytePos, Atom>,
+    additional_names: &'a [String],
 
     inline_sources_content: bool,
 
@@ -314,38 +345,52 @@ struct SwcSourceMapConfig<'a> {
     ignore_list: Option<FilePattern>,
 }
 
-impl SourceMapGenConfig for SwcSourceMapConfig<'_> {
-    fn file_name_to_source(&self, f: &FileName) -> String {
-        if let Some(file_name) = self.source_file_name {
-            return file_name.to_string();
-        }
+fn map_file_name_to_source(
+    source_file_name: Option<&str>,
+    output_path: Option<&Path>,
+    f: &FileName,
+) -> String {
+    if let Some(file_name) = source_file_name {
+        return file_name.to_string();
+    }
 
-        let Some(base_path) = self.output_path.as_ref().and_then(|v| v.parent()) else {
-            return f.to_string();
-        };
-        let target = match f {
-            FileName::Real(v) => v,
-            _ => return f.to_string(),
-        };
+    let Some(base_path) = output_path.and_then(|v| v.parent()) else {
+        return f.to_string();
+    };
+    let target = match f {
+        FileName::Real(v) => v,
+        _ => return f.to_string(),
+    };
 
-        let rel = pathdiff::diff_paths(target, base_path);
-        match rel {
-            Some(v) => {
-                let s = v.to_string_lossy().to_string();
-                if cfg!(target_os = "windows") {
-                    s.replace('\\', "/")
-                } else {
-                    s
-                }
+    let rel = pathdiff::diff_paths(target, base_path);
+    match rel {
+        Some(v) => {
+            let s = v.to_string_lossy().to_string();
+            if cfg!(target_os = "windows") {
+                s.replace('\\', "/")
+            } else {
+                s
             }
-            None => f.to_string(),
         }
+        None => f.to_string(),
+    }
+}
+
+impl SourceMapGenConfig for SwcSourceMapConfig<'_> {
+    fn file_name_to_source(&self, f: &FileName) -> String {
+        map_file_name_to_source(self.source_file_name, self.output_path, f)
     }
 
     fn name_for_bytepos(&self, pos: BytePos) -> Option<&str> {
         self.names.get(&pos).map(|v| &**v)
     }
 
+    fn for_each_additional_name(&self, op: &mut dyn FnMut(&str)) {
+        for name in self.additional_names {
+            op(name);
+        }
+    }
+
     fn inline_sources_content(&self, _: &FileName) -> bool {
         self.inline_sources_content
     }