[RFC] Source maps - General

[am11]

(Redirected from: #601 (comment), credit to @mgreter)

This is a general source-maps issue. It covers all the source maps progress. Going by LESS CLI, it provides these options:

 --source-map[=FILENAME]  Outputs a v3 sourcemap to the filename (or output filename.map)
 --source-map-rootpath=X  adds this path onto the sourcemap filename and less file paths
 --source-map-basepath=X  Sets sourcemap base path, defaults to current working directory.
 --source-map-less-inline puts the less files into the map instead of referencing them
 --source-map-map-inline  puts the map (and any less files) into the output css file
 --source-map-url=URL     the complete url and filename put in the less file

the description of last line is confusing, it is basically for sourceMappingURL in output CSS file. see less/less.js#2264

Here we will investigate the progress being made for open issues: #498, #444, #324 and #212.

Following are the requirements:

• Report correct columns and lines, matching the "index base" for of other transcompilers: ruby-sass, less, coffeescirpt and since so forth.
• Capture mapping for each token. In the code: body, nav { background: linear-gradient(top, left, #111) center no-repeat #111 }, there are 14 tokens: body, ,, nav, {, background-image, :, linear-gradient, top, left, #111, center, no-repeat, #111 and }.
• Option for map JSON to be encoded in base64 and set to sourceMappingURL's value in CSS (as opposed to exist as a separate file). An equivalent of LESS' source-map-map-inline.
• Option to add source-code in sourceContents array in map JSON. Answer to LESS' source-map-less-inline. This comes handy when the source files are not accessible remotely (HTTP?).
• Ability to set custom URL for sourceMappingURL. if this option is set, it will use the string provided by user as is. Answer to LESS' source-map-url.
• Add tests; which decode B64 and B64VLQ first and then match the mappings. Also test paths in sourceMappingURL comment in CSS, sources array and file elements in map's JSON.

[mgreter]

I have checked off two features, since they should be implemented by #591, which is now included in master. As you already referenced, I've started to implement more mappings and already got something working. But to call this complete, it needs a lot more work. I guess we should keep this issue clean and have more detailed discussions in seperate threads!

[simonexmachina]

I've created an issue for appending to a provided source map and a summary of the status of source maps in broccoli-sass, which may be of interest to this discussion.

[mgreter]

@am11 can we close this and make more clear targets from this?
IMHO points like "Capture mapping for each token" are not really satisfiable, since "each" is a very wide goal. Maybe you could factor out the concrete stuff that is still missing in libsass! IMO with my latests PR for source-maps we are at a point where we will need full whitespace parsing to make it even more correct! So my latest PR does not include bracket mappings etc.

[am11]

@mgreter, there are a lot of tools which make use of source-maps. Some are solely related to browser's F12, and then there some other interesting uses-cases for IDE etc. I can give you an example of WebEssentials extension for VS which when VS run the web-application hooks to the browser's F12 tools FF/IE/Chrome and let the user change the markup, CSS etc. in realtime from f12 tool. Now if the CSS was generated by Sass or Less, the change made in browser tool is reflected in the source file, and this magic happens via source map! But this is definitely not possible if the expression in hand is implicitly computed, for instance mixin, strings interpolations etc. (so it stops there).

The questions is "where to stop?" or "how much details is fair enough?". IMO, if we are able to achieve mapping of each independent verb(s) or word(s) of CSS to that of Sass, to the extent that if the token under question is a variable, it points to the latest assignment of that variable or direct mapping (CSS code in Sass), then its more than sufficient.

I agree this issue should be closed as resolved as the lines are blur and since there are no universal specs (even outside the Sass circle). We always have Less as a reference, as it being one of the kind. Although there happens to be a fundamental difference in Less and Sass (Less being declarative language, while Sass is imperative), source-map is something common emitted by both lang's parsers against the generated CSS. Hence comparable!

Would you rather close this issue with the PR merge? :)

Thank you for the great work! Libsass generated source-maps are definitely is a much better shape than ever before. 👍

[mgreter]

This issue should (hopefully) be addressed/fixed by #792.
Please try with latest master and open a new issue if the problem still exists.
Thank you!