bugsplat-git/source-mapper

📚➡️🥞 Node.js module for converting mangled stack traces to original positions in transpiled JS/TS code.

BugSplat

Crash and error reporting built for busy developers.

🗺️ source-mapper

source-mapper is a utility for translating function names, file names and line numbers in uglified JavaScript Error stack frames to the corresponding values in the original source. source-mapper is distributed as both a package and a library and is used by the BugSplat backend to deliver crash reporting as a service for JavaScript and TypeScript applications.

The following is an example JavaScript Error stack converted to its TypeScript equivalent using source-mapper:

Error: BugSplat rocks!
    at crash (/Users/bobby/Desktop/bugsplat/source-mapper/dist/bin/cmd.js:16:11)
    at /Users/bobby/Desktop/bugsplat/source-mapper/dist/bin/cmd.js:6:9
    at Object.<anonymous> (/Users/bobby/Desktop/bugsplat/source-mapper/dist/bin/cmd.js:14:3)

Error: BugSplat rocks!
    at crash (../../bin/cmd.ts:15:10)
    at <unknown> (../../bin/cmd.ts:5:8)
    at Object.<anonymous> (../../bin/cmd.ts:12:2)

🖥 Command Line

1. Install this package globally npm i -g @bugsplat/source-mapper
2. Run source-mapper -h to see the latest usage information:

bobby@BugSplat % ~ % source-mapper -h

    @bugsplat/source-mapper contains a command line utility and set of libraries to help you demangle JavaScript stack frames.

    source-mapper command line usage:

        source-mapper [ [ "/source-map-directory" OR "/source.js.map" ] [ "/stack-trace.txt" ] ]
    
    * Optionally provide either a path to a directory containing source maps or a .map.js file - Defaults to the current directory
    * Optionally provide a path to a .txt file containing a JavaScript Error stack trace - Defaults to the value in the clipboard
    
    ❤️ [email protected]

3. Run source-mapper and optionally specify a path to a directory containing .js.map files, path to a single .js.map file, and a path to a .txt file containing a stringified JavaScript Error. If no options are provided source-mapper will default to looking in the current directory for source maps and attempt to read the stringified JavaScript error stack from the system clipboard.

🧩 API

1. Install this package locally npm i @bugsplat/source-mapper
2. Import SourceMapper from @bugsplat/source-mapper

import { SourceMapper } from '@bugsplat/source-mapper';

3. Create a new instance of SourceMapper passing it an array of paths to source map files. You can also await the static factory function createFromDirectory(directory: string): Promise<SourceMapper> which takes a path to a directory and creates a new SourceMapper with an array of source map file paths it finds in the specified directory

const mapper = new SourceMapper(sourceMapFilePaths);

const mapper = await SourceMapper.createFromDirectory(directory);

4. Await the call to convert passing it the stack property from a JavaScript Error object

const result = await mapper.convert(error.stack);

Thanks for using BugSplat!

source-mapper's Issues

Use original function name instead of <unknown>

Support command-line invocation

We should support invoked from the command line with either a path to a directory full of map files or a path to a single map file.

An example of how we've achieved invoking a script from the command line on a globally installed package can be seen here.

Unify Processing of Single File and Directory cases

• Convert directory case to mulitple file case by scanning given directory and saving collection of all map file names
• Single file case initializes collection with single file
• Remove private field fromDirectory
• Converter will operator foreach item in collection

TypeScript build for distribution

We should support invoked from the command line with either a path to a directory full of map files or a path to a single map file. An example of how we've achieved invoking a script from the command line on a globally installed package can be seen here.

• Support usage as a library
• Support usage as a command-line tool installed globally
• Release to npm

Add linting rules

I'm particularly sensitive to missing semi-colons, but there are other things here that would be nice to have as well.

Make Command Line Invocation Easier

[NAB] Also if a filename of '-' is given as the first parameter, read from stdin? What if the second param is not supplied? Does it read from the current directory?

Originally posted by @csmith0651 in #14 (comment)

Let's reverse the order of the parameters to make this easier:

stack-converter {{path-to-source-maps}} {{path-to-stack-string}}

if {{path-to-stack-string}} isn't provided read from stdin

if {{path-to-source-maps}} try the current directory

add log statements so the user knows this is what we're doing?

support all the permutations of -h /h -help /help etc so the user can get the help info.

Add JSDoc Rule to ESLint

It looks like we're using JSDoc annotations on our public methods, let's lint these to make sure they conform to JSDoc standards.

Update README.md

Update to match our new conventions

Add README

I think this will eventually be released on npm so adding a readme here would be great.

Support Stack Frames with Windows Paths

node's path.basename works differently when run on posix vs windows when dealing with posix vs windows paths. we need to support getting the basename for a file that contains both styles of paths.

https://nodejs.org/api/path.html#windows-vs-posix

Do we need a copyright comment in all source files?

comment with copyright. or does the license file cover that?

Originally posted by @csmith0651 in #14 (comment)

I was unable to find a good answer on the internet. I think the LICENSE file at the root of the repo is likely good enough for our case but better safe than sorry!

Support the top line of the Error object

A full error object looks like:

Error: Http failure response for https://app.bugsplat.com/api/subscription.php?database=AutoDb_04102021_95345: 502 OK
    at t.<anonymous> (https://app.bugsplat.com/v2/main-es2015.cd6a577558c44d1be6da.js:1:1387216)
    at Generator.next (<anonymous>)
    at https://app.bugsplat.com/v2/main-es2015.cd6a577558c44d1be6da.js:1:995452
    at new P (https://app.bugsplat.com/v2/polyfills-es2015.2846539e99aef31c99d5.js:1:91860)
    at s (https://app.bugsplat.com/v2/main-es2015.cd6a577558c44d1be6da.js:1:995200)
    at t.handleError (https://app.bugsplat.com/v2/main-es2015.cd6a577558c44d1be6da.js:1:1386969)
    at e.<anonymous> (https://app.bugsplat.com/v2/26-es2015.25866671d60dd4058a4f.js:1:3715)
    at Generator.next (<anonymous>)
    at https://app.bugsplat.com/v2/main-es2015.cd6a577558c44d1be6da.js:1:995452
    at new P (https://app.bugsplat.com/v2/polyfills-es2015.2846539e99aef31c99d5.js:1:91860)

We seem to be chopping off the Error: Http failure response for https://app.bugsplat.com/api/subscription.php?database=AutoDb_04102021_95345: 502 OK part and returning only the trace. We should attach this top piece to the string that is returned by convert.

Add Teamcity Build

Fix dist script

We found a way to distribute our other libraries by adding the "files" property to package.json. Distributing this way removes the need to copy files into dist manually and cd to that directory before publishing.

Add Quote Rule to ESLint

Single quotes seem to be the JavaScript/TypeScript standard. Let's also extend the rules to the tests now that we are closer to release.

Test against stack traces on various browsers

We know at the very least Safari outputs a weirdly formatted stack trace. We should test some other formats too!

• Chrome
• Firefox
• Safari
• Edge
• Node.js
• IE11 (?)
• Deno (?)

Should Correctly Parse TypeError

In addition to Error, there's also TypeError, RangeError, SyntaxError etc.