refactor: comprehensive architecture improvements across all crates

- Centralize external dependencies in workspace Cargo.toml
- Add debug_assert guards before all unsafe String::from_utf8_unchecked calls
- Replace String error erasure with typed ScopesError in ParseError chain
- Add #[inline] to hot-path functions across codec, scopes, sourcemap, generator
- Add Hash, PartialOrd, Ord trait impls to Segment for completeness
- Add single-char fast path to vlq_decode_unsigned
- Use Box<RawValue> for indexed source map sections (avoid JSON re-serialize)
- Add get_source/get_name safe accessor methods to SourceMap
- Use impl Into<String> for flexible generator setter APIs
- Extract resolve_sources/build_source_map helpers to eliminate duplication
- Remove redundant dedup HashMaps from ConcatBuilder
- Cache has_range_mappings boolean to avoid O(n) scan on every call
- Convert find_nth_scope from recursive to iterative (stack overflow safety)
- Change scopes definition field from usize to u32 for platform consistency
- Replace .unwrap() with .expect() with descriptive messages
- Fix CLI error handling: replace unwrap with proper CliError propagation

Author: BartWaardenburg

Cargo.toml

@@ -16,6 +16,16 @@ srcmap-remapping = { version = "0.1.3", path = "crates/remapping" }
 srcmap-scopes = { version = "0.1.3", path = "crates/scopes" }
 srcmap-symbolicate = { version = "0.1.3", path = "crates/symbolicate" }
 criterion = { version = "0.5", features = ["html_reports"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["raw_value"] }
+rayon = "1"
+napi = { version = "2", default-features = false, features = ["napi6"] }
+napi-derive = "2"
+napi-build = "2"
+wasm-bindgen = "0.2"
+serde-wasm-bindgen = "0.6"
+js-sys = "0.3"
+clap = { version = "4", features = ["derive"] }
 
 [profile.release]
 lto = true

crates/cli/Cargo.toml

@@ -18,5 +18,5 @@ srcmap-codec = { workspace = true }
 srcmap-sourcemap = { workspace = true }
 srcmap-remapping = { workspace = true }
 srcmap-symbolicate = { workspace = true }
-clap = { version = "4", features = ["derive"] }
-serde_json = "1"
+clap = { workspace = true }
+serde_json = { workspace = true }

crates/cli/src/main.rs

@@ -687,7 +687,9 @@ fn cmd_mappings(
     };
 
     let filtered: Vec<_> = if let Some(source_name) = source_filter {
-        let source_idx = sm.source_index(source_name).unwrap();
+        let source_idx = sm
+            .source_index(source_name)
+            .ok_or_else(|| CliError::not_found(format!("source not found: {source_name}")))?;
         all.iter()
             .filter(|m| m.source == source_idx)
             .skip(offset)
@@ -812,7 +814,8 @@ fn cmd_concat(
     }
 
     let map_json = builder.to_json();
-    let result = SourceMap::from_json(&map_json).unwrap();
+    let result = SourceMap::from_json(&map_json)
+        .map_err(|e| CliError::parse(format!("failed to parse generated map: {e}")))?;
 
     if dry_run {
         if json {

crates/codec/Cargo.toml

@@ -17,7 +17,7 @@ parallel = ["rayon"]
 crate-type = ["lib"]
 
 [dependencies]
-rayon = { version = "1", optional = true }
+rayon = { workspace = true, optional = true }
 
 [dev-dependencies]
 criterion = { workspace = true }

crates/codec/src/decode.rs

@@ -1,7 +1,6 @@
 use crate::vlq::vlq_decode;
 use crate::{DecodeError, Line, Segment, SourceMapMappings};
 
-
 /// Decode a VLQ-encoded source map mappings string into structured data.
 ///
 /// The mappings string uses `;` to separate lines and `,` to separate

crates/codec/src/encode.rs

@@ -67,7 +67,9 @@ pub fn encode(mappings: &SourceMapMappings) -> String {
         }
     }
 
-    // SAFETY: buf contains only ASCII base64 chars, semicolons, and commas
+    // SAFETY: vlq_encode only pushes bytes from BASE64_ENCODE (all ASCII),
+    // and we only add b';' and b',' — all valid UTF-8.
+    debug_assert!(buf.is_ascii());
     unsafe { String::from_utf8_unchecked(buf) }
 }
 
@@ -189,6 +191,8 @@ pub fn encode_parallel(mappings: &SourceMapMappings) -> String {
         buf.extend_from_slice(line_bytes);
     }
 
-    // SAFETY: VLQ output is always valid ASCII/UTF-8
+    // SAFETY: vlq_encode only pushes bytes from BASE64_ENCODE (all ASCII),
+    // and we only add b';' — all valid UTF-8.
+    debug_assert!(buf.is_ascii());
     unsafe { String::from_utf8_unchecked(buf) }
 }

crates/codec/src/lib.rs

@@ -62,6 +62,27 @@ pub struct Segment {
     len: u8,
 }
 
+impl std::hash::Hash for Segment {
+    #[inline]
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        (**self).hash(state);
+    }
+}
+
+impl PartialOrd for Segment {
+    #[inline]
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for Segment {
+    #[inline]
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        (**self).cmp(&**other)
+    }
+}
+
 impl Segment {
     /// Create a 1-field segment (generated column only).
     #[inline]

crates/codec/src/vlq.rs

@@ -186,9 +186,34 @@ pub fn vlq_encode_unsigned(out: &mut Vec<u8>, value: u64) {
 /// Unlike signed VLQ, no sign bit extraction is performed.
 #[inline]
 pub fn vlq_decode_unsigned(input: &[u8], pos: usize) -> Result<(u64, usize), DecodeError> {
-    let mut result: u64 = 0;
-    let mut shift: u32 = 0;
-    let mut i = pos;
+    if pos >= input.len() {
+        return Err(DecodeError::UnexpectedEof { offset: pos });
+    }
+
+    let b0 = input[pos];
+    if b0 >= 128 {
+        return Err(DecodeError::InvalidBase64 {
+            byte: b0,
+            offset: pos,
+        });
+    }
+    let d0 = BASE64_DECODE[b0 as usize];
+    if d0 == 255 {
+        return Err(DecodeError::InvalidBase64 {
+            byte: b0,
+            offset: pos,
+        });
+    }
+
+    // Fast path: single character (value fits in 5 bits, no continuation)
+    if (d0 & 0x20) == 0 {
+        return Ok((d0 as u64, 1));
+    }
+
+    // Multi-character unsigned VLQ
+    let mut result: u64 = (d0 & 0x1F) as u64;
+    let mut shift: u32 = 5;
+    let mut i = pos + 1;
 
     loop {
         if i >= input.len() {
@@ -207,17 +232,16 @@ pub fn vlq_decode_unsigned(input: &[u8], pos: usize) -> Result<(u64, usize), Dec
             return Err(DecodeError::InvalidBase64 { byte, offset: i });
         }
 
-        let digit = digit as u64;
         i += 1;
 
         if shift >= VLQ_MAX_SHIFT {
             return Err(DecodeError::VlqOverflow { offset: pos });
         }
 
-        result += (digit & VLQ_BASE_MASK) << shift;
+        result += ((digit & 0x1F) as u64) << shift;
         shift += VLQ_BASE_SHIFT;
 
-        if (digit & VLQ_CONTINUATION_BIT) == 0 {
+        if (digit & 0x20) == 0 {
             break;
         }
     }

crates/generator/Cargo.toml

@@ -20,11 +20,11 @@ crate-type = ["lib"]
 srcmap-codec = { workspace = true }
 srcmap-sourcemap = { workspace = true }
 srcmap-scopes = { workspace = true }
-rayon = { version = "1", optional = true }
+rayon = { workspace = true, optional = true }
 
 [dev-dependencies]
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
+serde = { workspace = true }
+serde_json = { workspace = true }
 criterion = { workspace = true }
 
 [[bench]]