feat: Add codemod for DEP0185 - Instantiating node:repl classes without new (#242)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: AugustinMauroy <[email protected]>

Author: Copilot

package-lock.json

@@ -0,0 +1,39 @@
+# `repl` classes DEP0185
+
+This recipe provides a guide for migrating from the deprecated instantiation of `node:repl` classes without `new` to proper class instantiation in Node.js.
+
+See [DEP0185](https://nodejs.org/api/deprecations.html#DEP0185).
+
+## Example
+
+**Before:**
+
+```js
+const repl = require("node:repl");
+const { REPLServer, Recoverable } = require("node:repl");
+import { REPLServer } from "node:repl";
+const { REPLServer: REPL } = await import("node:repl");
+
+// Missing 'new' keyword
+const server1 = repl.REPLServer();
+const server2 = REPLServer({ prompt: ">>> " });
+const server3 = repl.Recoverable();
+const error = Recoverable(new SyntaxError());
+const server4 = REPL({ prompt: ">>> " });
+```
+
+**After:**
+
+```js
+const repl = require("node:repl");
+const { REPLServer, Recoverable } = require("node:repl");
+import { REPLServer } from "node:repl";
+const { REPLServer: REPL } = await import("node:repl");
+
+// With 'new' keyword
+const server1 = new repl.REPLServer();
+const server2 = new REPLServer({ prompt: ">>> " });
+const server3 = new repl.Recoverable();
+const error = new Recoverable(new SyntaxError());
+const server4 = new REPL({ prompt: ">>> " });
+```

recipes/repl-classes-with-new/README.md

@@ -0,0 +1,21 @@
+schema_version: "1.0"
+name: "@nodejs/repl-classes-with-new"
+version: 1.0.0
+description: "Handle DEP0185: Instantiating node:repl classes without new"
+author: GitHub Copilot
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+
+registry:
+  access: public
+  visibility: public

recipes/repl-classes-with-new/codemod.yaml

@@ -0,0 +1,24 @@
+{
+  "name": "@nodejs/repl-classes-with-new",
+  "version": "1.0.0",
+  "description": "Handle DEP0185: Instantiating node:repl classes without new.",
+  "type": "module",
+  "scripts": {
+    "test": "npx codemod jssg test -l typescript ./src/workflow.ts ./"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodejs/userland-migrations.git",
+    "directory": "recipes/repl-classes-with-new",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "GitHub Copilot",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/repl-classes-with-new/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.9"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*"
+  }
+}

recipes/repl-classes-with-new/package.json

@@ -0,0 +1,72 @@
+import { getNodeImportStatements, getNodeImportCalls } from '@nodejs/codemod-utils/ast-grep/import-statement';
+import { getNodeRequireCalls } from '@nodejs/codemod-utils/ast-grep/require-call';
+import { resolveBindingPath } from '@nodejs/codemod-utils/ast-grep/resolve-binding-path';
+import type { SgRoot, Edit, SgNode } from '@codemod.com/jssg-types/main';
+import type JS from "@codemod.com/jssg-types/langs/javascript";
+
+/**
+ * Classes of the repl module
+ */
+const CLASS_NAMES = [
+	'REPLServer',
+	'Recoverable',
+];
+
+/**
+ * Transform function that converts deprecated node:repl classes to use the `new` keyword
+ *
+ * Handles:
+ * 1. `repl.REPLServer()` → `new repl.REPLServer()`
+ * 2. `repl.Recoverable()` → `new repl.Recoverable()`
+ * 3. Handles both CommonJS, ESM imports, and dynamic imports
+ * 4. Preserves constructor arguments and assignments
+ */
+export default function transform(root: SgRoot<JS>): string | null {
+	const rootNode = root.root();
+	const edits: Edit[] = [];
+
+	const allStatementNodes = [
+		...getNodeImportStatements(root, 'repl'),
+		...getNodeRequireCalls(root, 'repl'),
+		...getNodeImportCalls(root, 'repl'),
+	];
+
+	// if no imports are present it means that we don't need to process the file
+	if (!allStatementNodes.length) return null;
+
+	const classes = new Set<string>(getReplClassBasePaths(allStatementNodes));
+
+	for (const cls of classes) {
+		const classesWithoutNew = rootNode.findAll({
+			rule: {
+				not: { follows: { pattern: 'new' } },
+				pattern: `${cls}($$$ARGS)`,
+			},
+		});
+
+		for (const clsWithoutNew of classesWithoutNew) {
+			edits.push(clsWithoutNew.replace(`new ${clsWithoutNew.text()}`));
+		}
+	}
+
+	if (!edits.length) return null;
+
+	return rootNode.commitEdits(edits);
+}
+
+/**
+ * Get the base path of the repl classes
+ *
+ * @param statements - The import & require statements to search for the repl classes
+ * @returns The base path of the repl classes
+ */
+function* getReplClassBasePaths(statements: SgNode<JS>[]) {
+	for (const cls of CLASS_NAMES) {
+		for (const stmt of statements) {
+			const resolvedPath = resolveBindingPath(stmt, `$.${cls}`);
+			if (resolvedPath) {
+				yield resolvedPath;
+			}
+		}
+	}
+}

recipes/repl-classes-with-new/src/workflow.ts

@@ -0,0 +1,26 @@
+const repl = require("node:repl");
+
+// Example 1: Basic REPL server instantiation
+const server = new repl.REPLServer();
+
+// Example 2: REPL server with options
+const server2 = new repl.REPLServer({
+  prompt: "custom> ",
+  input: process.stdin,
+  output: process.stdout
+});
+
+// Example 3: Recoverable class
+const error = new repl.Recoverable(new SyntaxError());
+
+// Example 4: Function parameter usage
+function createREPL(options) {
+  return new repl.REPLServer(options);
+}
+
+// Example 5: Variable assignment with configuration
+const customREPL = new repl.REPLServer({
+  prompt: "node> ",
+  useColors: true,
+  useGlobal: false
+});

recipes/repl-classes-with-new/tests/expected/file-1.js

@@ -0,0 +1,15 @@
+// Destructured import
+const { REPLServer, Recoverable } = require("node:repl");
+const server = new REPLServer({ prompt: ">>> " });
+
+// Recoverable without new
+const error = new Recoverable(new SyntaxError());
+
+// Another destructured case
+const server2 = new REPLServer();
+
+// With options
+const server3 = new REPLServer({
+  prompt: "test> ",
+  useColors: false
+});

recipes/repl-classes-with-new/tests/expected/file-2.js

@@ -0,0 +1,17 @@
+import { REPLServer } from "node:repl";
+
+// ESM import with no arguments
+const server = new REPLServer();
+
+// ESM import with options
+const server2 = new REPLServer({ 
+  prompt: ">>> ",
+  useColors: true
+});
+
+// ESM import in function
+function createCustomREPL() {
+  return new REPLServer({
+    prompt: "custom> "
+  });
+}

recipes/repl-classes-with-new/tests/expected/file-3.mjs

@@ -0,0 +1,14 @@
+// Dynamic import with await
+const { REPLServer, Recoverable } = await import("node:repl");
+
+// REPLServer without new
+const server = new REPLServer();
+
+// Recoverable without new
+const error = new Recoverable(new SyntaxError());
+
+// With options
+const server2 = new REPLServer({ 
+  prompt: ">>> ",
+  useColors: true
+});

recipes/repl-classes-with-new/tests/expected/file-4.mjs

@@ -0,0 +1,26 @@
+const repl = require("node:repl");
+
+// Example 1: Basic REPL server instantiation
+const server = repl.REPLServer();
+
+// Example 2: REPL server with options
+const server2 = repl.REPLServer({
+  prompt: "custom> ",
+  input: process.stdin,
+  output: process.stdout
+});
+
+// Example 3: Recoverable class
+const error = repl.Recoverable(new SyntaxError());
+
+// Example 4: Function parameter usage
+function createREPL(options) {
+  return repl.REPLServer(options);
+}
+
+// Example 5: Variable assignment with configuration
+const customREPL = repl.REPLServer({
+  prompt: "node> ",
+  useColors: true,
+  useGlobal: false
+});