Move sourcemap content generation to the sourcemap module, document the sourcemap module

Author: AlisCode

compiler-core/src/codegen.rs

@@ -263,31 +263,17 @@ impl<'a> JavaScript<'a> {
             self.typescript,
             &mut source_map_emitter,
         );
+
         tracing::debug!(name = ?js_name, "Generated js module");
         writer.write(&path, &output?)?;
 
-        match source_map_emitter {
-            SourceMapEmitter::Null => Ok(()),
-            SourceMapEmitter::Emit(builder) => {
-                let sourcemap_name = format!("{js_name}.mjs.map");
-                let sourcemap_path = self.output_directory.join(sourcemap_name);
-                tracing::debug!(path = ?sourcemap_path, name = ?js_name, "Emitting sourcemap for module");
-
-                // NOTE: This is a bit inefficient
-                // * we first write to a buffer
-                // * then construct a String based on the output
-                // * then write to the output
-                let sourcemap = builder.into_sourcemap();
-
-                let mut output = Vec::new();
-                sourcemap
-                    .to_writer(&mut output)
-                    .expect("Failed to write sourcemap to memory.");
-                let output =
-                    String::from_utf8(output).expect("Sourcemap did not generate valid UTF-8.");
-
-                writer.write(&sourcemap_path, &output)
-            }
+        if let Some(sourcemap_content) = source_map_emitter.maybe_emit_sourcemap_content() {
+            let sourcemap_name = format!("{js_name}.mjs.map");
+            let sourcemap_path = self.output_directory.join(sourcemap_name);
+            tracing::debug!(path = ?sourcemap_path, name = ?js_name, "Emitting sourcemap for module");
+            writer.write(&sourcemap_path, &sourcemap_content)?;
         }
+
+        Ok(())
     }
 }

compiler-core/src/sourcemap.rs

@@ -1,13 +1,28 @@
+//! Sourcemap generation utils
+//!
+//! # What are sourcemaps ?
+//!
+//! Sourcemaps are a tool of web development that helps debugging when working
+//! with code that is generated from other code.
+//!
+//! A sourcemap is essentially a list of positions in a target file (the
+//! code generated by the tool - in our case JavaScript) linked to a location
+//! in the source code (Gleam) that is responsible for its presence.
+
 use sourcemap::SourceMapBuilder;
 
 use crate::line_numbers::LineColumn;
 
+/// Tells whether or not the codegen should emit sourcemaps for all Gleam
+/// modules
 #[derive(Debug, Clone, Copy)]
 pub enum SourceMapSupport {
     Emit,
     None,
 }
 
+/// An utility that handles the emission of an associated sourcemap
+/// for a given Gleam module.
 pub enum SourceMapEmitter {
     Null,
     Emit(Box<SourceMapBuilder>),
@@ -24,6 +39,8 @@ impl std::fmt::Debug for SourceMapEmitter {
 }
 
 impl SourceMapEmitter {
+    /// Adds one mapping on the generated (javascript) file
+    /// referring to the given Gleam source location
     pub fn add_mapping(
         &mut self,
         generated_code_line: u32,
@@ -47,6 +64,32 @@ impl SourceMapEmitter {
         }
     }
 
+    /// Consumes the SourceMapEmitter to get the content of the sourcemap as a
+    /// String
+    pub fn maybe_emit_sourcemap_content(self) -> Option<String> {
+        match self {
+            SourceMapEmitter::Null => None,
+            SourceMapEmitter::Emit(builder) => {
+                let sourcemap = builder.into_sourcemap();
+                let mut output = Vec::new();
+                // We first write to a vector then build a string, hoping that
+                // the `sourcemap` crate generated a valid sourcemap. If it
+                // did not, it is a bug that should be reported.
+                //
+                // SourceMap currently does not support being written directly
+                // to a string.
+                sourcemap
+                    .to_writer(&mut output)
+                    .expect("Failed to write sourcemap to memory.");
+                let content =
+                    String::from_utf8(output).expect("Sourcemap did not generate valid UTF-8.");
+                Some(content)
+            }
+        }
+    }
+
+    /// Creates a null SourceMapEmitter.
+    /// Any operation on this SourceMapEmitter will be no-ops
     pub fn null() -> Self {
         SourceMapEmitter::Null
     }