Source-map path resolution when CoffeeScript 2.x output is restored to a different directory

Question

Source-map path integrity after restoring CoffeeScript build output
The goal is to confirm that a restored .js.map file still maps runtime positions to the original .coffee sources when the compiled JavaScript, map file, and source tree are returned to different directory paths. CoffeeScript 2.x retains the source-map option and implicit-return semantics, but the compiler writes source locations relative to the build environment. Moving any one of the three files independently can break the mapping, and constructors that end in a bare expression may return an unexpected value at runtime.
Version assumption: behavior differs between CoffeeScript 1.x and 2.x, so the compiler line should be identified before relying on module syntax or source-map output. Practical verification concerns whether stack traces and breakpoints resolve to .coffee lines after restoration.

Are source paths in the generated map absolute, relative to the source file, or relative to the compiled JavaScript?
Can sourcesContent in the map be used to reconstruct the original CoffeeScript when only the compiled output is restored?
Does a path change after restoration require regenerating the map with CoffeeScript 2.x, or can sourceRoot be adjusted safely?

Tasadduq Burney · Answer

In CoffeeScript 2.x, source-map paths are generated relative to the compiled JavaScript file (unless a specific sourceRoot was defined during compilation). If you restore the .js and .js.map files to a directory structure that differs from the original build environment, the relative paths stored in the map will no longer point to the correct .coffee source files, breaking debugger breakpoints and stack trace resolution.

Path Resolution and Recovery
To address the specific constraints of restoring build output to new locations, consider the following behaviors:

Path Type: By default, the sources array in the map contains relative paths. Moving the map file independently of the JavaScript file, or moving both to a new root without updating the source tree, invalidates these references.
  sourcesContent Usage: If the map was generated with sourcesContent enabled, the original CoffeeScript source code is embedded directly within the .js.map file. This allows debuggers to display the original code even if the .coffee files are missing from the restored environment. However, this does not "reconstruct" the source tree on disk; it only enables in-browser/IDE visualization.
  Adjusting sourceRoot: You can manually edit the sourceRoot property in the JSON map file to point to the new location of the source files. This is a safe alternative to regeneration if the relative distance between the source files themselves has not changed.

Verification Steps
To verify if your restoration has broken the mapping, perform these checks:

Inspect the Map: Open the .js.map file in a text editor. Locate the "sources": [...] array. If the paths are ../src/file.coffee but your restored structure is ../old_src/file.coffee, the mapping is broken.
  Runtime Validation: Trigger a known error in the application. Check the browser console or IDE debugger; if the stack trace points to the .js file instead of the .coffee file, the path resolution is failing.

Recommendation
If the directory depth has changed significantly, the most reliable fix is to regenerate the maps using the CoffeeScript 2.x compiler in the new environment. If regeneration is impossible, manually updating the sourceRoot is the primary recovery path.

Missing Diagnostic: To provide a more precise path correction, please specify if the sourcesContent field is currently present in your restored .js.map files.

Source-map path resolution when CoffeeScript 2.x output is restored to a different directory

Source-map path integrity after restoring CoffeeScript build output

1 answer

Path Resolution and Recovery

Verification Steps

Recommendation

Your perspective belongs here.

0 question comments