lib: deprecate node --debug at runtime

Fixes: nodejs#9789
PR-URL: nodejs#10970
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

doc/api/deprecations.md

@@ -511,6 +511,15 @@ Type: Documentation-only
 The `fs.SyncWriteStream` class was never intended to be a publicly accessible
 API.
 
+<a id="DEP0062"></a>
+### DEP0062: node --debug
+
+Type: Runtime
+
+`--debug` activates the legacy V8 debugger interface, which has been removed as
+of V8 5.8. It is replaced by Inspector which is activated with `--inspect`
+instead.
+
 [alloc]: buffer.html#buffer_class_method_buffer_alloc_size_fill_encoding
 [alloc_unsafe_size]: buffer.html#buffer_class_method_buffer_allocunsafe_size
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size

lib/_debug_agent.js

@@ -1,5 +1,10 @@
 'use strict';
 
+process.emitWarning(
+  'node --debug is deprecated. Please use node --inspect instead.',
+  'DeprecationWarning',
+  'DEP0062');
+
 const assert = require('assert');
 const net = require('net');
 const util = require('util');

test/parallel/test-debug-port-from-cmdline.js

@@ -2,12 +2,19 @@
 const common = require('../common');
 const assert = require('assert');
 const spawn = require('child_process').spawn;
+const os = require('os');
 
 const debugPort = common.PORT;
 const args = ['--interactive', '--debug-port=' + debugPort];
 const childOptions = { stdio: ['pipe', 'pipe', 'pipe', 'ipc'] };
 const child = spawn(process.execPath, args, childOptions);
 
+const reDeprecationWarning = new RegExp(
+  /^\(node:\d+\) \[DEP0062\] DeprecationWarning: /.source +
+  /node --debug is deprecated. /.source +
+  /Please use node --inspect instead.$/.source
+);
+
 child.stdin.write("process.send({ msg: 'childready' });\n");
 
 child.stderr.on('data', function(data) {
@@ -37,12 +44,20 @@ function processStderrLine(line) {
 }
 
 function assertOutputLines() {
-  const expectedLines = [
-    'Starting debugger agent.',
-    'Debugger listening on 127.0.0.1:' + debugPort,
+  // need a var so can swap the first two lines in following
+  // eslint-disable-next-line no-var
+  var expectedLines = [
+    /^Starting debugger agent.$/,
+    reDeprecationWarning,
+    new RegExp(`^Debugger listening on 127.0.0.1:${debugPort}$`)
   ];
 
+  if (os.platform() === 'win32') {
+    expectedLines[1] = expectedLines[0];
+    expectedLines[0] = reDeprecationWarning;
+  }
+
   assert.strictEqual(outputLines.length, expectedLines.length);
   for (let i = 0; i < expectedLines.length; i++)
-    assert(expectedLines[i].includes(outputLines[i]));
+    assert(expectedLines[i].test(outputLines[i]));
 }

test/parallel/test-debug-signal-cluster.js

@@ -8,7 +8,8 @@ const path = require('path');
 
 const port = common.PORT;
 const serverPath = path.join(common.fixturesDir, 'clustered-server', 'app.js');
-const args = [`--debug-port=${port}`, serverPath];
+// cannot use 'Flags: --no-deprecation' since it doesn't effect child
+const args = [`--debug-port=${port}`, '--no-deprecation', serverPath];
 const options = { stdio: ['inherit', 'inherit', 'pipe', 'ipc'] };
 const child = spawn(process.execPath, args, options);