feat(types-is-native-error): introduce (#157)

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

Author: 3 people

package-lock.json

@@ -0,0 +1,25 @@
+# `types.isNativeError` DEP0197
+
+This recipe transforms the usage of `types.isNativeError` to use the `Error.isError`.
+
+See [DEP0197](https://nodejs.org/api/deprecations.html#DEP0197).
+
+## Example
+
+**Before:**
+
+```js
+import { types } from "node:util";
+
+if (types.isNativeError(err)) {
+	// handle the error
+}
+```
+
+**After:**
+
+```js
+if (Error.isError(err)) {
+	// handle the error
+}
+```

recipes/types-is-native-error/README.md

@@ -0,0 +1,21 @@
+schema_version: "1.0"
+name: "@nodejs/types-is-native-error"
+version: 1.0.0
+description: Handle DEP0197 via transforming `types.isNativeError` to `Error.isError`
+author: Bruno Rodrigues
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+
+registry:
+  access: public
+  visibility: public

recipes/types-is-native-error/codemod.yaml

@@ -0,0 +1,23 @@
+{
+  "name": "@nodejs/types-is-native-error",
+  "version": "1.0.0",
+  "description": "Handle DEP0197 via transforming `types.isNativeError` to `Error.isError`",
+  "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/rmdirs",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "Bruno Rodrigues",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/types-is-native-error/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.3"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*"
+  }
+}

recipes/types-is-native-error/package.json

@@ -0,0 +1,134 @@
+import type { Edit, Range, SgNode, SgRoot } from "@codemod.com/jssg-types/main";
+import { getNodeRequireCalls } from "@nodejs/codemod-utils/ast-grep/require-call";
+import { getNodeImportStatements } from "@nodejs/codemod-utils/ast-grep/import-statement";
+import { resolveBindingPath } from "@nodejs/codemod-utils/ast-grep/resolve-binding-path";
+import { removeLines } from "@nodejs/codemod-utils/ast-grep/remove-lines";
+import { removeBinding } from "@nodejs/codemod-utils/ast-grep/remove-binding";
+
+type Binding = {
+	path: string;
+	lastPropertyAccess?: string;
+	propertyAccess?: string;
+	depth: number;
+	node: SgNode;
+};
+
+/**
+ * Extracts property access information from a dot-notation path string.
+ *
+ * @param path - A dot-notation string representing a property path (e.g., "object.property.subProperty")
+ * @returns An object containing:
+ *   - `path`: The original path string
+ *   - `lastPropertyAccess`: The last segment of the path (e.g., "subProperty" from "object.property.subProperty")
+ *   - `propertyAccess`: The path without the last segment (e.g., "object.property" from "object.property.subProperty")
+ *   - `depth`: The number of segments in the path
+ *
+ * @example
+ * ```typescript
+ * createPropBinding("foo.bar.baz");
+ * // Returns: { path: "foo.bar.baz", propertyAccess: "foo.bar", lastPropertyAccess: "baz", depth: 3 }
+ *
+ * createPropBinding("foo");
+ * // Returns: { path: "foo", propertyAccess: "", lastPropertyAccess: "foo", depth: 1 }
+ * ```
+ */
+function createPropBinding(
+	path: string,
+): Pick<Binding, "path" | "lastPropertyAccess" | "propertyAccess" | "depth"> {
+	const pathArr = path.split(".");
+
+	if (!pathArr) {
+		return {
+			path,
+			depth: 1,
+		};
+	}
+
+	const lastPropertyAccess = pathArr.at(-1);
+	const propertyAccess = pathArr.slice(0, -1).join(".");
+
+	return {
+		path,
+		propertyAccess,
+		lastPropertyAccess,
+		depth: pathArr.length,
+	};
+}
+
+/**
+ * Transforms `util.types.isNativeError` usage to `Error.isError`.
+ *
+ * This transformation handles various import/require patterns and usage scenarios:
+ *
+ * 1. Identifies all require/import statements from 'node:util' or 'util' module that
+ *    include access to `types.isNativeError`
+ *
+ * 2. Replaces all matching code references:
+ *    - `util.types.isNativeError(...)` → `Error.isError(...)`
+ *    - `types.isNativeError(...)` → `Error.isError(...)`
+ *    - `isNativeError(...)` → `Error.isError(...)`
+ *
+ * 3. Removes unused bindings when all references to the imported/required
+ *    isNativeError have been replaced
+ *
+ */
+export default function transform(root: SgRoot): string | null {
+	const rootNode = root.root();
+	const bindings: Binding[] = [];
+	const edits: Edit[] = [];
+	const linesToRemove: Range[] = [];
+
+	const nodeRequires = getNodeRequireCalls(root, "util");
+	const nodeImports = getNodeImportStatements(root, "util");
+	const path = "$.types.isNativeError";
+
+	for (const stmt of [...nodeRequires, ...nodeImports]) {
+		const bindToReplace = resolveBindingPath(stmt, path);
+
+		if (!bindToReplace) {
+			continue;
+		}
+
+		bindings.push({
+			...createPropBinding(bindToReplace),
+			node: stmt,
+		});
+	}
+
+	for (const binding of bindings) {
+		const nodes = rootNode.findAll({
+			rule: {
+				pattern: `${binding.propertyAccess || binding.path}${binding.depth > 1 ? ".$$$FN" : ""}`,
+			},
+		});
+
+		const nodesToEdit = rootNode.findAll({
+			rule: {
+				pattern: binding.path,
+			},
+		});
+
+		for (const node of nodesToEdit) {
+			edits.push(node.replace("Error.isError"));
+		}
+
+		if (nodes.length === nodesToEdit.length) {
+			const bindToRemove = binding.path.includes(".")
+				? binding.path.split(".").at(0)!
+				: binding.path;
+
+			const result = removeBinding(binding.node, bindToRemove);
+
+			if (result?.edit) {
+				edits.push(result.edit);
+			}
+
+			if (result?.lineToRemove) {
+				linesToRemove.push(result.lineToRemove);
+			}
+		}
+	}
+
+	const sourceCode = rootNode.commitEdits(edits);
+	return removeLines(sourceCode, linesToRemove);
+}

recipes/types-is-native-error/src/workflow.ts

@@ -0,0 +1,10 @@
+const {
+	types: { isMap },
+} = require("util");
+
+if (Error.isError(err)) {
+	// handle the error
+}
+
+if (isMap([])) {
+}

recipes/types-is-native-error/tests/expected/complex-named-require-scenario.cjs

@@ -0,0 +1,4 @@
+
+if (Error.isError(err)) {
+	// handle the error
+}

recipes/types-is-native-error/tests/expected/named-import.js

@@ -0,0 +1,4 @@
+
+if (Error.isError(err)) {
+	// handle the error
+}

recipes/types-is-native-error/tests/expected/renamed-import.js

@@ -0,0 +1,8 @@
+const { types: test } = require("util");
+
+if (Error.isError(err)) {
+	// handle the error
+}
+
+if (test.isMap([])) {
+}

recipes/types-is-native-error/tests/expected/renamed-types-with-multiple-usages.cjs

@@ -0,0 +1,13 @@
+const err = new Error();
+
+if (Error.isError(err)) {
+	// handle the error
+}
+
+if (Error.isError(err)) {
+	// handle the error
+}
+
+if (Error.isError(err)) {
+	// handle the error
+}