$

node_modules/spawn-wrap/README.md

@@ -0,0 +1,111 @@
+# spawn-wrap
+
+Wrap all spawned Node.js child processes by adding environs and
+arguments ahead of the main JavaScript file argument.
+
+Any child processes launched by that child process will also be
+wrapped in a similar fashion.
+
+This is a bit of a brutal hack, designed primarily to support code
+coverage reporting in cases where tests or the system under test are
+loaded via child processes rather than via `require()`.
+
+It can also be handy if you want to run your own mock executable
+instead of some other thing when child procs call into it.
+
+[![Build Status](https://travis-ci.org/istanbuljs/spawn-wrap.svg)](https://travis-ci.org/istanbuljs/spawn-wrap)
+
+## USAGE
+
+```javascript
+var wrap = require('spawn-wrap')
+
+// wrap(wrapperArgs, environs)
+var unwrap = wrap(['/path/to/my/main.js', 'foo=bar'], { FOO: 1 })
+
+// later to undo the wrapping, you can call the returned function
+unwrap()
+```
+
+In this example, the `/path/to/my/main.js` file will be used as the
+"main" module, whenever any Node or io.js child process is started,
+whether via a call to `spawn` or `exec`, whether node is invoked
+directly as the command or as the result of a shebang `#!` lookup.
+
+In `/path/to/my/main.js`, you can do whatever instrumentation or
+environment manipulation you like.  When you're done, and ready to run
+the "real" main.js file (ie, the one that was spawned in the first
+place), you can do this:
+
+```javascript
+// /path/to/my/main.js
+// process.argv[1] === 'foo=bar'
+// and process.env.FOO === '1'
+
+// my wrapping manipulations
+setupInstrumentationOrCoverageOrWhatever()
+process.on('exit', function (code) {
+  storeCoverageInfoSynchronously()
+})
+
+// now run the instrumented and covered or whatever codes
+require('spawn-wrap').runMain()
+```
+
+## ENVIRONMENT VARIABLES
+
+Spawn-wrap responds to two environment variables, both of which are
+preserved through child processes.
+
+`SPAWN_WRAP_DEBUG=1` in the environment will make this module dump a
+lot of information to stderr.
+
+`SPAWN_WRAP_SHIM_ROOT` can be set to a path on the filesystem where
+the shim files are written in a `.node-spawn-wrap-<id>` folder.  By
+default this is done in `$HOME`, but in some environments you may wish
+to point it at some other root.  (For example, if `$HOME` is mounted
+as read-only in a virtual machine or container.)
+
+## CONTRACTS and CAVEATS
+
+The initial wrap call uses synchronous I/O.  Probably you should not
+be using this script in any production environments anyway.
+
+Also, this will slow down child process execution by a lot, since
+we're adding a few layers of indirection.
+
+The contract which this library aims to uphold is:
+
+* Wrapped processes behave identical to their unwrapped counterparts
+  for all intents and purposes.  That means that the wrapper script
+  propagates all signals and exit codes.
+* If you send a signal to the wrapper, the child gets the signal.
+* If the child exits with a numeric status code, then the wrapper
+  exits with that code.
+* If the child dies with a signal, then the wrapper dies with the
+  same signal.
+* If you execute any Node child process, in any of the various ways
+  that such a thing can be done, it will be wrapped.
+* Children of wrapped processes are also wrapped.
+
+(Much of this made possible by
+[foreground-child](http://npm.im/foreground-child).)
+
+There are a few ways situations in which this contract cannot be
+adhered to, despite best efforts:
+
+1. In order to handle cases where `node` is invoked in a shell script,
+   the `PATH` environment variable is modified such that the the shim
+   will be run before the "real" node.  However, since Windows does
+   not allow executing shebang scripts like regular programs, a
+   `node.cmd` file is required.
+2. Signal propagation through `dash` doesn't always work.  So, if you
+   use `child_process.exec()` on systems where `/bin/sh` is actually
+   `dash`, then the process may exit with a status code > 128 rather
+   than indicating that it received a signal.
+3. `cmd.exe` is even stranger with how it propagates and interprets
+   unix signals.  If you want your programs to be portable, then
+   probably you wanna not rely on signals too much.
+4. It *is* possible to escape the wrapping, if you spawn a bash
+   script, and that script modifies the `PATH`, and then calls a
+   specific `node` binary explicitly.