feat(tls-securepair-to-tlssocket): introduce

recipes/tls-securepair-to-tlssocket/README.md

@@ -0,0 +1,89 @@
+# tls-securepair-to-tlssocket
+
+Codemod to migrate from the deprecated `tls.SecurePair` class to `tls.TLSSocket` in Node.js applications. `SecurePair` was deprecated and subsequently removed in favor of `TLSSocket`.
+
+## What it does
+
+This codemod transforms usages of `tls.SecurePair` into `tls.TLSSocket`. Since `TLSSocket` wraps an existing socket, the codemod injects a `socket` argument that you may need to define or bind in your context.
+
+Key transformations:
+- **Constructor:** Replaces `new SecurePair()` with `new TLSSocket(socket)`.
+- **Imports:** Updates `require` and `import` statements from `SecurePair` to `TLSSocket`.
+- **Renaming:** Intelligently renames variables (e.g., `pair` → `socket`, `securePairInstance` → `socketInstance`) while preserving CamelCase.
+- **Cleanup:** Removes deprecated property accesses like `.cleartext` and `.encrypted`.
+- **Annotations:** Adds comments to highlight where manual API verification is needed.
+
+## Supports
+
+- **Module Systems:**
+  - CommonJS: `const tls = require('node:tls')` / `const { SecurePair } = ...`
+  - ESM: `import tls from 'node:tls'` / `import { SecurePair } ...`
+- **Variable Renaming:**
+  - Updates variable declarations: `const pair = ...` → `const socket = ...`
+  - Updates references deep in the scope: `pair.on('error')` → `socket.on('error')`
+  - Handles naming variations: `myPair` → `mySocket`, `securePair` → `secureSocket`.
+- **Cleanup:**
+  - Identifies and removes lines accessing `cleartext` or `encrypted` properties.
+- **Namespace Handling:**
+  - Supports both `new tls.SecurePair()` and `new SecurePair()`.
+
+## Examples
+
+### Case 1: CommonJS with namespace access
+
+```diff
+  const tls = require('node:tls');
+
+- const pair = new tls.SecurePair();
+- const encrypted = pair.encrypted;
++ const socket = new tls.TLSSocket(socket);
+```
+
+### Case 2: ESM with destructuring
+
+```diff
+- import { SecurePair } from 'node:tls';
++ import { TLSSocket } from 'node:tls';
+
+- const myPair = new SecurePair();
+- myPair.cleartext.write('hello');
++ const mySocket = new TLSSocket(socket);
++ mySocket.write('hello');
+```
+
+### Case 3: Variable renaming across scope
+
+```diff
+  const tls = require('node:tls');
+
+- const securePair = new tls.SecurePair();
++ const secureSocket = new tls.TLSSocket(socket);
+
+- securePair.on('error', (err) => {
++ secureSocket.on('error', (err) => {
+    console.error(err);
+  });
+```
+
+### Case 4: Multiple variables with cleanup
+
+```diff
+- const { SecurePair } = require('node:tls');
++ const { TLSSocket } = require('node:tls');
+
+- const pair = new SecurePair();
+- const cleartext = pair.cleartext;
++ const socket = new TLSSocket(socket);
+```
+
+## Warning
+
+The tls.TLSSocket constructor requires an existing socket instance (net.Socket) as an argument. This codemod automatically inserts socket as the argument:
+JavaScript
+
+```js
+```
+new TLSSocket(socket)
+```
+
+You must ensure that a variable named socket exists in the scope or rename it to match your existing socket variable (e.g., clientSocket, stream, etc.).

recipes/tls-securepair-to-tlssocket/codemod.yaml

@@ -0,0 +1,23 @@
+schema_version: "1.0"
+name: "@nodejs/tls-securepair-to-tlssocket"
+version: "1.0.0"
+description: Migrate usages of `tls.SecurePair` to `tls.TLSSocket` where possible.
+author: Maxime Devillet
+license: MIT
+workflow: workflow.yaml
+category: migration
+
+targets:
+  languages:
+    - javascript
+    - typescript
+
+keywords:
+  - transformation
+  - migration
+  - tls
+  - securepair
+
+registry:
+  access: public
+  visibility: public

recipes/tls-securepair-to-tlssocket/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@nodejs/tls-securepair-to-tlssocket",
+  "version": "1.0.0",
+  "description": "Migrate usages of tls.SecurePair to tls.TLSSocket.",
+  "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/tls-securepair-to-tlssocket",
+    "bugs": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "author": "Maxime Devillet",
+  "license": "MIT",
+  "homepage": "https://github.com/nodejs/userland-migrations/blob/main/recipes/tls-securepair-to-tlssocket/README.md",
+  "devDependencies": {
+    "@codemod.com/jssg-types": "^1.0.9"
+  },
+  "dependencies": {
+    "@nodejs/codemod-utils": "*",
+    "@ast-grep/napi": "^0.40.0"
+  }
+}

recipes/tls-securepair-to-tlssocket/src/workflow.ts

@@ -0,0 +1,159 @@
+import {
+	getNodeImportStatements,
+	getNodeImportCalls,
+} from '@nodejs/codemod-utils/ast-grep/import-statement';
+import { getNodeRequireCalls } from '@nodejs/codemod-utils/ast-grep/require-call';
+import { updateBinding } from '@nodejs/codemod-utils/ast-grep/update-binding';
+import { removeLines } from '@nodejs/codemod-utils/ast-grep/remove-lines';
+import { getScope } from '@nodejs/codemod-utils/ast-grep/get-scope';
+import type { Edit, SgRoot, Range, SgNode } from '@codemod.com/jssg-types/main';
+import type Js from '@codemod.com/jssg-types/langs/javascript';
+
+// Codemod: migrate SecurePair -> TLSSocket
+
+function getClosest(node: SgNode<Js>, kinds: string[]): SgNode<Js> | null {
+	// Prefer shared `getScope` helper when a single kind is requested.
+	if (kinds.length === 1) return getScope(node, kinds[0]) ?? null;
+
+	// Walk up the ancestor chain and return the first matching kind.
+	let current = node.parent();
+	while (current) {
+		if (kinds.includes(current.kind())) return current;
+		current = current.parent();
+	}
+
+	return null;
+}
+
+// Utility: find the closest ancestor whose kind is one of `kinds`.
+// Returns the first matching ancestor or `null` when none is found.
+
+export default function transform(root: SgRoot<Js>): string | null {
+	const rootNode = root.root();
+	const edits: Edit[] = [];
+	const linesToRemove: Range[] = [];
+
+	// Collect all import/require nodes that reference the `tls` module.
+	// This includes static imports, require() calls and dynamic imports.
+	const importNodes = [
+		...getNodeImportStatements(root, 'tls'),
+		...getNodeRequireCalls(root, 'tls'),
+		...getNodeImportCalls(root, 'tls'),
+	];
+
+	for (const node of importNodes) {
+		// Update any binding that imports SecurePair -> TLSSocket (e.g. import { SecurePair })
+		const change = updateBinding(node, { old: 'SecurePair', new: 'TLSSocket' });
+		if (change?.edit) edits.push(change.edit);
+		if (change?.lineToRemove) linesToRemove.push(change.lineToRemove);
+	}
+
+	// Find `new` expressions that construct a SecurePair either via namespace
+	// (e.g. `tls.SecurePair`) or via a direct identifier (`SecurePair`).
+	const newExpressions = rootNode.findAll({
+		rule: {
+			kind: 'new_expression',
+			has: {
+				any: [
+					{
+						kind: 'member_expression',
+						has: { field: 'property', regex: '^SecurePair$' },
+					},
+					{ kind: 'identifier', pattern: 'SecurePair' },
+				],
+			},
+		},
+	});
+
+	for (const node of newExpressions) {
+		const callee = node.field('constructor');
+		if (!callee) continue;
+
+		let newConstructorName = 'TLSSocket';
+		if (callee.kind() === 'member_expression') {
+			const object = callee.field('object');
+			if (object) {
+				newConstructorName = `${object.text()}.TLSSocket`;
+			}
+		}
+
+		// Replace the constructor call with `new TLSSocket(socket)`.
+		edits.push(node.replace(`new ${newConstructorName}(socket)`));
+		const declarator = getClosest(node, ['variable_declarator']);
+		if (declarator) {
+			const idNode = declarator.field('name');
+			if (idNode) {
+				const oldName = idNode.text();
+				let newName = 'socket';
+				if (oldName !== 'pair' && oldName !== 'SecurePair') {
+					if (oldName.includes('Pair'))
+						newName = oldName.replace('Pair', 'Socket');
+					else if (oldName.includes('pair'))
+						newName = oldName.replace('pair', 'socket');
+				}
+
+				// Find usages like `pair.cleartext` or `pair.encrypted` to remove those
+				// statements as they don't apply to TLSSocket-based code.
+				const obsoleteUsages = rootNode.findAll({
+					rule: {
+						kind: 'member_expression',
+						all: [
+							{ has: { field: 'object', regex: `^${oldName}$` } },
+							{ has: { field: 'property', regex: '^(cleartext|encrypted)$' } },
+						],
+					},
+				});
+				for (const usage of obsoleteUsages) {
+					const statement = getClosest(usage, [
+						'lexical_declaration',
+						'expression_statement',
+					]);
+					if (statement) linesToRemove.push(statement.range());
+				}
+
+				// Rename the variable (e.g. `pair` -> `socket`) and update references.
+				edits.push(idNode.replace(newName));
+				const references = rootNode.findAll({
+					rule: { kind: 'identifier', regex: `^${oldName}$` },
+				});
+
+				// Update all references, skipping property accesses and imports.
+				for (const ref of references) {
+					const parent = ref.parent();
+					if (!parent) continue;
+
+					const parentKind = parent.kind();
+					if (parentKind === 'member_expression') {
+						const property = parent.field('property');
+						if (property && property.id() === ref.id()) continue;
+					}
+					if (
+						parentKind === 'import_specifier' ||
+						parentKind === 'shorthand_property_identifier_pattern'
+					)
+						continue;
+					if (ref.id() === idNode.id()) continue;
+
+					edits.push(ref.replace(newName));
+				}
+			}
+		}
+	}
+
+	const sourceCode = rootNode.commitEdits(edits);
+
+	let output = removeLines(sourceCode, linesToRemove) ?? '';
+	// Normalize newlines and trim trailing whitespace for predictable snapshots.
+	output = output.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+	output = output.replace(/(^.*\S)[ \t]+$/gm, '$1');
+	output = output.replace(/^\uFEFF/, '');
+
+	const eol =
+		typeof process !== 'undefined' && process.platform === 'win32'
+			? '\r\n'
+			: '\n';
+	output = output.replace(/\n/g, eol);
+	if (output.endsWith(eol)) output = output.slice(0, -eol.length);
+
+	return output;
+}

recipes/tls-securepair-to-tlssocket/tests/expected/basic-test-file-3.js

@@ -0,0 +1,11 @@
+const tls = require('node:tls');
+const fs = require('fs'); // Code non lié
+
+function createSecureConnection() {
+  // Using tls.SecurePair constructor
+  const socket = new tls.TLSSocket(socket);
+
+  // Ces lignes doivent disparaître
+
+  return socket;
+}

recipes/tls-securepair-to-tlssocket/tests/expected/file-1.js

@@ -0,0 +1,8 @@
+const tls = require('node:tls');
+
+// Using tls.SecurePair constructor
+const socket = new tls.TLSSocket(socket);
+
+// Direct import
+const { TLSSocket } = require('node:tls');
+const socket2 = new TLSSocket(socket);

recipes/tls-securepair-to-tlssocket/tests/expected/file-2.js

@@ -0,0 +1,8 @@
+import tls from 'node:tls';
+
+// Using tls.SecurePair constructor
+const socket = new tls.TLSSocket(socket);
+
+// Direct import
+import { TLSSocket } from 'node:tls';
+const socket2 = new TLSSocket(socket);

recipes/tls-securepair-to-tlssocket/tests/expected/test-crucial-file.js

@@ -0,0 +1,10 @@
+const { TLSSocket } = require('node:tls');
+const { unrelated } = require('other-module');
+
+const socket = new TLSSocket(socket);
+
+socket.on('error', (err) => {
+  console.error(err);
+});
+
+// Obsolete properties

recipes/tls-securepair-to-tlssocket/tests/expected/test-edge-variable-name-file.js

@@ -0,0 +1,7 @@
+const { TLSSocket } = require('node:tls');
+
+// Completely arbitrary variable name
+const socket = new TLSSocket(socket);
+
+// Usage
+socket.doSomething();

recipes/tls-securepair-to-tlssocket/tests/expected/test-esm-file.js

@@ -0,0 +1,8 @@
+import tls from 'node:tls';
+import { TLSSocket } from 'node:tls';
+
+// Case 1: Via namespace
+const socket1 = new tls.TLSSocket(socket);
+
+// Case 2: Direct
+const socket2 = new TLSSocket(socket);

recipes/tls-securepair-to-tlssocket/tests/expected/test-multiple-variable-file.js

@@ -0,0 +1,7 @@
+const tls = require('node:tls');
+
+const socket = new tls.TLSSocket(socket);
+const mySocket = new tls.TLSSocket(socket);
+const secureSocketInstance = new tls.TLSSocket(socket);
+
+// Specific cleanup for each variable

recipes/tls-securepair-to-tlssocket/tests/expected/test-scoping-file.js

@@ -0,0 +1,14 @@
+const tls = require('node:tls');
+
+class ConnectionManager {
+  constructor() {
+    if (true) {
+      const socket = new tls.TLSSocket(socket);
+      this.init(socket);
+
+      if (socket.cleartext) {
+        console.log("cleaning");
+      }
+    }
+  }
+}