modules: runtime deprecate module.parent

Author: aduh95

doc/api/deprecations.md

@@ -2612,14 +2612,17 @@ no longer required due to simplification of the implementation.
 ### DEP0144: `module.parent`
 <!-- YAML
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/33534
+    description: Runtime deprecation.
   - version:
     - v14.6.0
     - v12.19.0
     pr-url: https://github.com/nodejs/node/pull/32217
     description: Documentation-only deprecation.
 -->
 
-Type: Documentation-only (supports [`--pending-deprecation`][])
+Type: Runtime (supports [`--pending-deprecation`][])
 
 A CommonJS module can access the first module that required it using
 `module.parent`. This feature is deprecated because it does not work
@@ -2643,6 +2646,9 @@ const moduleParents = Object.values(require.cache)
   .filter((m) => m.children.includes(module));
 ```
 
+Without `--pending-deprecation`, runtime warnings occur only when this property
+is accessed from a module that have a nullish value for their `module.parent`.
+
 ### DEP0145: `socket.bufferSize`
 <!-- YAML
 changes:

doc/api/modules.md

@@ -917,10 +917,10 @@ deprecated:
 > Stability: 0 - Deprecated: Please use [`require.main`][] and
 > [`module.children`][] instead.
 
-* {module | null | undefined}
+* {module | null | UnknownModule}
 
 The module that first required this one, or `null` if the current module is the
-entry point of the current process, or `undefined` if the module was loaded by
+entry point of the current process, or `UnknownModule` if the module was loaded by
 something that is not a CommonJS module (E.G.: REPL or `import`).
 
 ### `module.path`

lib/internal/modules/cjs/loader.js

@@ -241,26 +241,37 @@ ObjectDefineProperty(Module.prototype, 'isPreloading', isPreloadingDesc);
 ObjectDefineProperty(NativeModule.prototype, 'isPreloading', isPreloadingDesc);
 
 function getModuleParent() {
-  return moduleParentCache.get(this);
+  const parent = moduleParentCache.get(this);
+  if (!process.noDeprecation && !getModuleParent.warned &&
+      (parent == null || pendingDeprecation)) {
+    process.emitWarning(
+      'module.parent is deprecated due to accuracy issues. Please use ' +
+        'require.main to find program entry point instead.',
+      'DeprecationWarning',
+      'DEP0144'
+    );
+    getModuleParent.warned = true;
+  }
+  if (parent === undefined) {
+    const parent = new (class UnknownModule {})();
+    moduleParentCache.set(this, parent);
+    return parent;
+  }
+  return parent;
 }
 
 function setModuleParent(value) {
   moduleParentCache.set(this, value);
 }
 
 ObjectDefineProperty(Module.prototype, 'parent', {
-  get: pendingDeprecation ? deprecate(
-    getModuleParent,
-    'module.parent is deprecated due to accuracy issues. Please use ' +
-      'require.main to find program entry point instead.',
-    'DEP0144'
-  ) : getModuleParent,
-  set: pendingDeprecation ? deprecate(
+  get: getModuleParent,
+  set: deprecate(
     setModuleParent,
     'module.parent is deprecated due to accuracy issues. Please use ' +
       'require.main to find program entry point instead.',
     'DEP0144'
-  ) : setModuleParent,
+  ),
 });
 
 let debug = require('internal/util/debuglog').debuglog('module', (fn) => {

test/fixtures/cjs-module-parent.js

@@ -0,0 +1,5 @@
+'use strict';
+const assert = require('assert');
+
+// Accessing module.parent should not be falsy.
+assert.ok(module.parent)

test/parallel/test-module-parent-deprecation-no-warning-for-cjs-users.js

@@ -0,0 +1,7 @@
+'use strict';
+
+require('../common');
+const fixtures = require('../common/fixtures');
+
+// Accessing module.parent from a child module should not raise a warning.
+require(fixtures.path('cjs-module-parent.js'));

test/parallel/test-module-parent-deprecation-warning-for-esm-users.mjs

@@ -0,0 +1,7 @@
+import { mustCall } from '../common/index.mjs';
+import fixtures from '../common/fixtures.js';
+
+// Accessing module.parent from a child module should raise a deprecation
+// warning when imported from ESM.
+import(fixtures.path('cjs-module-parent.js'))
+    .then(mustCall());

test/parallel/test-module-parent-deprecation.js

@@ -1,6 +1,5 @@
-// Flags: --pending-deprecation
-
 'use strict';
+
 const common = require('../common');
 const assert = require('assert');
 

test/parallel/test-module-parent-pending-deprecation.js

@@ -0,0 +1,15 @@
+// Flags: --pending-deprecation
+
+'use strict';
+
+const common = require('../common');
+const fixtures = require('../common/fixtures');
+
+common.expectWarning(
+  'DeprecationWarning',
+  'module.parent is deprecated due to accuracy issues. Please use ' +
+      'require.main to find program entry point instead.',
+  'DEP0144'
+);
+
+require(fixtures.path('cjs-module-parent.js'));