Implements Istanbul coverage support and user-defined sourceTransformers

Readme.md

@@ -44,12 +44,31 @@ following:
   of the sandboxed module.
 * `globals:` An object of global variables to inject into the sandboxed module.
 * `locals:` An object of local variables to inject into the sandboxed module.
+* `sourceTransformers:` An object of named functions to transform the source code of
+the sandboxed module's file (e.g. transpiler language, code coverage).
 
 ### SandboxedModule.require(moduleId, [options])
 
 Identical to `SandboxedModule.load()`, but returns `sandboxedModule.exports`
 directly.
 
+### SandboxedModule.configure(options)
+
+Sets options globally across all uses of `SandboxedModule.load()` and
+`SandboxedModule.require()`. This way, a commonly needed require, global, local,
+or sourceTransformer can be specified once across all sandboxed modules.
+
+### SandboxedModule.registerBuiltInSourceTransformer(name)
+
+Enables a built-in source transformer by name. Currently, SandboxedModule ships
+with two built in source transformers:
+
+* "coffee" - Compiles source with CoffeeScript [Enabled by default for backwards compatibility]
+* "istanbul" - Instruments sources via istanbul when istanbul code coverage is running.
+
+For example, if you'd like to use SandboxedModule in conjunction with istanbul,
+just run `SandboxedModule.registerBuiltInSourceTransformer('istanbul')`.
+
 ### sandboxedModule.filename
 
 The full path to the module.
@@ -77,6 +96,29 @@ Modifying this object has no effect on the state of the sandbox.
 An object holding a list of all module required by the sandboxed module itself.
 The keys are the `moduleId`s used for the require calls.
 
+### sandboxedModule.sourceTransformers
+
+An object of named functions which will transform the source code required with
+`SandboxedModule.require`. For example, CoffeeScript &
+[istanbul](https://github.com/gotwarlost/istanbul) support is implemented with
+built-in sourceTransformer functions (see `#registerBuiltInSourceTransformer`).
+
+A source transformer receives the source (as it's been transformed thus far) and
+**must** return the transformed source (whether it's changed or unchanged).
+
+An example source transformer to change all instances of the number "3" to "5"
+would look like this:
+
+``` javascript
+SandboxedModule.require('../fixture/baz', {
+  sourceTransformers: {
+    turn3sInto5s: function(source) {
+      return source.replace(/3/g,'5');
+    }
+  }
+})
+```
+
 ## License
 
 sandboxed-module is licensed under the MIT license.

lib/sandboxed_module.js

@@ -5,6 +5,9 @@ var fs = require('fs');
 var vm = require('vm');
 var path = require('path');
 var parent = module.parent;
+var globalOptions = {};
+var registeredBuiltInSourceTransformers = ['coffee']
+
 module.exports = SandboxedModule;
 function SandboxedModule() {
   this.id = null;
@@ -13,6 +16,7 @@ function SandboxedModule() {
   this.globals = {};
   this.locals = {};
   this.required = {};
+  this.sourceTransformers = {};
 
   this._options = {};
 }
@@ -31,6 +35,19 @@ SandboxedModule.require = function(moduleId, options) {
   return this.load(moduleId, options, trace).exports;
 };
 
+SandboxedModule.configure = function(options) {
+  Object.keys(options).forEach(function(name) {
+    globalOptions[name] = options[name];
+  });
+};
+
+SandboxedModule.registerBuiltInSourceTransformer = function(name) {
+  if(registeredBuiltInSourceTransformers.indexOf(name) === -1) {
+    registeredBuiltInSourceTransformers.push(name)
+  }
+};
+
+
 Object.defineProperty(SandboxedModule.prototype, 'exports', {
   enumerable: true,
   configurable: true,
@@ -52,6 +69,7 @@ SandboxedModule.prototype._init = function(moduleId, trace, options) {
 
   this.locals = this._getLocals();
   this.globals = this._getGlobals();
+  this.sourceTransformers = this._getSourceTransformers();
 
   this._compile();
 };
@@ -70,6 +88,10 @@ SandboxedModule.prototype._getLocals = function() {
     exports: this.exports
   };
 
+  for (var globalKey in globalOptions.locals) {
+    locals[globalKey] = globalOptions.locals[globalKey];
+  }
+
   for (var key in this._options.locals) {
     locals[key] = this._options.locals[key];
   }
@@ -84,16 +106,44 @@ SandboxedModule.prototype._getGlobals = function() {
     globals[globalKey] = global[globalKey];
   }
 
+  for (var globalOptionKey in globalOptions.globals) {
+    globals[globalOptionKey] = globalOptions.globals[globalOptionKey];
+  }
+
   for (var optionsGlobalsKey in this._options.globals) {
     globals[optionsGlobalsKey] = this._options.globals[optionsGlobalsKey];
   }
 
   return globals;
 };
 
+SandboxedModule.prototype._getSourceTransformers = function() {
+  var sourceTransformers = getStartingSourceTransformers();
+
+  for (var globalKey in globalOptions.sourceTransformers) {
+    sourceTransformers[globalKey] = globalOptions.sourceTransformers[globalKey];
+  }
+
+  for (var userKey in this._options.sourceTransformers) {
+    sourceTransformers[userKey] = this._options.sourceTransformers[userKey];
+  }
+
+  return sourceTransformers;
+};
+
+SandboxedModule.prototype._getRequires = function() {
+  var requires = this._options.requires || {};
+
+  for (var key in globalOptions.requires) {
+    requires[key] = globalOptions.requires[key];
+  }
+
+  return requires;
+};
+
 SandboxedModule.prototype._requireInterceptor = function() {
   var requireProxy = requireLike(this.filename, true);
-  var inject = this._options.requires;
+  var inject = this._getRequires();
   var self = this;
 
   function requireInterceptor(request) {
@@ -125,24 +175,15 @@ SandboxedModule.prototype._compile = function() {
 SandboxedModule.prototype._getCompileInfo = function() {
   var localVariables = [];
   var localValues = [];
-  var coffeeScript;
 
   for (var localVariable in this.locals) {
     localVariables.push(localVariable);
     localValues.push(this.locals[localVariable]);
   }
 
-  var sourceToWrap = fs.readFileSync(this.filename, 'utf8');
-
-  if (this.filename.search('.coffee$') != -1){
-    // Try loading coffee-script module if we think this is a coffee-script file
-    try {
-      coffeeScript = require('coffee-script');
-      sourceToWrap = coffeeScript.compile(sourceToWrap);
-    } catch (e) {
-      // if coffee-script not installed, we can just proceed as normal
-    }
-  }
+  var sourceToWrap = Object.keys(this.sourceTransformers).reduce(function(source, name){
+    return this.sourceTransformers[name].bind(this)(source);
+  }.bind(this), fs.readFileSync(this.filename, 'utf8'));
 
   var source =
     'global = GLOBAL = root = (function() { return this; })();' +
@@ -174,3 +215,42 @@ function getStartingGlobals() {
     URIError: URIError
   };
 }
+
+function getStartingSourceTransformers() {
+  var sourceTransformers = {};
+
+  registeredBuiltInSourceTransformers.forEach(function(name){
+    sourceTransformers[name] = builtInSourceTransformers[name];
+  });
+
+  return sourceTransformers;
+}
+
+var builtInSourceTransformers = {
+  coffee: function(source) {
+    if (this.filename.search('.coffee$') !== -1){
+      return require('coffee-script').compile(source);
+    } else {
+      return source;
+    }
+  },
+  istanbul: function(source) {
+    var coverageVariable, istanbulCoverageMayBeRunning = false;
+    Object.keys(global).forEach(function(name) {
+      if(name.indexOf("$$cov_") == 0 && global[name]) {
+        istanbulCoverageMayBeRunning = true;
+        coverageVariable = name;
+      }
+    });
+
+    if(istanbulCoverageMayBeRunning) {
+      try {
+        var istanbul = require('istanbul'),
+            instrumenter = new istanbul.Instrumenter({coverageVariable: coverageVariable}),
+            instrumentMethod = instrumenter.instrumentSync.bind(instrumenter);
+        source = instrumentMethod(source, this.filename);
+      } catch(e) {}
+    }
+    return source;
+  }
+};

package.json

@@ -23,6 +23,7 @@
   },
   "devDependencies": {
     "urun": "0.0.6",
-    "coffee-script": "1.x"
+    "coffee-script": "1.x",
+    "istanbul": "~0.1.44"
   }
 }

test/fixture/baz.js

@@ -0,0 +1,8 @@
+module.exports = {
+  biz: function(){
+    return 1 + 3;
+  },
+  bang: function() {
+    return require('./foo') + someLocal + someGlobal + 3;
+  }
+};

test/integration/test-configure.js

@@ -0,0 +1,26 @@
+var assert = require('assert');
+var SandboxedModule = require('../..');
+
+SandboxedModule.configure({
+  globals: {
+    someGlobal: 9
+  },
+  locals: {
+    someLocal: 4
+  },
+  requires: {
+    './foo': 1
+  },
+  sourceTransformers: {
+    turn3sInto5s: function(source) {
+      return source.replace(/3/g,'5');
+    }
+  }
+});
+
+SandboxedModule = require('../..');
+
+var baz = SandboxedModule.load('../fixture/baz').exports;
+
+assert.strictEqual(baz.bang(), 19);
+

test/integration/test-custom-source-transformer.js

@@ -0,0 +1,13 @@
+var assert = require('assert');
+var SandboxedModule = require('../..');
+
+var baz = SandboxedModule.load('../fixture/baz', {
+  sourceTransformers: {
+    turn3sInto5s: function(source) {
+      return source.replace(/3/g,'5');
+    }
+  }
+}).exports;
+
+assert.strictEqual(baz.biz(), 6);
+

test/integration/test-istanbul.js

@@ -0,0 +1,11 @@
+var assert = require('assert');
+var SandboxedModule = require('../..');
+SandboxedModule.registerBuiltInSourceTransformer('istanbul');
+
+global['$$cov_1234'] = {};
+var baz = SandboxedModule.load('../fixture/baz').exports,
+    instrumentedFunction = /^function \(\){__cov_.*\.f\['1'\]\+\+;__cov_.*\.s\['2'\]\+\+;return 1\+3;}$/;
+
+assert.strictEqual(baz.biz.toString().match(instrumentedFunction).length, 1);
+
+delete global['$$cov_1234'];