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

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

@@ -0,0 +1,24 @@
+# `process.assert` to `node:assert` DEP0100
+
+This recipe transforms the usage of `process.assert` to use `node:assert` module.
+
+See [DEP0100](https://nodejs.org/api/deprecations.html#DEP0100).
+
+## Example
+
+**Before:**
+
+```js
+process.assert(condition, "Assertion failed");
+```
+
+**After:**
+
+```js
+import assert from "node:assert";
+assert(condition, "Assertion failed");
+```
+
+## Additional Notes
+
+This codemod use [`fs` capability](https://docs.codemod.com/jssg/security) to read the `package.json` file and determine if the project is using ES modules or CommonJS. Based on this information, it adds the appropriate import statement for the `assert` module.

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

@@ -0,0 +1,25 @@
+schema_version: "1.0"
+name: "@nodejs/process-assert-to-node-assert"
+version: 1.0.0
+description: Handle DEP0100 via transforming `process.assert` to `node:assert`.
+author: matheusmorett2
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+
+registry:
+  access: public
+  visibility: public
+
+# https://docs.codemod.com/jssg/security#enabling-capabilities
+capabilities:
+  - fs

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

@@ -0,0 +1,24 @@
+{
+  "name": "@nodejs/process-assert-to-node-assert",
+  "version": "1.0.0",
+  "description": "Handle DEP0100 via transforming `process.assert` to `node:assert`.",
+  "type": "module",
+  "scripts": {
+    "test": "npx codemod jssg test -l typescript --ignore-whitespace ./src/workflow.ts ./"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodejs/userland-migrations.git",
+    "directory": "recipes/process-assert-to-node-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-node-assert/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.3"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*"
+  }
+}

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

@@ -0,0 +1,230 @@
+import { EOL } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+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';
+import type {
+	Edit,
+	Range,
+	Rule,
+	SgNode,
+	SgRoot,
+} from '@codemod.com/jssg-types/main';
+import type JS from '@codemod.com/jssg-types/langs/javascript';
+
+type ReplaceRule = {
+	importNode?: SgNode<JS>;
+	binding?: string;
+	rule: Rule<JS>;
+	replaceWith?: string;
+};
+
+/**
+ * Transform function that converts deprecated `process.assert` usage to the `node:assert` module.
+ *
+ * Handles:
+ * 1. Replaces `process.assert(...)` member expressions/calls with `assert(...)` or `assert.xxx` as appropriate.
+ * 2. Handles cases where `process` is imported/required under a different binding (resolves binding paths).
+ * 3. Removes the original `process` import/require when it's only used for `assert` and removes the import line when empty.
+ * 4. Adds `import assert from "node:assert";` or `const assert = require("node:assert");` at the top
+ *    when the file does not already import/require `assert`.
+ *
+ * Steps:
+ * - Find all `process` import/require statements and resolve any binding for `assert`.
+ * - Replace call and member-expression usages that reference `process.assert` (or the resolved binding) with `assert`.
+ * - Remove or update the original import/require for `process` when it's no longer needed.
+ * - If `assert` is not already present, insert the appropriate `import` or `require` line depending on the module style.
+ *
+ * @param root - The AST root node provided by jssg for the file being transformed.
+ * @returns The transformed source code as a string, or `null` when no edits are required.
+ */
+export default function transform(root: SgRoot<JS>): string | null {
+	const rootNode = root.root();
+	const edits: Edit[] = [];
+	const linesToRemove: Range[] = [];
+	const replaceRules: ReplaceRule[] = [
+		{
+			rule: {
+				kind: 'member_expression',
+				pattern: 'process.assert',
+			},
+			replaceWith: 'assert',
+		},
+	];
+
+	const processImportsToRemove = new Set<SgNode<JS>>();
+
+	const requireCalls = getNodeRequireCalls(root, 'process');
+	const importStatements = getNodeImportStatements(root, 'process');
+	const allImports = [...requireCalls, ...importStatements];
+	const processUsages = rootNode.findAll({
+		rule: {
+			kind: 'member_expression',
+			has: {
+				kind: 'identifier',
+				pattern: 'process',
+			},
+		},
+	});
+
+	for (const processImport of allImports) {
+		const binding = resolveBindingPath(processImport, '$.assert');
+
+		if (binding) {
+			// Handle member expressions like nodeAssert.strictEqual
+			replaceRules.push({
+				importNode: processImport,
+				binding,
+				rule: {
+					kind: 'member_expression',
+					has: {
+						kind: binding.includes('.') ? 'member_expression' : 'identifier',
+						pattern: binding,
+					},
+				},
+				replaceWith: 'assert',
+			});
+
+			// Handle standalone calls like nodeAssert(...)
+			replaceRules.push({
+				importNode: processImport,
+				binding,
+				rule: {
+					kind: 'call_expression',
+					has: {
+						kind: 'identifier',
+						field: 'function',
+						pattern: binding,
+					},
+				},
+				replaceWith: 'assert',
+			});
+		}
+
+		let hasNonAssertUsage = false;
+		for (const usage of processUsages) {
+			const propertyNode = usage.field('property');
+			if (propertyNode && propertyNode.text() !== 'assert') {
+				hasNonAssertUsage = true;
+				break;
+			}
+		}
+
+		if (!hasNonAssertUsage && processUsages.length > 0) {
+			processImportsToRemove.add(processImport);
+			linesToRemove.push(processImport.range());
+		}
+	}
+
+	const processedImports = new Set<SgNode<JS>>();
+
+	for (const replaceRule of replaceRules) {
+		const nodes = rootNode.findAll({
+			rule: replaceRule.rule,
+		});
+
+		for (const node of nodes) {
+			if (
+				replaceRule.importNode &&
+				!processedImports.has(replaceRule.importNode)
+			) {
+				if (!processImportsToRemove.has(replaceRule.importNode)) {
+					const removeBind = removeBinding(
+						replaceRule.importNode,
+						replaceRule.binding,
+					);
+
+					if (removeBind.edit) {
+						edits.push(removeBind.edit);
+					}
+
+					if (removeBind.lineToRemove) {
+						linesToRemove.push(removeBind.lineToRemove);
+					}
+				}
+				processedImports.add(replaceRule.importNode);
+			}
+
+			if (
+				replaceRule.rule.kind === 'member_expression' &&
+				replaceRule.binding
+			) {
+				// Replace the object part of member expressions (e.g., nodeAssert.strictEqual -> assert.strictEqual)
+				const objectNode = node.field('object');
+
+				if (objectNode) {
+					edits.push(objectNode.replace('assert'));
+				}
+			} else if (
+				replaceRule.rule.kind === 'call_expression' &&
+				replaceRule.binding
+			) {
+				// Replace the function identifier in call expressions (e.g., nodeAssert(...) -> assert(...))
+				const functionNode = node.field('function');
+
+				if (functionNode) {
+					edits.push(functionNode.replace('assert'));
+				}
+			} else {
+				const replaceText = replaceRule.replaceWith || 'assert';
+				edits.push(node.replace(replaceText));
+			}
+		}
+	}
+
+	let sourceCode = rootNode.commitEdits(edits);
+
+	sourceCode = removeLines(sourceCode, linesToRemove);
+
+	if (edits.length === 0 && linesToRemove) return sourceCode;
+
+	const alreadyRequiringAssert = getNodeRequireCalls(root, 'assert');
+	const alreadyImportingAssert = getNodeImportStatements(root, 'assert');
+
+	if (alreadyRequiringAssert.length || alreadyImportingAssert.length)
+		return sourceCode;
+
+	const usingRequire = rootNode.find({
+		rule: {
+			kind: 'call_expression',
+			has: {
+				kind: 'identifier',
+				field: 'function',
+				regex: 'require',
+			},
+		},
+	});
+	const usingImport = rootNode.find({
+		rule: {
+			kind: 'import_statement',
+		},
+	});
+	const filename = root.filename();
+	const isCjsFile = filename.endsWith('.cjs');
+	const isMjsFile = filename.endsWith('.mjs');
+
+	// Prefer adding an ES module import when the file already uses ESM syntax
+	// (contains `import` statements) or is an `.mjs` file. This avoids injecting a
+	// CommonJS `require` into an ES module source (even if the file references
+	// `createRequire`).
+	if (usingImport || isMjsFile) {
+		return `import assert from "node:assert";${EOL}${sourceCode}`;
+	}
+
+	if (usingRequire || isCjsFile) {
+		return `const assert = require("node:assert");${EOL}${sourceCode}`;
+	}
+
+	const packageJsonPath = join(process.cwd(), 'package.json');
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+	const isEsm = packageJson.type === 'module';
+
+	if (isEsm) {
+		return `import assert from "node:assert";${EOL}${sourceCode}`;
+	}
+
+	return `const assert = require("node:assert");${EOL}${sourceCode}`;
+}

recipes/process-assert-to-node-assert/tests/expected/01-basic-global-process-assert.js

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+assert(condition, "Basic assertion");
+assert.strictEqual(a, b, "Values should be equal");

recipes/process-assert-to-node-assert/tests/expected/02-basic-commonjs.cjs

@@ -0,0 +1,3 @@
+const assert = require("node:assert");
+assert(condition, "Basic assertion");
+assert.strictEqual(a, b, "Values should be equal");

recipes/process-assert-to-node-assert/tests/expected/03-esm-import-process.mjs

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+assert(value, "Process assertion");
+assert.strictEqual(obj1, obj2);

recipes/process-assert-to-node-assert/tests/expected/04-mixed-process-usage.js

@@ -0,0 +1,5 @@
+import assert from "node:assert";
+import process from "node:process";
+assert(value, "Process assertion");
+process.env.NODE_ENV = "test";
+console.log(process.pid);

recipes/process-assert-to-node-assert/tests/expected/05-require-process.js

@@ -0,0 +1,3 @@
+const assert = require("node:assert");
+assert(value, "Process assertion");
+assert.throws(() => { throw new Error(); });

recipes/process-assert-to-node-assert/tests/expected/06-destructured-assert-only.js

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+assert(condition, "Assertion from destructured import");
+assert.throws(() => { throw new Error("test"); });

recipes/process-assert-to-node-assert/tests/expected/07-destructured-mixed-bindings.js

@@ -0,0 +1,4 @@
+import assert from "node:assert";
+import { env } from "node:process";
+assert(value, "Using destructured assert");
+console.log(env.NODE_ENV);

recipes/process-assert-to-node-assert/tests/expected/08-aliased-destructured-assert.js

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+assert(value, "Using aliased assert");
+assert.notStrictEqual(a, b);

recipes/process-assert-to-node-assert/tests/expected/09-aliased-destructured-mixed.js

@@ -0,0 +1,5 @@
+import assert from "node:assert";
+import { env } from "node:process";
+assert(value, "Using aliased assert");
+assert.strictEqual(a, b);
+console.log(env.NODE_ENV);

recipes/process-assert-to-node-assert/tests/expected/10-require-destructured.js

@@ -0,0 +1,3 @@
+const assert = require("node:assert");
+assert(value, "Destructured assert from require");
+assert.strictEqual(a, b, "Should be equal");

recipes/process-assert-to-node-assert/tests/expected/11-already-has-assert-import.js

@@ -0,0 +1,3 @@
+import assert from "node:assert";
+assert(value, "This should be transformed");
+assert.strictEqual(a, b, "This should remain unchanged");

recipes/process-assert-to-node-assert/tests/expected/12-already-has-assert-require.js

@@ -0,0 +1,3 @@
+const assert = require("node:assert");
+assert(value, "This should be transformed");
+assert.strictEqual(a, b, "This should remain unchanged");

recipes/process-assert-to-node-assert/tests/expected/13-no-process-assert.js

@@ -0,0 +1,6 @@
+const config = {
+  port: 3000,
+  host: "localhost"
+};
+
+console.log("Server config:", config);

recipes/process-assert-to-node-assert/tests/expected/14-nested-in-function.js

@@ -0,0 +1,10 @@
+import assert from "node:assert";
+function testFunction() {
+  assert(condition, "Assertion inside function");
+
+  if (someCondition) {
+    assert.deepStrictEqual(obj1, obj2, "Deep comparison");
+  }
+
+  return assert.ok(value) && true;
+}

recipes/process-assert-to-node-assert/tests/expected/15-multiple-assert-methods.js

@@ -0,0 +1,6 @@
+import assert from "node:assert";
+assert(condition);
+assert.ok(value);
+assert.strictEqual(a, b);
+assert.notStrictEqual(a, c);
+assert.throws(() => { throw new Error(); });

recipes/process-assert-to-node-assert/tests/expected/16-mixed-require-and-assert.js

@@ -0,0 +1,9 @@
+const assert = require("node:assert");
+const fs = require("fs");
+
+function readConfig(path) {
+  assert(fs.existsSync(path), "Config file must exist");
+  const data = fs.readFileSync(path, "utf8");
+  assert.ok(data.length > 0, "Config file cannot be empty");
+  return JSON.parse(data);
+}