Feat(node url to whatwg url)

biome.jsonc

@@ -1,7 +1,7 @@
 {
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "files": {
-    "includes": ["**", "!**/*.snap.cjs", "!**/fixtures/**", "!**/expected/**", "!**/input/**"]
+    "includes": ["**", "!**/*.snap.cjs", "!**/fixtures/**", "!**/tests/**"]
   },
   "assist": { "actions": { "source": { "organizeImports": "off" } } },
   // Rules for the linter

recipes/node-url-to-whatwg-url/README.md

@@ -0,0 +1,58 @@
+# Node.js URL to WHATWG URL
+
+This recipe converts Node.js `url` module usage to the WHATWG URL API. It modifies code that uses the legacy `url` module to use the modern `URL` class instead.
+
+See [DEP0116](https://nodejs.org/api/deprecations.html#DEP0116).
+
+## Example
+
+
+**`url.parse` to `new URL()`**
+```js
+// Before
+const url = require('node:url');
+
+const myUrl = new url.URL('https://example.com');
+const urlAuth = legacyURL.auth;
+// After
+const myUrl = new URL('https://example.com');
+const urlAuth = `${myUrl.username}:${myUrl.password}`;
+```
+
+**`url.format` to `myUrl.toString()`**
+```js
+// Before
+const url = require('node:url');
+
+url.format({
+  protocol: 'https',
+  hostname: 'example.com',
+  pathname: '/some/path',
+  query: {
+    page: 1,
+    format: 'json',
+  },
+});
+// After
+const myUrl = new URL('https://example.com/some/path?page=1&format=json').toString();
+```
+
+## Caveats
+
+The [`url.resolve`](https://nodejs.org/api/url.html#urlresolvefrom-to) method is not directly translatable to the WHATWG URL API. You may need to implement custom logic to handle URL resolution in your application.
+
+```js
+function resolve(from, to) {
+  const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
+  if (resolvedUrl.protocol === 'resolve:') {
+    // `from` is a relative URL.
+    const { pathname, search, hash } = resolvedUrl;
+    return pathname + search + hash;
+  }
+  return resolvedUrl.toString();
+}
+
+resolve('/one/two/three', 'four');         // '/one/two/four'
+resolve('http://example.com/', '/one');    // 'http://example.com/one'
+resolve('http://example.com/one', '/two'); // 'http://example.com/two'
+```

recipes/node-url-to-whatwg-url/codemod.yaml

@@ -0,0 +1,21 @@
+schema_version: "1.0"
+name: "@nodejs/node-url-to-whatwg-url"
+version: 1.0.0
+description: Handle DEPDEP0116 via transforming `url.parse` to `new URL()`
+author: Augustin Mauroy
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+
+registry:
+  access: public
+  visibility: public

recipes/node-url-to-whatwg-url/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@nodejs/node-url-to-whatwg-url",
+  "version": "1.0.0",
+  "description": "Handle DEPDEP0116 via transforming `url.parse` to `new URL()`",
+  "type": "module",
+  "scripts": {
+  "test": "node --run test:import-process && node --run test:url-format && node --run test:url-parse",
+  "test:import-process": "npx codemod@next jssg test -l typescript ./src/import-process.ts ./tests/ --filter import-process",
+  "test:url-format": "npx codemod@next jssg test -l typescript ./src/url-format.ts ./tests/ --filter url-format",
+  "test:url-parse": "npx codemod@next jssg test -l typescript ./src/url-parse.ts ./tests/ --filter url-parse"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodejs/userland-migrations.git",
+    "directory": "recipes/node-url-to-whatwg-url",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "Augustin Mauroy",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/tree/main/node-url-to-whatwg-url#readme",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.3"
+  }
+}

recipes/node-url-to-whatwg-url/src/import-process.ts

@@ -0,0 +1,114 @@
+import type { SgRoot, Edit, Range } from "@codemod.com/jssg-types/main";
+import type JS from "@codemod.com/jssg-types/langs/javascript";
+import { getNodeImportStatements } from "@nodejs/codemod-utils/ast-grep/import-statement";
+import { getNodeRequireCalls } from "@nodejs/codemod-utils/ast-grep/require-call";
+import { removeLines } from "@nodejs/codemod-utils/ast-grep/remove-lines";
+
+/**
+ * Clean up unused imports/requires from 'node:url' after transforms using shared utils
+ */
+export default function transform(root: SgRoot<JS>): string | null {
+    const rootNode = root.root();
+    const edits: Edit[] = [];
+
+    const isBindingUsed = (name: string): boolean => {
+        const refs = rootNode.findAll({ rule: { pattern: name } });
+        // Heuristic: declaration counts as one; any other usage yields > 1
+        return refs.length > 1;
+    };
+
+    const linesToRemove: Range[] = [];
+
+    // 1) ES Module imports: import ... from 'node:url'
+    // @ts-ignore - ast-grep types vs jssg types
+    const esmImports = getNodeImportStatements(root, "url");
+
+    for (const imp of esmImports) {
+        const clause = imp.find({ rule: { kind: "import_clause" } });
+        let removed = false;
+        if (clause) {
+            const nsId = clause.find({ rule: { kind: "namespace_import" } })?.find({ rule: { kind: "identifier" } });
+            if (nsId && !isBindingUsed(nsId.text())) {
+                linesToRemove.push(imp.range());
+                removed = true;
+            }
+            if (removed) continue;
+
+            const specs = clause.findAll({ rule: { kind: "import_specifier" } });
+
+            if (specs.length === 0 && !nsId) {
+                const defaultId = clause.find({ rule: { kind: "identifier" } });
+                if (defaultId && !isBindingUsed(defaultId.text())) {
+                    linesToRemove.push(imp.range());
+                    removed = true;
+                }
+                if (removed) continue;
+            }
+
+            if (specs.length > 0) {
+                const keepTexts: string[] = [];
+                for (const spec of specs) {
+                    const text = spec.text().trim();
+                    const bindingName = text.includes(" as ") ? text.split(/\s+as\s+/)[1] : text;
+                    if (bindingName && isBindingUsed(bindingName)) keepTexts.push(text);
+                }
+                if (keepTexts.length === 0) {
+                    linesToRemove.push(imp.range());
+                } else if (keepTexts.length !== specs.length) {
+                    const namedImportsNode = clause.find({ rule: { kind: "named_imports" } });
+                    if (namedImportsNode) edits.push(namedImportsNode.replace(`{ ${keepTexts.join(", ")} }`));
+                }
+            }
+        }
+    }
+
+    // 2) CommonJS requires: const ... = require('node:url')
+    // @ts-ignore - ast-grep types vs jssg types
+    const requireDecls = getNodeRequireCalls(root, "url");
+
+    for (const decl of requireDecls) {
+        const id = decl.find({ rule: { kind: "identifier" } });
+        const hasObjectPattern = decl.find({ rule: { kind: "object_pattern" } });
+
+        if (id && !hasObjectPattern) {
+            if (!isBindingUsed(id.text())) linesToRemove.push(decl.parent().range());
+            continue;
+        }
+
+        if (hasObjectPattern) {
+            const names: string[] = [];
+            const shorts = decl.findAll({ rule: { kind: "shorthand_property_identifier_pattern" } });
+            for (const s of shorts) names.push(s.text());
+            const pairs = decl.findAll({ rule: { kind: "pair_pattern" } });
+            for (const pair of pairs) {
+                const aliasId = pair.find({ rule: { kind: "identifier" } });
+                if (aliasId) names.push(aliasId.text());
+            }
+
+            const usedTexts: string[] = [];
+            for (const s of shorts) if (isBindingUsed(s.text())) usedTexts.push(s.text());
+            for (const pair of pairs) {
+                const aliasId = pair.find({ rule: { kind: "identifier" } });
+                if (aliasId && isBindingUsed(aliasId.text())) usedTexts.push(pair.text());
+            }
+
+            if (usedTexts.length === 0) {
+                linesToRemove.push(decl.parent().range());
+            } else if (usedTexts.length !== names.length) {
+                const objPat = decl.find({ rule: { kind: "object_pattern" } });
+                if (objPat) edits.push(objPat.replace(`{ ${usedTexts.join(", ")} }`));
+            }
+        }
+    }
+
+    if (edits.length === 0 && linesToRemove.length === 0) return null;
+
+    let source = rootNode.commitEdits(edits);
+
+    source = removeLines(source, linesToRemove.map(range => ({
+        start: { line: range.start.line, column: 0, index: 0 },
+        end: { line: range.end.line + 1, column: 0, index: 0 }
+    })));
+
+    return source;
+};