From ed9ee1ff7e35ae170c3b00ad916dff36af70d8fb Mon Sep 17 00:00:00 2001
From: Nate Fischer <ntfschr@google.com>
Date: Tue, 13 Nov 2018 00:33:24 -0800
Subject: [PATCH] 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  |  9 ++++++++-
 test/plugin.js | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/src/common.js b/src/common.js
index 14a49fc5..693dbb3a 100644
--- a/src/common.js
+++ b/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
diff --git a/test/plugin.js b/test/plugin.js
index bafe2a05..21f8db99 100644
--- a/test/plugin.js
+++ b/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;
+  }
+});