feat(process-main-module): introduce (#136)

Co-authored-by: Augustin Mauroy <[email protected]>
Co-authored-by: Aviv Keller <[email protected]>
Co-authored-by: Jacob Smith <[email protected]>

Author: 4 people

package-lock.json

@@ -0,0 +1,27 @@
+# `process.mainModule` DEP0138
+
+This recipe transforms the usage of `process.mainModule` to use `require.main` in CommonJS modules.
+
+See [DEP0138](https://nodejs.org/api/deprecations.html#DEP0138).
+
+## Example
+
+**Before:**
+
+```js
+if (process.mainModule === "mod.js") {
+	// cli thing
+} else {
+	// module thing
+}
+```
+
+**After:**
+
+```js
+if (require.main === "mod.js") {
+	// cli thing
+} else {
+	// module thing
+}
+```

recipes/process-main-module/README.md

@@ -0,0 +1,21 @@
+schema_version: "1.0"
+name: @nodejs/process-main-module
+version: 1.0.0
+description: Handle DEP0138 via transforming `process.mainModule` to `require.main`.
+author: Bruno Rodrigues
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+
+registry:
+  access: public
+  visibility: public

recipes/process-main-module/codemod.yaml

@@ -0,0 +1,25 @@
+{
+  "name": "@nodejs/process-main-module",
+  "version": "1.0.0",
+  "description": "Handle DEP0138 via transforming `process.mainModule` to `require.main`.",
+  "type": "module",
+  "scripts": {
+    "test": "npx codemod@next jssg test -l typescript ./src/workflow.ts ./"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodejs/userland-migrations.git",
+    "directory": "recipes/process-main-module",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "Bruno Rodrigues",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/process-main-module/README.md",
+  "devDependencies": {
+    "@types/node": "^24.0.3",
+    "@codemod.com/jssg-types": "^1.0.3"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "0.0.0"
+  }
+}

recipes/process-main-module/package.json

@@ -0,0 +1,100 @@
+import type { Edit, SgRoot, Range } from "@codemod.com/jssg-types/main";
+import { getNodeRequireCalls } from "@nodejs/codemod-utils/ast-grep/require-call";
+import { removeLines } from "@nodejs/codemod-utils/ast-grep/remove-lines";
+
+/**
+ * Transforms `process.mainModule` usage to `require.main`. Handles direct global access
+ * with `process.mainModule` or `require("node:process")` imports, as `mainModule` is CJS-only.
+ *
+ *
+ * Handles:
+ * 1. Find all destructuring require statements from 'node:process' module that import 'mainModule'
+ *
+ * 2. Handle the destructuring import:
+ *    - If 'mainModule' is the only imported property → Remove the entire require statement
+ *    - If other properties are also imported → Remove only 'mainModule' from the destructuring
+ *
+ * 3. Replace all code references:
+ *    - Change 'mainModule' → 'require.main'
+ *    - Change 'process.mainModule' → 'require.main'
+ */
+export default function transform(root: SgRoot): string | null {
+	const rootNode = root.root();
+	const edits: Edit[] = [];
+	const linesToRemove: Range[] = [];
+	const patternsToReplace = [
+		{
+			pattern: "process.mainModule",
+		},
+	];
+
+	// @ts-ignore - ast-grep types are not fully compatible with JSSG types
+	const requireDeclarations = getNodeRequireCalls(root, "process");
+
+	const destructureDeclarations = rootNode.findAll({
+		rule: {
+			kind: "lexical_declaration",
+			has: {
+				kind: "variable_declarator",
+				has: {
+					kind: "identifier",
+					regex: "process",
+				},
+			},
+		},
+	});
+
+	for (const declarationNode of [...requireDeclarations, ...destructureDeclarations]) {
+		// Step 1: Get all requires from module nodule:process that is destructuring mainModule:
+		if (declarationNode.text().includes("mainModule")) {
+			const objectPattern = declarationNode.find({
+				rule: {
+					kind: "object_pattern",
+				},
+			});
+
+			if (!objectPattern) continue;
+
+			// Step2: Handle the destructuring import:
+			const declarations = declarationNode.findAll({
+				rule: {
+					kind: "shorthand_property_identifier_pattern",
+				},
+			});
+
+			if (declarations.length !== 0) {
+				patternsToReplace.push({
+					pattern: "mainModule",
+				});
+			}
+
+			// When 'mainModule' is the only item imported, remove to whole thing to avoid an empty import
+			if (declarations.length === 1) {
+				linesToRemove.push(declarationNode.range());
+			}
+
+			if (declarations.length > 1) {
+				const restDeclarations = declarations
+					.map((d) => d.text())
+					.filter((d) => d !== "mainModule");
+
+				edits.push(objectPattern.replace(`{ ${restDeclarations.join(", ")} }`));
+			}
+		}
+	}
+
+	// Step 3: Replace all code references:
+	const nodes = rootNode.findAll({
+		rule: {
+			any: patternsToReplace,
+		},
+	});
+
+	for (const node of nodes) {
+		edits.push(node.replace("require.main"));
+	}
+
+	let sourceCode = rootNode.commitEdits(edits);
+	sourceCode = removeLines(sourceCode, linesToRemove);
+	return sourceCode;
+}

recipes/process-main-module/src/workflow.ts

@@ -0,0 +1,4 @@
+
+if (require.main === module) {
+	console.log(require.main.filename);
+}

recipes/process-main-module/tests/expected/destucturing-process.js

@@ -0,0 +1,5 @@
+if (require.main === module) {
+	// cli thing
+} else {
+	// module thing
+}

recipes/process-main-module/tests/expected/file-1.js

@@ -0,0 +1,9 @@
+const { env, cwd } = require("node:process"); // mainModule as first
+const { env, cwd } = require("node:process"); // mainModule as last
+const { env, cwd } = require("node:process"); // mainModule at middle
+
+if (require.main === module) {
+	console.log(env, cwd);
+} else {
+	//code
+}

recipes/process-main-module/tests/expected/importing-multiple-values.js

@@ -0,0 +1,7 @@
+const { env } = require("node:process");
+
+if (require.main === module) {
+	//code
+} else {
+	//code
+}

recipes/process-main-module/tests/expected/multiple-requires.js

@@ -0,0 +1,6 @@
+
+if (require.main === module) {
+	//code
+} else {
+	//code
+}