module: add --experimental-strip-private-modules

Signed-off-by: Marco Ippolito <marcoippolito54@gmail.com>
PR-URL: #63869
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com>

Author: marco-ippolito

doc/api/cli.md

@@ -1647,6 +1647,25 @@ added:
 
 Enable the experimental [`node:stream/iter`][] module.
 
+### `--experimental-strip-private-modules`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+By default, Node.js refuses to strip types from TypeScript files inside
+folders under a `node_modules` path. This flag enables type stripping for
+such files when they belong to a package whose `package.json` contains
+`"private": true`. Files belonging to non-private packages still throw
+[`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`][].
+The limitation to private packages should never be lifted,
+as publishing packages with TypeScript sources
+is highly discouraged.
+Stripping types inside `node_modules` is intended only
+for local development.
+
 ### `--experimental-test-coverage`
 
 <!-- YAML
@@ -4287,6 +4306,7 @@ one is included in the list below.
 * `--experimental-shadow-realm`
 * `--experimental-specifier-resolution`
 * `--experimental-stream-iter`
+* `--experimental-strip-private-modules`
 * `--experimental-test-isolation`
 * `--experimental-top-level-await`
 * `--experimental-vm-modules`
@@ -4941,6 +4961,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`CRYPTO_secure_malloc_init`]: https://www.openssl.org/docs/man3.0/man3/CRYPTO_secure_malloc_init.html
 [`ERR_INVALID_TYPESCRIPT_SYNTAX`]: errors.md#err_invalid_typescript_syntax
 [`ERR_RX_MEMORY_NOT_SUPPORTED`]: errors.md#err_rx_memory_not_supported
+[`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`]: errors.md#err_unsupported_node_modules_type_stripping
 [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
 [`ERR_WEBASSEMBLY_NOT_SUPPORTED`]: errors.md#err_webassembly_not_supported
 [`NODE_OPTIONS`]: #node_optionsoptions

doc/api/packages.md

@@ -1153,6 +1153,9 @@ The following fields in `package.json` files are used in Node.js:
   limits which submodules can be loaded from within the package.
 * [`"imports"`][] - Package imports, for use by modules within the package
   itself.
+* [`"private"`][] - When `true`, marks the package as not for publication. Used
+  by [`--experimental-strip-private-modules`][] to allow type stripping for the
+  package's TypeScript files under `node_modules`.
 
 ### `"name"`
 
@@ -1348,6 +1351,33 @@ Package imports permit mapping to external packages.
 
 This field defines [subpath imports][] for the current package.
 
+### `"private"`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {boolean}
+
+```json
+{
+  "private": true
+}
+```
+
+The `"private"` field marks a package as private, signaling to package managers
+such as _npm_ that it must not be published to a public registry.
+By default, Node.js refuses to strip types from TypeScript files inside
+`node_modules`. When [`--experimental-strip-private-modules`][] is enabled,
+Node.js allows type stripping for:
+
+* files that are not inside a `node_modules` directory.
+* files inside `node_modules`, but only when the package that contains the
+  file sets `"private": true`. Only the `package.json` at each package boundary
+  is considered: the package's root directory, which is the directory directly
+  under `node_modules` (or under `node_modules/<@scope>` for scoped packages).
+  Nested `package.json` files are ignored.
+
 [CommonJS]: modules.md
 [Conditional exports]: #conditional-exports
 [ES module]: esm.md
@@ -1362,10 +1392,12 @@ This field defines [subpath imports][] for the current package.
 [`"imports"`]: #imports
 [`"main"`]: #main
 [`"name"`]: #name
+[`"private"`]: #private
 [`"type"`]: #type
 [`--conditions` / `-C` flag]: #resolving-user-conditions
 [`--experimental-addon-modules`]: cli.md#--experimental-addon-modules
 [`--experimental-package-map`]: cli.md#--experimental-package-mappath
+[`--experimental-strip-private-modules`]: cli.md#--experimental-strip-private-modules
 [`--no-addons` flag]: cli.md#--no-addons
 [`ERR_PACKAGE_MAP_EXTERNAL_FILE`]: errors.md#err_package_map_external_file
 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported

doc/api/typescript.md

@@ -222,6 +222,15 @@ To discourage package authors from publishing packages written in TypeScript,
 Node.js refuses to handle TypeScript files inside folders under a `node_modules`
 path.
 
+The [`--experimental-strip-private-modules`][] flag relaxes this restriction
+for packages whose `package.json` contains `"private": true`, such as
+workspace packages in a monorepo, which are not published to a registry.
+The limitation to private packages should never be lifted,
+as publishing packages with TypeScript sources
+is highly discouraged.
+Stripping types inside `node_modules` is intended only
+for local development.
+
 ### Paths aliases
 
 [`tsconfig` "paths"][] won't be transformed and therefore produce an error. The closest
@@ -231,6 +240,7 @@ with `#`.
 [CommonJS]: modules.md
 [ES Modules]: esm.md
 [Full TypeScript support]: #full-typescript-support
+[`--experimental-strip-private-modules`]: cli.md#--experimental-strip-private-modules
 [`--no-strip-types`]: cli.md#--no-strip-types
 [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
 [`tsconfig` "paths"]: https://www.typescriptlang.org/tsconfig/#paths

doc/node-config-schema.json

@@ -367,6 +367,10 @@
               "type": "boolean",
               "description": "experimental iterable streams API (node:stream/iter)"
             },
+            "experimental-strip-private-modules": {
+              "type": "boolean",
+              "description": "Type-stripping for TypeScript files under node_modules belonging to packages marked \"private\": true"
+            },
             "experimental-vm-modules": {
               "type": "boolean",
               "description": "experimental ES Module support in vm module"

doc/node.1

@@ -909,6 +909,18 @@ Enable experimental support for storage inspection
 .It Fl -experimental-stream-iter
 Enable the experimental \fBnode:stream/iter\fR module.
 .
+.It Fl -experimental-strip-private-modules
+By default, Node.js refuses to strip types from TypeScript files inside
+folders under a \fBnode_modules\fR path. This flag enables type stripping for
+such files when they belong to a package whose \fBpackage.json\fR contains
+\fB"private": true\fR. Files belonging to non-private packages still throw
+\fBERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING\fR.
+The limitation to private packages should never be lifted,
+as publishing packages with TypeScript sources
+is highly discouraged.
+Stripping types inside \fBnode_modules\fR is intended only
+for local development.
+.
 .It Fl -experimental-test-coverage
 When used in conjunction with the \fBnode:test\fR module, a code coverage report is
 generated as part of the test runner output. If no tests are run, a coverage
@@ -2273,6 +2285,8 @@ one is included in the list below.
 .It
 \fB--experimental-stream-iter\fR
 .It
+\fB--experimental-strip-private-modules\fR
+.It
 \fB--experimental-test-isolation\fR
 .It
 \fB--experimental-top-level-await\fR

lib/internal/modules/helpers.js

@@ -85,6 +85,8 @@ const nativeLoaderMethods = {
     modulesBinding.readPackageJSON(jsonPath, isESM, base, specifier),
   getNearestParentPackageJSON: (checkPath) =>
     modulesBinding.getNearestParentPackageJSON(checkPath),
+  getRootPackageJSON: (checkPath) =>
+    modulesBinding.getRootPackageJSON(checkPath),
   getNearestParentPackageJSONType: (checkPath) =>
     modulesBinding.getNearestParentPackageJSONType(checkPath),
   getPackageScopeConfig: (resolved) =>

lib/internal/modules/package_json_reader.js

@@ -64,6 +64,7 @@ function deserializePackageJSON(path, contents) {
     3: plainImports,
     4: plainExports,
     5: optionalFilePath,
+    6: isPrivate,
   } = contents;
 
   const pjsonPath = optionalFilePath ?? path;
@@ -73,6 +74,7 @@ function deserializePackageJSON(path, contents) {
     ...(name != null && { name }),
     ...(main != null && { main }),
     ...(type != null && { type }),
+    ...(isPrivate != null && { private: isPrivate }),
   };
 
   if (plainExports !== null) {
@@ -217,6 +219,40 @@ function getNearestParentPackageJSON(checkPath) {
   return deserializedPackageJSONCache.get(parentPackageJSONPath);
 }
 
+const moduleToRootPackageJSONCache = new SafeMap();
+
+/**
+ * This is stricter than {@link getNearestParentPackageJSON}: nested
+ * `package.json` files inside a package are ignored, and a non-private package
+ * anywhere in the `node_modules` chain (for example a publishable package that
+ * bundles a private dependency) disqualifies the path. A directory under
+ * `node_modules` with no `package.json` (such as pnpm's `.pnpm` store) is not
+ * a package and is skipped.
+ *
+ * Returns the package.json data and the path to the package.json file, or undefined.
+ * @param {string} checkPath The path to start searching from.
+ * @returns {undefined | DeserializedPackageConfig}
+ */
+function getRootPackageJSON(checkPath) {
+  const packageJSONPath = moduleToRootPackageJSONCache.get(checkPath);
+  if (packageJSONPath !== undefined) {
+    return deserializedPackageJSONCache.get(packageJSONPath);
+  }
+
+  const result = loaderMethods.getRootPackageJSON(checkPath);
+  const packageConfig = deserializePackageJSON(checkPath, result);
+
+  moduleToRootPackageJSONCache.set(checkPath, packageConfig.path);
+
+  const maybeCachedPackageConfig = deserializedPackageJSONCache.get(packageConfig.path);
+  if (maybeCachedPackageConfig !== undefined) {
+    return maybeCachedPackageConfig;
+  }
+
+  deserializedPackageJSONCache.set(packageConfig.path, packageConfig);
+  return packageConfig;
+}
+
 /**
  * Returns the package configuration for the given resolved URL.
  * @param {URL | string} resolved - The resolved URL.
@@ -412,6 +448,7 @@ function purgePackageJSONCacheForPrefix(mountPoint) {
 module.exports = {
   read,
   getNearestParentPackageJSON,
+  getRootPackageJSON,
   getPackageScopeConfig,
   getPackageType,
   getPackageJSONURL,

lib/internal/modules/typescript.js

@@ -18,6 +18,7 @@ const {
   ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING,
   ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX,
 } = require('internal/errors').codes;
+const { getOptionValue } = require('internal/options');
 const assert = require('internal/assert');
 const {
   getCompileCacheEntry,
@@ -141,6 +142,35 @@ function stripTypeScriptTypesForCoverage(code) {
 }
 
 
+/**
+ * Whether type-stripping is allowed for files under node_modules belonging
+ * to packages whose package.json contains `"private": true`.
+ * @returns {boolean}
+ */
+const isStripPrivateModulesEnabled = getLazy(
+  () => getOptionValue('--experimental-strip-private-modules'),
+);
+
+/**
+ * Checks whether a file under node_modules is owned by a private package, in
+ * which case type stripping is allowed under `--experimental-strip-private-modules`.
+ *
+ * Every package enclosing the file inside `node_modules` must be marked
+ * `"private": true`. npm refuses to publish a private package, so requiring
+ * the package root (not a nested package.json, which is published verbatim)
+ * and rejecting any non-private enclosing package (e.g. a publishable package
+ * bundling a private dependency) prevents published packages from shipping
+ * strippable TypeScript. See {@link getRootPackageJSON}.
+ * @param {string} filename The filename (path or file URL) of the source code.
+ * @returns {boolean} Whether the file belongs to a package with `"private": true`.
+ */
+function isInsidePrivatePackage(filename) {
+  const { getRootPackageJSON } = require('internal/modules/package_json_reader');
+  const { urlToFilename } = require('internal/modules/helpers');
+  const packageJSON = getRootPackageJSON(urlToFilename(filename));
+  return packageJSON?.data.private === true;
+}
+
 /**
  * Performs type-stripping to TypeScript source code internally.
  * It is used by internal loaders.
@@ -152,7 +182,10 @@ function stripTypeScriptTypesForCoverage(code) {
 function stripTypeScriptModuleTypes(source, filename, sourceURL) {
   assert(typeof source === 'string');
   if (isUnderNodeModules(filename)) {
-    throw new ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING(filename);
+    if (!isStripPrivateModulesEnabled() || !isInsidePrivatePackage(filename)) {
+      throw new ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING(filename);
+    }
+    emitExperimentalWarning('Type stripping in node_modules');
   }
   // Get a compile cache entry into the native compile cache store,
   // keyed by the filename. If the cache can already be loaded on disk,