fs: runtime deprecate rmdir recursive option

Author: aduh95

doc/api/deprecations.md

@@ -2663,19 +2663,25 @@ The [`crypto.Certificate()` constructor][] is deprecated. Use
 ### DEP0147: `fs.rmdir(path, { recursive: true })`
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/37216
+    description: Runtime deprecation.
   - version: v15.0.0
     pr-url: https://github.com/nodejs/node/pull/35562
-    description: Runtime deprecation.
+    description: Runtime deprecation for permissive behavior.
   - version: v14.14.0
     pr-url: https://github.com/nodejs/node/pull/35579
     description: Documentation-only deprecation.
 -->
 
 Type: Runtime
 
-In future versions of Node.js, `fs.rmdir(path, { recursive: true })` will throw
-if `path` does not exist or is a file.
-Use `fs.rm(path, { recursive: true, force: true })` instead.
+In future versions of Node.js, `recursive` option will be ignored for
+`fs.rmdir`, `fs.rmdirSync`, and `fs.promises.rmdir`.
+
+Use `fs.rm(path, { recursive: true, force: true })`,
+`fs.rmSync(path, { recursive: true, force: true })` or
+`fs.promises.rm(path, { recursive: true, force: true })` instead.
 
 ### DEP0148: Folder mappings in `"exports"` (trailing `"/"`)
 <!-- YAML

doc/api/fs.md

@@ -3589,6 +3589,10 @@ Synchronous rename(2). Returns `undefined`.
 <!-- YAML
 added: v0.0.2
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29168
+    description: The `recursive` option is deprecated, using it triggers a
+                 deprecation warning.
   - version:
      - v13.3.0
      - v12.16.0
@@ -3625,7 +3629,7 @@ changes:
     option is not `true`. **Default:** `0`.
   * `recursive` {boolean} If `true`, perform a recursive directory removal. In
     recursive mode, errors are not reported if `path` does not exist, and
-    operations are retried on failure. **Default:** `false`.
+    operations are retried on failure. **Default:** `false`. **Deprecated**.
   * `retryDelay` {integer} The amount of time in milliseconds to wait between
     retries. This option is ignored if the `recursive` option is not `true`.
     **Default:** `100`.
@@ -3640,14 +3644,17 @@ Windows and an `ENOTDIR` error on POSIX.
 
 Setting `recursive` to `true` results in behavior similar to the Unix command
 `rm -rf`: an error will not be raised for paths that do not exist, and paths
-that represent files will be deleted. The permissive behavior of the
-`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in
-the future.
+that represent files will be deleted. The `recursive` option is deprecated,
+`ENOTDIR` and `ENOENT` will be thrown in the future.
 
 ## `fs.rmdirSync(path[, options])`
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29168
+    description: The `recursive` option is deprecated, using it triggers a
+                 deprecation warning.
   - version:
      - v13.3.0
      - v12.16.0
@@ -3676,7 +3683,7 @@ changes:
     option is not `true`. **Default:** `0`.
   * `recursive` {boolean} If `true`, perform a recursive directory removal. In
     recursive mode, errors are not reported if `path` does not exist, and
-    operations are retried on failure. **Default:** `false`.
+    operations are retried on failure. **Default:** `false`. **Deprecated**.
   * `retryDelay` {integer} The amount of time in milliseconds to wait between
     retries. This option is ignored if the `recursive` option is not `true`.
     **Default:** `100`.
@@ -3688,9 +3695,8 @@ on Windows and an `ENOTDIR` error on POSIX.
 
 Setting `recursive` to `true` results in behavior similar to the Unix command
 `rm -rf`: an error will not be raised for paths that do not exist, and paths
-that represent files will be deleted. The permissive behavior of the
-`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in
-the future.
+that represent files will be deleted. The `recursive` option is deprecated,
+`ENOTDIR` and `ENOENT` will be thrown in the future.
 
 ## `fs.rm(path[, options], callback)`
 <!-- YAML
@@ -5677,6 +5683,10 @@ upon success.
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29168
+    description: The `recursive` option is deprecated, using it triggers a
+                 deprecation warning.
   - version:
      - v13.3.0
      - v12.16.0
@@ -5701,7 +5711,7 @@ changes:
     option is not `true`. **Default:** `0`.
   * `recursive` {boolean} If `true`, perform a recursive directory removal. In
     recursive mode, errors are not reported if `path` does not exist, and
-    operations are retried on failure. **Default:** `false`.
+    operations are retried on failure. **Default:** `false`. **Deprecated**.
   * `retryDelay` {integer} The amount of time in milliseconds to wait between
     retries. This option is ignored if the `recursive` option is not `true`.
     **Default:** `100`.
@@ -5716,9 +5726,8 @@ error on POSIX.
 
 Setting `recursive` to `true` results in behavior similar to the Unix command
 `rm -rf`: an error will not be raised for paths that do not exist, and paths
-that represent files will be deleted. The permissive behavior of the
-`recursive` option is deprecated, `ENOTDIR` and `ENOENT` will be thrown in
-the future.
+that represent files will be deleted. The `recursive` option is deprecated,
+`ENOTDIR` and `ENOENT` will be thrown in the future.
 
 ### `fsPromises.rm(path[, options])`
 <!-- YAML

lib/internal/fs/promises.js

@@ -41,7 +41,10 @@ const {
   ERR_INVALID_ARG_VALUE,
   ERR_METHOD_NOT_IMPLEMENTED,
 } = codes;
-const { isArrayBufferView } = require('internal/util/types');
+const {
+  isArrayBufferView,
+  emitRecursiveRmdirWarning,
+} = require('internal/util/types');
 const { rimrafPromises } = require('internal/fs/rimraf');
 const {
   copyObject,
@@ -488,6 +491,7 @@ async function rmdir(path, options) {
   options = validateRmdirOptions(options);
 
   if (options.recursive) {
+    emitRecursiveRmdirWarning();
     return rimrafPromises(path, options);
   }
 

lib/internal/fs/utils.js

@@ -704,18 +704,11 @@ const validateRmOptions = hideStackFrames((path, options, warn, callback) => {
   lazyLoadFs().stat(path, (err, stats) => {
     if (err) {
       if (options.force && err.code === 'ENOENT') {
-        if (warn) {
-          emitPermissiveRmdirWarning();
-        }
         return callback(null, options);
       }
       return callback(err, options);
     }
 
-    if (warn && !stats.isDirectory()) {
-      emitPermissiveRmdirWarning();
-    }
-
     if (stats.isDirectory() && !options.recursive) {
       return callback(new ERR_FS_EISDIR({
         code: 'EISDIR',
@@ -737,10 +730,6 @@ const validateRmOptionsSync = hideStackFrames((path, options, warn) => {
     const isDirectory = lazyLoadFs()
       .statSync(path, { throwIfNoEntry: !options.force })?.isDirectory();
 
-    if (warn && !isDirectory) {
-      emitPermissiveRmdirWarning();
-    }
-
     if (isDirectory && !options.recursive) {
       throw new ERR_FS_EISDIR({
         code: 'EISDIR',
@@ -755,18 +744,16 @@ const validateRmOptionsSync = hideStackFrames((path, options, warn) => {
   return options;
 });
 
-let permissiveRmdirWarned = false;
-
-function emitPermissiveRmdirWarning() {
-  if (!permissiveRmdirWarned) {
+let recursiveRmdirWarned = process.noDeprecation;
+function emitRecursiveRmdirWarning() {
+  if (!recursiveRmdirWarned) {
     process.emitWarning(
       'In future versions of Node.js, fs.rmdir(path, { recursive: true }) ' +
-      'will throw if path does not exist or is a file. Use fs.rm(path, ' +
-      '{ recursive: true, force: true }) instead',
+      'will be removed. Use fs.rm(path, { recursive: true }) instead',
       'DeprecationWarning',
       'DEP0147'
     );
-    permissiveRmdirWarned = true;
+    recursiveRmdirWarned = true;
   }
 }
 
@@ -782,6 +769,10 @@ const validateRmdirOptions = hideStackFrames(
     validateInt32(options.retryDelay, 'options.retryDelay', 0);
     validateUint32(options.maxRetries, 'options.maxRetries');
 
+    if (options.recursive) {
+      emitRecursiveRmdirWarning();
+    }
+
     return options;
   });
 
@@ -851,6 +842,7 @@ module.exports = {
   BigIntStats,  // for testing
   copyObject,
   Dirent,
+  emitRecursiveRmdirWarning,
   getDirent,
   getDirents,
   getOptions,

test/parallel/test-fs-rmdir-recursive.js

@@ -7,6 +7,13 @@ const fs = require('fs');
 const path = require('path');
 const { validateRmdirOptions } = require('internal/fs/utils');
 
+common.expectWarning(
+  'In future versions of Node.js, fs.rmdir(path, { recursive: true }) ' +
+      'will be removed. Use fs.rm(path, { recursive: true }) instead',
+  'DeprecationWarning',
+  'DEP0147'
+);
+
 tmpdir.refresh();
 
 let count = 0;