Design

TODO: This is super out of date.

We're using a modified version of the coffee-script compiler which you can find on the Benbria github. This is vanilla coffee-script, except that this keeps track of what line/column tokens start and end on, and passes that information on to the abstract-syntax tree during the compile step. We're working with Jeremy to get these changes integrated into coffee-script.

coffee-coverage starts by compiling a .coffee file into an abstract syntax tree (AST). coffee-coverage then walks the AST and inserts instrumentation nodes before every statement (almost every statement... There's some weird things you can do in coffeescript which will end up with more than one statement on a single line.) The instrumentation essentially transforms this:

console.log "Hello World"

into this:

if (! _$jscoverage["hello.coffee"]) {
    _$jscoverage["hello.coffee"] = [];
    _$jscoverage["hello.coffee"][1] = 0;
}
_$jscoverage["hello.coffee"].source = ["console.log \"Hello World\"", ""];

(function() {

  _$jscoverage["hello.coffee"][1]++;
  console.log("Hello World");

}).call(this);

So _$jscoverage[ file ][ line ] has a count of the total number of times line number line of file has been executed. _$jscoverage[ file ].source has a copy of the original coffee-script source code, split into lines, where other tools can extract it to display the original source.

The name for "_$jscoverage" comes from the JSCoverage tool - coffee-coverage's output is compatible with it, which means we can use standard tools like Mocha's html-cov reporter.