feat: add debugId support across all crates (ECMA-426)

Parses both `debugId` and `debug_id` fields from source maps,
stores and roundtrips through to_json(). Added to parser, generator,
CLI info command, NAPI bindings, and WASM bindings.

Author: BartWaardenburg

ROADMAP.md

@@ -155,7 +155,7 @@ Node.js WASM bindings completing the full source map pipeline.
 
 ## Future
 
-- [ ] Debug ID support (`debugId` field, part of ECMA-426)
+- [x] Debug ID support (`debugId` field, part of ECMA-426)
 - [ ] NAPI bindings for generator and remapping
 - [ ] WASM build target for browser (devtools, playgrounds, edge runtimes)
 - [ ] Scopes & variables support (ECMA-426 proposal — no library supports this yet)

crates/cli/src/main.rs

@@ -377,6 +377,7 @@ fn cmd_info(file: &PathBuf, json: bool) -> Result<(), CliError> {
             "totalContentSize": content_size,
             "fileSize": raw.len(),
             "ignoreList": sm.ignore_list,
+            "debugId": sm.debug_id,
         });
         println!("{}", serde_json::to_string_pretty(&obj).unwrap());
     } else {
@@ -407,6 +408,10 @@ fn cmd_info(file: &PathBuf, json: bool) -> Result<(), CliError> {
             );
         }
 
+        if let Some(ref id) = sm.debug_id {
+            println!("Debug ID:     {id}");
+        }
+
         if !sm.ignore_list.is_empty() {
             println!("Ignore list:  {} sources", sm.ignore_list.len());
         }

crates/generator/src/lib.rs

@@ -51,6 +51,7 @@ pub struct SourceMapGenerator {
     names: Vec<String>,
     mappings: Vec<Mapping>,
     ignore_list: Vec<u32>,
+    debug_id: Option<String>,
 
     // Dedup maps for O(1) lookup
     source_map: HashMap<String, u32>,
@@ -68,6 +69,7 @@ impl SourceMapGenerator {
             names: Vec::new(),
             mappings: Vec::new(),
             ignore_list: Vec::new(),
+            debug_id: None,
             source_map: HashMap::new(),
             name_map: HashMap::new(),
         }
@@ -78,6 +80,11 @@ impl SourceMapGenerator {
         self.source_root = Some(root);
     }
 
+    /// Set the debug ID (UUID) for this source map (ECMA-426).
+    pub fn set_debug_id(&mut self, id: String) {
+        self.debug_id = Some(id);
+    }
+
     /// Register a source file and return its index.
     pub fn add_source(&mut self, source: &str) -> u32 {
         if let Some(&idx) = self.source_map.get(source) {
@@ -441,6 +448,12 @@ impl SourceMapGenerator {
             json.push(']');
         }
 
+        // debugId
+        if let Some(ref id) = self.debug_id {
+            json.push_str(r#","debugId":"#);
+            json.push_str(&json_quote(id));
+        }
+
         json.push('}');
         json
     }
@@ -767,6 +780,23 @@ mod tests {
         assert!(sm.original_position_for(5, 0).is_some());
     }
 
+    #[test]
+    fn debug_id() {
+        let mut builder = SourceMapGenerator::new(None);
+        builder.set_debug_id("85314830-023f-4cf1-a267-535f4e37bb17".to_string());
+        let src = builder.add_source("input.js");
+        builder.add_mapping(0, 0, src, 0, 0);
+
+        let json = builder.to_json();
+        assert!(json.contains(r#""debugId":"85314830-023f-4cf1-a267-535f4e37bb17""#));
+
+        let sm = srcmap_sourcemap::SourceMap::from_json(&json).unwrap();
+        assert_eq!(
+            sm.debug_id.as_deref(),
+            Some("85314830-023f-4cf1-a267-535f4e37bb17")
+        );
+    }
+
     #[cfg(feature = "parallel")]
     mod parallel_tests {
         use super::*;

crates/sourcemap/src/lib.rs

@@ -117,6 +117,10 @@ struct RawSourceMap<'a> {
     mappings: &'a str,
     #[serde(default, rename = "ignoreList")]
     ignore_list: Vec<u32>,
+    /// Debug ID for associating generated files with source maps (ECMA-426).
+    /// Accepts both `debugId` (spec) and `debug_id` (Sentry compat).
+    #[serde(default, rename = "debugId", alias = "debug_id")]
+    debug_id: Option<String>,
     /// Indexed source maps use `sections` instead of `mappings`.
     #[serde(default)]
     sections: Option<Vec<RawSection>>,
@@ -146,6 +150,8 @@ pub struct SourceMap {
     pub sources_content: Vec<Option<String>>,
     pub names: Vec<String>,
     pub ignore_list: Vec<u32>,
+    /// Debug ID (UUID) for associating generated files with source maps (ECMA-426).
+    pub debug_id: Option<String>,
 
     /// Flat decoded mappings, ordered by (generated_line, generated_column).
     mappings: Vec<Mapping>,
@@ -213,6 +219,7 @@ impl SourceMap {
             sources_content,
             names: raw.names,
             ignore_list: raw.ignore_list,
+            debug_id: raw.debug_id,
             mappings,
             line_offsets,
             reverse_index: OnceCell::new(),
@@ -354,6 +361,7 @@ impl SourceMap {
             sources_content: all_sources_content,
             names: all_names,
             ignore_list: all_ignore_list,
+            debug_id: None,
             mappings: all_mappings,
             line_offsets,
             reverse_index: OnceCell::new(),
@@ -553,6 +561,11 @@ impl SourceMap {
             json.push(']');
         }
 
+        if let Some(ref id) = self.debug_id {
+            json.push_str(r#","debugId":"#);
+            json_quote_into(&mut json, id);
+        }
+
         json.push('}');
         json
     }
@@ -2069,6 +2082,51 @@ mod tests {
         assert_eq!(sm2.source(loc.source), "a.js");
     }
 
+    #[test]
+    fn parse_debug_id() {
+        let json = r#"{"version":3,"sources":["a.js"],"names":[],"mappings":"AAAA","debugId":"85314830-023f-4cf1-a267-535f4e37bb17"}"#;
+        let sm = SourceMap::from_json(json).unwrap();
+        assert_eq!(
+            sm.debug_id.as_deref(),
+            Some("85314830-023f-4cf1-a267-535f4e37bb17")
+        );
+    }
+
+    #[test]
+    fn parse_debug_id_snake_case() {
+        let json = r#"{"version":3,"sources":["a.js"],"names":[],"mappings":"AAAA","debug_id":"85314830-023f-4cf1-a267-535f4e37bb17"}"#;
+        let sm = SourceMap::from_json(json).unwrap();
+        assert_eq!(
+            sm.debug_id.as_deref(),
+            Some("85314830-023f-4cf1-a267-535f4e37bb17")
+        );
+    }
+
+    #[test]
+    fn parse_no_debug_id() {
+        let json = r#"{"version":3,"sources":["a.js"],"names":[],"mappings":"AAAA"}"#;
+        let sm = SourceMap::from_json(json).unwrap();
+        assert_eq!(sm.debug_id, None);
+    }
+
+    #[test]
+    fn debug_id_roundtrip() {
+        let json = r#"{"version":3,"sources":["a.js"],"names":[],"mappings":"AAAA","debugId":"85314830-023f-4cf1-a267-535f4e37bb17"}"#;
+        let sm = SourceMap::from_json(json).unwrap();
+        let output = sm.to_json();
+        assert!(output.contains(r#""debugId":"85314830-023f-4cf1-a267-535f4e37bb17""#));
+        let sm2 = SourceMap::from_json(&output).unwrap();
+        assert_eq!(sm.debug_id, sm2.debug_id);
+    }
+
+    #[test]
+    fn debug_id_not_in_json_when_absent() {
+        let json = r#"{"version":3,"sources":["a.js"],"names":[],"mappings":"AAAA"}"#;
+        let sm = SourceMap::from_json(json).unwrap();
+        let output = sm.to_json();
+        assert!(!output.contains("debugId"));
+    }
+
     /// Generate a test source map JSON with realistic structure.
     fn generate_test_sourcemap(lines: usize, segs_per_line: usize, num_sources: usize) -> String {
         let sources: Vec<String> = (0..num_sources)

packages/generator-wasm/__tests__/generator-wasm.test.mjs

@@ -149,6 +149,28 @@ describe('ignoreList', () => {
   })
 })
 
+describe('debugId', () => {
+  it('sets and outputs debugId', () => {
+    const gen = new SourceMapGenerator()
+    gen.setDebugId('85314830-023f-4cf1-a267-535f4e37bb17')
+    gen.addSource('input.js')
+    gen.addGeneratedMapping(0, 0)
+
+    const map = JSON.parse(gen.toJSON())
+    assert.equal(map.debugId, '85314830-023f-4cf1-a267-535f4e37bb17')
+    gen.free()
+  })
+
+  it('omits debugId when not set', () => {
+    const gen = new SourceMapGenerator()
+    gen.addGeneratedMapping(0, 0)
+
+    const map = JSON.parse(gen.toJSON())
+    assert.equal(map.debugId, undefined)
+    gen.free()
+  })
+})
+
 describe('large roundtrip', () => {
   it('handles 1000 mappings correctly', () => {
     const gen = new SourceMapGenerator('bundle.js')

packages/generator-wasm/src/lib.rs

@@ -33,6 +33,12 @@ impl SourceMapGenerator {
         self.inner.set_source_root(root.to_string());
     }
 
+    /// Set the debug ID (UUID) for this source map (ECMA-426).
+    #[wasm_bindgen(js_name = "setDebugId")]
+    pub fn set_debug_id(&mut self, id: &str) {
+        self.inner.set_debug_id(id.to_string());
+    }
+
     /// Set the content for a source file by index.
     #[wasm_bindgen(js_name = "setSourceContent")]
     pub fn set_source_content(&mut self, source_idx: u32, content: &str) {

packages/sourcemap-wasm/__tests__/sourcemap-wasm.test.mjs

@@ -122,6 +122,27 @@ describe('originalPositionsFor (batch)', () => {
   })
 })
 
+describe('debugId', () => {
+  it('returns debugId when present', () => {
+    const map = JSON.stringify({
+      version: 3,
+      sources: ['a.js'],
+      names: [],
+      mappings: 'AAAA',
+      debugId: '85314830-023f-4cf1-a267-535f4e37bb17',
+    })
+    const sm = new SourceMap(map)
+    assert.equal(sm.debugId, '85314830-023f-4cf1-a267-535f4e37bb17')
+    sm.free()
+  })
+
+  it('returns undefined when debugId is absent', () => {
+    const sm = new SourceMap(SIMPLE_MAP)
+    assert.equal(sm.debugId, undefined)
+    sm.free()
+  })
+})
+
 describe('indexed source maps', () => {
   it('parses an indexed (sectioned) source map', () => {
     const indexedMap = JSON.stringify({

packages/sourcemap-wasm/src/lib.rs

@@ -85,6 +85,12 @@ impl SourceMap {
             .collect()
     }
 
+    /// Get the debug ID (UUID) if present.
+    #[wasm_bindgen(getter, js_name = "debugId")]
+    pub fn debug_id(&self) -> Option<String> {
+        self.inner.debug_id.clone()
+    }
+
     /// Total number of decoded mappings.
     #[wasm_bindgen(getter, js_name = "mappingCount")]
     pub fn mapping_count(&self) -> u32 {

packages/sourcemap/src/lib.rs

@@ -101,6 +101,11 @@ impl JsSourceMap {
         results
     }
 
+    #[napi(getter)]
+    pub fn debug_id(&self) -> Option<String> {
+        self.inner.debug_id.clone()
+    }
+
     #[napi(getter)]
     pub fn mapping_count(&self) -> u32 {
         self.inner.mapping_count() as u32