punycode: add pending deprecation

doc/api/deprecations.md

@@ -831,12 +831,15 @@ The [`require.extensions`][] property is deprecated.
 ### DEP0040: `punycode` module
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/38444
+    description: Added support for `--pending-deprecation`.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7941
     description: Documentation-only deprecation.
 -->
 
-Type: Documentation-only
+Type: Documentation-only (supports [`--pending-deprecation`][])
 
 The [`punycode`][] module is deprecated. Please use a userland alternative
 instead.

lib/punycode.js

@@ -1,5 +1,15 @@
 'use strict';
 
+const { getOptionValue } = require('internal/options');
+if (getOptionValue('--pending-deprecation')){
+	process.emitWarning(
+		'The `punycode` module is deprecated. Please use a userland ' +
+		'alternative instead.',
+		'DeprecationWarning',
+		'DEP0040',
+	);
+}
+
 /** Highest positive signed 32-bit float value */
 const maxInt = 2147483647; // aka. 0x7FFFFFFF or 2^31-1
 

test/parallel/test-punycode.js

@@ -1,3 +1,5 @@
+// Flags: --pending-deprecation
+
 // Copyright Joyent, Inc. and other Node contributors.
 //
 // Permission is hereby granted, free of charge, to any person obtaining a
@@ -20,7 +22,13 @@
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 'use strict';
-require('../common');
+const common = require('../common');
+
+const punycodeWarning =
+  'The `punycode` module is deprecated. Please use a userland alternative ' +
+  'instead.';
+common.expectWarning('DeprecationWarning', punycodeWarning, 'DEP0040');
+
 const punycode = require('punycode');
 const assert = require('assert');