@bloomberg/pasta-sourcemaps

@bloomberg/pasta-sourcemaps

pasta, or Pretty (and) Accurate Stack Trace Analysis, is an implementation of an extension to the source map format that allows for accurate function name decoding. It allows you to extract function-related metadata from a source file and encode it into a source map, as well as decode a pasta-enriched source map to query enclosing function names for a given location.

Background

Source code often gets modified one way or another before hitting production - through transpilation, minification, etc. Looking at a "raw" crash stack of generated code can be hard work.

// sample.js
const penne     = () => { throw Error(); }
const spaghetti = () => penne();
const orzo      = () => spaghetti();
orzo();

// **original** output                           // **compiled** output
Error                                            Error
    at penne (sample.js:2:33)                        at r (out.js:1:82)
    at spaghetti (sample.js:3:25)         vs         at o (out.js:1:97)
    at orzo (sample.js:4:25)                         at n (out.js:1:107)

Today, source maps already provide the ability to produce accurate locations (filename, line number, column number) in a crash stack, but not enclosing function names. This hinders debugging and confuses automatic crash stack consolidation.

pasta extends the source map format with a x_com_bloomberg_sourcesFunctionMappings field to allow for accurate function name decoding. See spec.md to learn more about the pasta format.

Features

• Native support for ECMAScript, TypeScript, JSX and TSX input source types
• Encoder allows you to roll your own parser to support other languages

Installation

npm install @bloomberg/pasta-sourcemaps

API

@bloomberg/pasta-sourcemaps exposes three utilities:

• parser
• encoder
• decoder

The parser and the encoder are normally used in conjunction to parse a source file and encode the resulting function descriptions into a source map.

The decoder takes a pasta-enriched sourcemap and gives back enclosing function names for a given source file, line and column location.

To read the full API documentation please visit the GitHub Pages

Usage

Parser

const pasta = require("@bloomberg/pasta-sourcemaps");

const source = "function orzo(){}; function penne(){};";
const functionDescs = pasta.parse(source, "ECMAScript");

console.log(functionDescs);

output

[
    {
        name: '<top-level>',
        startLine: 0,
        startColumn: 0,
        endLine: 0,
        endColumn: 38
    },
    {
        name: 'orzo',
        startLine: 0,
        startColumn: 0,
        endLine: 0,
        endColumn: 17
    },
    {
        name: 'penne',
        startLine: 0,
        startColumn: 18,
        endLine: 0,
        endColumn: 37
    }
]

Encoder

const pasta = require("@bloomberg/pasta-sourcemaps");

const sourceMap = {
    version: 3,
    file: 'out.js',
    sources: [ 'barilla.js' ],
    names: [ 'orzo', 'penne' ],
    mappings: 'AAAA,SAASA,QAAU,SAASC'
};

const functionDescs = new Map([
    [
        "barilla.js", [
        {
            name: '<top-level>',
            startLine: 0,
            startColumn: 0,
            endLine: 0,
            endColumn: 38
        },
        {
            name: 'orzo',
            startLine: 0,
            startColumn: 0,
            endLine: 0,
            endColumn: 17
        },
        {
            name: 'penne',
            startLine: 0,
            startColumn: 18,
            endLine: 0,
            endColumn: 37
        }
        ]
    ]
]);

const enrichedSourceMap = pasta.encode(sourceMap, functionDescs);

console.log(enrichedSourceMap);

output

{
    version: 3,
    file: 'out.js',
    sources: [ 'barilla.js' ],
    names: [ 'orzo', 'penne', '<top-level>' ],
    mappings: 'AAAA,SAASA,QAAU,SAASC',
    x_com_bloomberg_sourcesFunctionMappings: [ 'EAAAsC,FAAArB,CAkBAoB' ]
}

Decoder

const pasta = require("@bloomberg/pasta-sourcemaps");

const enrichedSourceMap = {
    version: 3,
    file: 'out.js',
    sources: [ 'barilla.js' ],
    names: [ 'orzo', 'penne', '<top-level>' ],
    mappings: 'AAAA,SAASA,QAAU,SAASC',
    x_com_bloomberg_sourcesFunctionMappings: [ 'EAAAsC,FAAArB,CAkBAoB' ]
};

const decoder = new pasta.SourceMapDecoder(enrichedSourceMap);

decoder.decode("barilla.js", 0, 4);  // orzo
decoder.decode("barilla.js", 0, 25); // penne

Development

• Clone this repository
• Install dependencies:
  • npm install
• Write code, add tests!
• To build code and run tests:
  • npm run build
  • npm run test
• To run lint checks prior to committing:
  • npm run lint

Contributions

We :heart: contributions.

Have you had a good experience with pasta-sourcemaps? Why not share some love and contribute code, or just let us know about any issues you had with it?

We welcome issue reports here; be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.

Before sending a Pull Request, please make sure you read our Contribution Guidelines.

License

Apache 2.0

Code of Conduct

This project has adopted a Code of Conduct. If you have any concerns about the Code, or behavior which you have experienced in the project, please contact us at [e-mail].

Security Vulnerability Reporting

If you believe you have identified a security vulnerability in this project, please send email to the project team at [e-mail], detailing the suspected issue and any methods you've found to reproduce it.

Please do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until we've had an opportunity to review and address them.