feat(plugin): support deprecating plugins

This adds a new wrap() option named `.deprecate`. This currently accepts
a string value, which will be the deprecation message for the plugin.
Deprecation works on standard commands as well as pipes. The call stack
points directly to the deprecated method, and not to any ShellJS
internals.

Fixes #541
Test: This adds unit tests.

src/common.js

@@ -4,6 +4,7 @@
 
 var os = require('os');
 var fs = require('fs');
+var util = require('util');
 var glob = require('glob');
 var shell = require('..');
 
@@ -312,7 +313,7 @@ exports.randomFileName = randomFileName;
 // command-logging, and other nice things
 function wrap(cmd, fn, options) {
   options = options || {};
-  return function () {
+  var fun = function () {
     var retValue = null;
 
     state.currentCmd = cmd;
@@ -409,6 +410,11 @@ function wrap(cmd, fn, options) {
     state.currentCmd = 'shell.js';
     return retValue;
   };
+  if (options.deprecated) {
+    var msg = options.deprecated; // This is the deprecation message.
+    fun = util.deprecate(fun, msg);
+  }
+  return fun;
 } // wrap
 exports.wrap = wrap;
 
@@ -427,6 +433,7 @@ var DEFAULT_WRAP_OPTIONS = {
   pipeOnly: false,
   wrapOutput: true,
   unix: true,
+  deprecated: '',
 };
 
 // This is populated during plugin registration

test/plugin.js

@@ -165,3 +165,37 @@ test('Cannot overwrite an existing command', t => {
   }, 'Command `cat` already exists');
   t.is(shell.cat, oldCat);
 });
+
+test('Deprecated command', t => {
+  process.throwDeprecation = true;
+  const oldThrowDep = process.throwDeprecation;
+  try {
+    plugin.register('dep', function dep(opt, arg) { return arg; }, {
+      cmdOptions: null,
+      deprecated: 'Use the foo method instead',
+    });
+
+    t.throws(() => {
+      shell.dep('bar');
+    }, /Use the foo method instead/);
+  } finally {
+    process.throwDeprecation = oldThrowDep;
+  }
+});
+
+test('Deprecated command in pipe', t => {
+  process.throwDeprecation = true;
+  plugin.register('depPipe', function depPipe(opt, arg) { return arg; }, {
+    cmdOptions: null,
+    deprecated: 'Use the foo pipe instead',
+    canReceivePipe: true,
+  });
+  const oldThrowDep = process.throwDeprecation;
+  try {
+    t.throws(() => {
+      shell.cat('./package.json').depPipe('bar');
+    }, /Use the foo pipe instead/);
+  } finally {
+    process.throwDeprecation = oldThrowDep;
+  }
+});