From a16b570f8c1283db81b85ff78ce73608a4265f61 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sat, 11 Mar 2017 12:18:53 -0800
Subject: [PATCH] src: add --pending-deprecation and NODE_PENDING_DEPRECATION
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Command line flag and environment variable that can be used to
indicate that pending deprecations should be emitted.

PR-URL: https://github.com/nodejs/node/pull/11968
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/cli.md                            | 28 ++++++++++++++
 doc/node.1                                |  8 ++++
 src/node.cc                               | 12 ++++++
 src/node_config.cc                        |  3 ++
 src/node_internals.h                      |  4 ++
 test/parallel/test-pending-deprecation.js | 45 +++++++++++++++++++++++
 6 files changed, 100 insertions(+)
 create mode 100644 test/parallel/test-pending-deprecation.js

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 8e5915d5f9aef7..e003d38fe2cfb4 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -137,6 +137,20 @@ added: v0.11.14
 
 Throw errors for deprecations.
 
+### `--pending-deprecation`
+<!-- YAML
+added: REPLACEME
+-->
+
+Emit pending deprecation warnings.
+
+*Note*: Pending deprecations are generally identical to a runtime deprecation
+with the notable exception that they are turned *off* by default and will not
+be emitted unless either the `--pending-deprecation` command line flag, or the
+`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
+are used to provide a kind of selective "early warning" mechanism that
+developers may leverage to detect deprecated API usage.
+
 ### `--no-warnings`
 <!-- YAML
 added: v6.0.0
@@ -383,6 +397,20 @@ added: v7.5.0
 
 When set to `1`, process warnings are silenced.
 
+### `NODE_PENDING_DEPRECATION=1`
+<!-- YAML
+added: REPLACEME
+-->
+
+When set to `1`, emit pending deprecation warnings.
+
+*Note*: Pending deprecations are generally identical to a runtime deprecation
+with the notable exception that they are turned *off* by default and will not
+be emitted unless either the `--pending-deprecation` command line flag, or the
+`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
+are used to provide a kind of selective "early warning" mechanism that
+developers may leverage to detect deprecated API usage.
+
 ### `NODE_PRESERVE_SYMLINKS=1`
 <!-- YAML
 added: v7.1.0
diff --git a/doc/node.1 b/doc/node.1
index e4d46b792e775c..3dff0a78290d68 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -115,6 +115,10 @@ Print stack traces for deprecations.
 .BR \-\-throw\-deprecation
 Throw errors for deprecations.
 
+.TP
+.BR \-\-pending\-deprecation
+Emit pending deprecation warnings.
+
 .TP
 .BR \-\-no\-warnings
 Silence all process warnings (including deprecations).
@@ -259,6 +263,10 @@ When set to \fI1\fR, process warnings are silenced.
 .BR NODE_PATH =\fIpath\fR[:\fI...\fR]
 \':\'\-separated list of directories prefixed to the module search path.
 
+.TP
+.BR NODE_PENDING_DEPRECATION = \fI1\fR
+When set to \fI1\fR, emit pending deprecation warnings.
+
 .TP
 .BR NODE_REPL_HISTORY =\fIfile\fR
 Path to the file used to store the persistent REPL history. The default path
diff --git a/src/node.cc b/src/node.cc
index a24dcdb734e79b..21296a1418ad34 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -209,6 +209,10 @@ bool trace_warnings = false;
 // that is used by lib/module.js
 bool config_preserve_symlinks = false;
 
+// Set by ParseArgs when --pending-deprecation or NODE_PENDING_DEPRECATION
+// is used.
+bool config_pending_deprecation = false;
+
 // Set in node.cc by ParseArgs when --redirect-warnings= is used.
 std::string config_warning_file;  // NOLINT(runtime/string)
 
@@ -3768,6 +3772,8 @@ static void ParseArgs(int* argc,
       short_circuit = true;
     } else if (strcmp(arg, "--zero-fill-buffers") == 0) {
       zero_fill_all_buffers = true;
+    } else if (strcmp(arg, "--pending-deprecation") == 0) {
+      config_pending_deprecation = true;
     } else if (strcmp(arg, "--v8-options") == 0) {
       new_v8_argv[new_v8_argc] = "--help";
       new_v8_argc += 1;
@@ -4187,6 +4193,12 @@ void Init(int* argc,
   V8::SetFlagsFromString(NODE_V8_OPTIONS, sizeof(NODE_V8_OPTIONS) - 1);
 #endif
 
+  {
+    std::string text;
+    config_pending_deprecation =
+        SafeGetenv("NODE_PENDING_DEPRECATION", &text) && text[0] == '1';
+  }
+
   // Allow for environment set preserving symlinks.
   {
     std::string text;
diff --git a/src/node_config.cc b/src/node_config.cc
index 05a163c3f1e4df..f4729a64fe6bcb 100644
--- a/src/node_config.cc
+++ b/src/node_config.cc
@@ -49,6 +49,9 @@ static void InitConfig(Local<Object> target,
   if (config_preserve_symlinks)
     READONLY_BOOLEAN_PROPERTY("preserveSymlinks");
 
+  if (config_pending_deprecation)
+    READONLY_BOOLEAN_PROPERTY("pendingDeprecation");
+
   if (!config_warning_file.empty()) {
     Local<String> name = OneByteString(env->isolate(), "warningFile");
     Local<String> value = String::NewFromUtf8(env->isolate(),
diff --git a/src/node_internals.h b/src/node_internals.h
index fa219b96cdb4a9..e07cb9d6d39a41 100644
--- a/src/node_internals.h
+++ b/src/node_internals.h
@@ -76,6 +76,10 @@ extern bool config_expose_internals;
 // it to stderr.
 extern std::string config_warning_file;  // NOLINT(runtime/string)
 
+// Set in node.cc by ParseArgs when --pending-deprecation or
+// NODE_PENDING_DEPRECATION is used
+extern bool config_pending_deprecation;
+
 // Tells whether it is safe to call v8::Isolate::GetCurrent().
 extern bool v8_initialized;
 
diff --git a/test/parallel/test-pending-deprecation.js b/test/parallel/test-pending-deprecation.js
new file mode 100644
index 00000000000000..402ec79b1bc04c
--- /dev/null
+++ b/test/parallel/test-pending-deprecation.js
@@ -0,0 +1,45 @@
+'use strict';
+
+// Tests that --pending-deprecation and NODE_PENDING_DEPRECATION both
+// set the process.binding('config').pendingDeprecation flag that is
+// used to determine if pending deprecation messages should be shown.
+// The test is performed by launching two child processes that run
+// this same test script with different arguments. If those exit with
+// code 0, then the test passes. If they don't, it fails.
+
+const common = require('../common');
+
+const assert = require('assert');
+const config = process.binding('config');
+const fork = require('child_process').fork;
+
+function message(name) {
+  return `${name} did not set the process.binding('config').` +
+         'pendingDeprecation flag.';
+}
+
+switch (process.argv[2]) {
+  case 'env':
+  case 'switch':
+    assert.strictEqual(config.pendingDeprecation, true);
+    break;
+  default:
+    // Verify that the flag is off by default.
+    assert.strictEqual(config.pendingDeprecation, undefined);
+
+    // Test the --pending-deprecation command line switch.
+    fork(__filename, ['switch'], {
+      execArgv: ['--pending-deprecation'],
+      silent: true
+    }).on('exit', common.mustCall((code) => {
+      assert.strictEqual(code, 0, message('--pending-deprecation'));
+    }));
+
+    // Test the NODE_PENDING_DEPRECATION environment var.
+    fork(__filename, ['env'], {
+      env: {NODE_PENDING_DEPRECATION: 1},
+      silent: true
+    }).on('exit', common.mustCall((code) => {
+      assert.strictEqual(code, 0, message('NODE_PENDING_DEPRECATION'));
+    }));
+}