feat(process-assert-to-node-assert): introduce

recipes/process-assert-to-assert/README.md

@@ -0,0 +1,20 @@
+# `process.assert` DEP0100
+
+This recipe transforms the usage of `process.assert` to use `assert` module.
+
+See [DEP0100](https://github.com/nodejs/userland-migrations/issues/197).
+
+## Example
+
+**Before:**
+
+```js
+process.assert(condition, "Assertion failed");
+```
+
+**After:**
+
+```js
+import assert from "node:assert";
+assert(condition, "Assertion failed");
+```

recipes/process-assert-to-assert/codemod.yaml

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

recipes/process-assert-to-assert/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@nodejs/process-assert-to-assert",
+  "version": "1.0.0",
+  "description": "Handle DEP0100 via transforming `process.assert` to `assert`.",
+  "type": "module",
+  "scripts": {
+    "test": "npx codemod jssg test -l typescript --ignore-whitespace ./src/workflow.ts ./",
+    "test:u": "npx codemod jssg test -l typescript -u ./src/workflow.ts ./"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodejs/userland-migrations.git",
+    "directory": "recipes/process-assert-to-assert",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "matheusmorett2",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/process-assert-to-assert/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.3"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*"
+  }
+}

recipes/process-assert-to-assert/src/workflow.ts

@@ -0,0 +1,121 @@
+import type { Edit, Range, Rule, 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 { removeBinding } from "@nodejs/codemod-utils/ast-grep/remove-binding";
+import { removeLines } from "@nodejs/codemod-utils/ast-grep/remove-lines";
+
+/**
+ * Transforms deprecated `process.assert` usage to the standard `assert` module.
+ * 
+ * Transformations:
+ * 1. Replaces all `process.assert` references with `assert`
+ * 2. Adds the necessary import/require statement if not already present:
+ *    - For ESM or files without require calls: adds `import assert from "node:assert"`
+ *    - For CommonJS (.cjs files or files using require): adds `const assert = require("node:assert")`
+ * 
+ * Examples:
+ * 
+ * Before:
+ * ```js
+ * process.assert(value);
+ * process.assert.strictEqual(a, b);
+ * ```
+ * 
+ * After:
+ * ```js
+ * import assert from "node:assert";
+ * assert(value);
+ * assert.strictEqual(a, b);
+ * ```
+ */
+export default function transform(root: SgRoot): string | null {
+	const rootNode = root.root();
+	const edits: Edit[] = [];
+	const linesToRemove: Range[] = [];
+	const replaceRules: Array<
+		{
+			importNode?: SgNode
+			binding?: string
+			rule: Rule
+		}
+	> = [{
+		rule: {
+			kind: 'member_expression',
+			pattern: "process.assert",
+		}
+	}];
+
+	const requireProcess = getNodeRequireCalls(root, "process");
+	const importProcess = getNodeImportStatements(root, "process");
+
+	const allProcessImports = [...requireProcess, ...importProcess]
+
+	for (const processImport of allProcessImports) {
+		const binding = resolveBindingPath(processImport, "$.assert");
+		replaceRules.push(
+			{
+				importNode: processImport,
+				binding,
+				rule: {
+					kind: "identifier",
+					regex: binding,
+					inside: {
+						kind: 'call_expression',
+					}
+				}
+			}
+		)
+	}
+
+	for (const replaceRule of replaceRules) {
+		const nodes = rootNode.findAll({
+			rule: replaceRule.rule
+		})
+
+		for (const node of nodes) {
+			if (replaceRule.importNode) {
+				const removeBind = removeBinding(replaceRule.importNode, replaceRule.binding)
+
+				if (removeBind.edit) {
+					edits.push(removeBind.edit);
+				}
+
+				if (removeBind.lineToRemove) {
+					linesToRemove.push(removeBind.lineToRemove)
+				}
+			}
+
+			edits.push(node.replace("assert"))
+		}
+	}
+
+	let sourceCode = rootNode.commitEdits(edits);
+	sourceCode = removeLines(sourceCode, linesToRemove);
+
+	const alreadyRequiringAssert = getNodeRequireCalls(root, "assert");
+	const alreadyImportingAssert = getNodeImportStatements(root, "assert");
+
+	if (!alreadyRequiringAssert.length && !alreadyImportingAssert.length) {
+		const usingRequire = rootNode.find({
+			rule: {
+				kind: 'call_expression',
+				has: {
+					kind: 'identifier',
+					field: 'function',
+					regex: 'require'
+				}
+			}
+		})
+
+		const isCommonJs = root.filename().includes('.cjs')
+
+		if (Boolean(usingRequire) || isCommonJs) {
+			return `const assert = require("node:assert");\n${sourceCode}`
+		}
+
+		return `import assert from "node:assert";\n${sourceCode}`
+	}
+
+	return sourceCode
+}

recipes/process-assert-to-assert/tests/expected/inside-a-function.js

@@ -0,0 +1,5 @@
+import assert from "node:assert";
+function validateInput(input) {
+  assert(typeof input === "string", "Input must be string");
+  return input.trim();
+}

recipes/process-assert-to-assert/tests/expected/mixed-assert-usages.js

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+assert(config.port, "Port must be configured");
+assert(config.port, "Port must be configured");

recipes/process-assert-to-assert/tests/expected/simple-usage.js

@@ -0,0 +1,2 @@
+import assert from "node:assert";
+assert(condition, "Assertion failed");

recipes/process-assert-to-assert/tests/expected/using-common-js.cjs

@@ -0,0 +1,2 @@
+const assert = require("node:assert");
+assert(config.port, "Port must be configured");

recipes/process-assert-to-assert/tests/expected/using-process-import.js

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+import { env } from "process";
+assert(condition, "Assertion valid");

recipes/process-assert-to-assert/tests/expected/using-process-require.js

@@ -0,0 +1,3 @@
+const assert = require("node:assert");
+const { env } = require("process");
+assert(condition, "Assertion valid");

recipes/process-assert-to-assert/tests/expected/using-require.js

@@ -0,0 +1,3 @@
+const assert = require("node:assert");
+const util = require("node:util");
+assert(config.port, "Port must be configured");

recipes/process-assert-to-assert/tests/input/inside-a-function.js

@@ -0,0 +1,4 @@
+function validateInput(input) {
+  process.assert(typeof input === "string", "Input must be string");
+  return input.trim();
+}

recipes/process-assert-to-assert/tests/input/mixed-assert-usages.js

@@ -0,0 +1,4 @@
+import assert from "node:assert";
+
+process.assert(config.port, "Port must be configured");
+assert(config.port, "Port must be configured");

recipes/process-assert-to-assert/tests/input/simple-usage.js

@@ -0,0 +1 @@
+process.assert(condition, "Assertion failed");

recipes/process-assert-to-assert/tests/input/using-common-js.cjs

@@ -0,0 +1 @@
+process.assert(config.port, "Port must be configured");

recipes/process-assert-to-assert/tests/input/using-process-import.js

@@ -0,0 +1,2 @@
+import { assert as nodeAssert, env } from "process";
+nodeAssert(condition, "Assertion valid");

recipes/process-assert-to-assert/tests/input/using-process-require.js

@@ -0,0 +1,2 @@
+const { assert: nodeAssert, env } = require("process");
+nodeAssert(condition, "Assertion valid");

recipes/process-assert-to-assert/tests/input/using-require.js

@@ -0,0 +1,2 @@
+const util = require("node:util");
+process.assert(config.port, "Port must be configured");

recipes/process-assert-to-assert/workflow.yaml

@@ -0,0 +1,25 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/codemod-com/codemod/refs/heads/main/schemas/workflow.json
+
+version: "1"
+
+nodes:
+  - id: apply-transforms
+    name: Apply AST Transformations
+    type: automatic
+    steps:
+      - name: Handle DEP0100 via transforming `process.assert` to `assert`.
+        js-ast-grep:
+          js_file: src/workflow.ts
+          base_path: .
+          include:
+            - "**/*.cjs"
+            - "**/*.js"
+            - "**/*.jsx"
+            - "**/*.mjs"
+            - "**/*.cts"
+            - "**/*.mts"
+            - "**/*.ts"
+            - "**/*.tsx"
+          exclude:
+            - "**/node_modules/**"
+          language: typescript

utils/src/ast-grep/remove-binding.test.ts

@@ -29,6 +29,29 @@ describe("remove-binding", () => {
 		});
 	});
 
+	it("should not remove non-related named requires", () => {
+		const code = dedent`
+			const { assert: nodeAssert, env } = require("process");
+		`;
+
+		const rootNode = astGrep.parse(astGrep.Lang.JavaScript, code);
+		const node = rootNode.root();
+
+		const requireStatement = node.find({
+			rule: {
+				kind: "lexical_declaration",
+			},
+		});
+
+		const change = removeBinding(requireStatement!, "nodeAssert");
+
+		const sourceCode = node.commitEdits([change?.edit!]);
+		assert.strictEqual(sourceCode, `const { env } = require("process");`);
+
+		assert.notEqual(change, null);
+		assert.strictEqual(change?.lineToRemove, undefined);
+	})
+
 	it("should return undefined when the binding does not match the imported name", () => {
 		const code = dedent`
 			const util = require('node:util');

utils/src/ast-grep/remove-binding.ts

@@ -184,7 +184,14 @@ function handleNamedRequireBindings(
 
 	const declarations = node.findAll({
 		rule: {
-			kind: "shorthand_property_identifier_pattern",
+			any: [
+				{
+					kind: "pair_pattern",
+				},
+				{
+					kind: "shorthand_property_identifier_pattern",
+				},
+			]
 		},
 	});
 
@@ -195,7 +202,18 @@ function handleNamedRequireBindings(
 	}
 
 	if (declarations.length > 1) {
-		const restDeclarations = declarations.map((d) => d.text()).filter((d) => d !== binding);
+		const restDeclarations = declarations.map((d) => {
+			if (d.kind() === 'pair_pattern') {
+				const alias = d.find({
+					rule: {
+						kind: 'identifier',
+					}
+				})
+
+				return alias.text()
+			}
+			return d.text()
+		}).filter((d) => d !== binding);
 
 		return {
 			edit: objectPattern.replace(`{ ${restDeclarations.join(", ")} }`),