feat(util-extend-to-object-assign): introduce (#280)

Co-authored-by: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>

Author: AugustinMauroy

package-lock.json

@@ -0,0 +1,15 @@
+# `util._extend` DEP0060
+
+This recipe transforms the usage of deprecated `util._extend()` to use `Object.assign()`.
+
+See [DEP0060](https://nodejs.org/api/deprecations.html#DEP0060).
+
+## Example
+
+```diff
+- const util = require("node:util");
+  const target = { a: 1 };
+  const source = { b: 2 };
+- const result = util._extend(target, source);
++ const result = Object.assign(target, source);
+```

recipes/util-extend-to-object-assign/README.md

@@ -0,0 +1,21 @@
+schema_version: "1.0"
+name: "@nodejs/util-extend-to-object-assign"
+version: 1.0.0
+description: "Handle DEP0060 by replacing `util._extend()` with `Object.assign()`."
+author: GitHub Copilot
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+
+registry:
+  access: public
+  visibility: public

recipes/util-extend-to-object-assign/codemod.yaml

@@ -0,0 +1,24 @@
+{
+  "name": "@nodejs/util-extend-to-object-assign",
+  "version": "1.0.0",
+  "description": "Handle DEP0060 by replacing `util._extend()` with `Object.assign()`.",
+  "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/util-extend-to-object-assign",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "GitHub Copilot",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/util-extend-to-object-assign/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.9"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*"
+  }
+}

recipes/util-extend-to-object-assign/package.json

@@ -0,0 +1,133 @@
+import {
+	getNodeImportStatements,
+	getNodeImportCalls,
+	getDefaultImportIdentifier,
+} from '@nodejs/codemod-utils/ast-grep/import-statement';
+import {
+	getNodeRequireCalls,
+	getRequireNamespaceIdentifier,
+} from '@nodejs/codemod-utils/ast-grep/require-call';
+import { removeBinding } from '@nodejs/codemod-utils/ast-grep/remove-binding';
+import { resolveBindingPath } from '@nodejs/codemod-utils/ast-grep/resolve-binding-path';
+import { removeLines } from '@nodejs/codemod-utils/ast-grep/remove-lines';
+import type { SgRoot, Edit, Range } from '@codemod.com/jssg-types/main';
+import type JS from '@codemod.com/jssg-types/langs/javascript';
+
+const method = '_extend';
+
+/**
+ * Transform function that converts deprecated util._extend() calls
+ * to Object.assign().
+ *
+ * Handles:
+ * 1. util._extend(target, source) → Object.assign(target, source)
+ * 2. const { _extend } = require('util'); _extend(target, source) → Object.assign(target, source)
+ * 3. import { _extend } from 'node:util'; _extend(target, source) → Object.assign(target, source)
+ * 4. Aliased imports: const { _extend: extend } = require('util'); extend(target, source) → Object.assign(target, source)
+ *
+ * Also cleans up unused imports and requires.
+ */
+export default function transform(root: SgRoot<JS>): string | null {
+	const rootNode = root.root();
+	const edits: Edit[] = [];
+	const linesToRemove: Range[] = [];
+	const editRanges: Range[] = [];
+
+	const importOrRequireNodes = [
+		...getNodeRequireCalls(root, 'util'),
+		...getNodeImportStatements(root, 'util'),
+		...getNodeImportCalls(root, 'util'),
+	];
+
+	// If no util imports/requires, nothing to do
+	if (!importOrRequireNodes.length) return null;
+
+	// 1. Resolve local bindings for util._extend and replace invocations
+	const localRefs = new Set<string>();
+
+	for (const node of importOrRequireNodes) {
+		const resolved = resolveBindingPath(node, `$.${method}`);
+		if (resolved) localRefs.add(resolved);
+
+		// Workaround for mixed imports (e.g. import util, { _extend } from 'util')
+		if (node.kind() === 'import_statement') {
+			const namedSpecifiers = node.findAll({
+				rule: {
+					kind: 'import_specifier',
+				},
+			});
+
+			for (const specifier of namedSpecifiers) {
+				const nameNode = specifier.field('name');
+				const aliasNode = specifier.field('alias');
+
+				if (nameNode && nameNode.text() === method) {
+					const localName = aliasNode ? aliasNode.text() : nameNode.text();
+					localRefs.add(localName);
+				}
+			}
+		}
+	}
+
+	for (const ref of localRefs) {
+		const calls = rootNode.findAll({
+			rule: {
+				kind: 'call_expression',
+				pattern: `${ref}($$$ARGS)`,
+			},
+		});
+
+		for (const call of calls) {
+			const args = call.find({
+				rule: { kind: 'arguments' },
+			});
+
+			edits.push(call.replace(`Object.assign${args.text()}`));
+			editRanges.push(call.range());
+		}
+	}
+
+	// if no edits were made, don't try to clean up imports
+	if (!edits.length) return null;
+
+	// 2. Cleanup imports
+	for (const node of importOrRequireNodes) {
+		let nsBinding = '';
+
+		const reqNs = getRequireNamespaceIdentifier(node);
+		const defaultImport = getDefaultImportIdentifier(node);
+		const namespaceImport = node.find({
+			rule: {
+				kind: 'identifier',
+				inside: {
+					kind: 'namespace_import',
+				},
+			},
+		});
+
+		if (reqNs) {
+			nsBinding = reqNs.text();
+		} else if (defaultImport) {
+			nsBinding = defaultImport.text();
+		} else if (namespaceImport) {
+			nsBinding = namespaceImport.text();
+		}
+
+		// Check if namespace binding is still used
+		if (nsBinding) {
+			const change = removeBinding(node, nsBinding, {
+				usageCheck: { ignoredRanges: editRanges },
+				root: rootNode,
+			});
+			if (change?.lineToRemove) linesToRemove.push(change.lineToRemove);
+		}
+
+		const change = removeBinding(node, method);
+		if (change?.edit) edits.push(change.edit);
+		if (change?.lineToRemove) linesToRemove.push(change.lineToRemove);
+	}
+
+	const sourceCode = rootNode.commitEdits(edits);
+
+	return removeLines(sourceCode, linesToRemove);
+}

recipes/util-extend-to-object-assign/src/workflow.ts

@@ -0,0 +1 @@
+Object.assign({}, {});

recipes/util-extend-to-object-assign/tests/expected/alias.js

@@ -0,0 +1 @@
+Object.assign({}, {});

recipes/util-extend-to-object-assign/tests/expected/destructuring.js

@@ -0,0 +1 @@
+Object.assign({}, {});

recipes/util-extend-to-object-assign/tests/expected/dynamic.js

@@ -0,0 +1,18 @@
+import * as util1 from 'util';
+Object.assign({}, {});
+util1.types.isDate(new Date());
+
+import util2 from 'node:util';
+Object.assign({}, {});
+console.log(util2.inspect({}));
+
+const util3 = require('util');
+Object.assign({}, {});
+registerPlugin(util3);
+
+import util4 from 'util';
+Object.assign({}, {});
+util4.promisify(() => { });
+
+Object.assign({}, {});
+

recipes/util-extend-to-object-assign/tests/expected/edge_cases.js

@@ -0,0 +1 @@
+Object.assign({}, {});