punycode: add pending deprecation

PR-URL: https://github.com/nodejs/node/pull/38444
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

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/message/core_line_numbers.out

@@ -1,9 +1,9 @@
-node:punycode:42
+node:punycode:52
 	throw new RangeError(errors[type]);
 	^
 
 RangeError: Invalid input
-    at error (node:punycode:42:8)
+    at error (node:punycode:52:8)
     at Object.decode (node:punycode:*:*)
     at Object.<anonymous> (*test*message*core_line_numbers.js:*:*)
     at Module._compile (node:internal/modules/cjs/loader:*:*)

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');