feat(logger): expose utils to other recipes (#93)

AugustinMauroy · avivkeller · JakobJingleheimer · web-flow · commit 660154517b11 · 2025-06-30T17:28:06.000-04:00
Co-authored-by: Aviv Keller &lt;me@aviv.sh&gt;
Co-authored-by: Jacob Smith &lt;3012099+JakobJingleheimer@users.noreply.github.com&gt;
diff --git a/.github/workflows/codemod_publish.yml b/.github/workflows/codemod_publish.yml
@@ -5,7 +5,6 @@ on:
   push:
     paths:
       - "recipes/**"
-      - "codemods/**"
     branches:
       - main
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,7 +8,7 @@ files).
   * unit tests
   * end-to-end test(s) for accepted use-cases
   * a `test` command in `package.json`; there may be sub-commands like `test:unit` & `test:e2e`, but there must be a parent that combines them.
-    * Include `--import='../../build/snapshots.mts` to standardise the filename (`${original_base_name}.snap.cjs`) across recipes.
+    * Include `--import='@nodejs/codemod-utils/snapshots` to standardise the filename (`${original_base_name}.snap.cjs`) across recipes.
     * Ensure `--test-coverage-include` and `--test-coverage-exclude` are set correctly for the recipe's workspace. The root repo handles setting coverage rules like minimum line coverage.
 * Code comments (js docs, etc)
 * Types (either via typescript or jsdoc)
@@ -20,3 +20,6 @@ New recipes are added under `./recipes` in their own folder, succinctly named fo
 ## Before pushing a commit
 
 A convenient superset of checks is available via `node --run pre-commit`, which automatically fixes formatting and linting issues (that are safe to fix), checks types, and runs tests. Changes resulting from this should be committed.
+
+> [!WARNING]
+> Some integration tests modify fixtures because they run the entire codemod. Remember to use the `git restore` command to restore these files before pushing a commit.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -7,7 +7,7 @@
     "lint:fix": "biome lint --fix ./",
     "lint": "biome lint ./",
     "pre-commit": "node --run lint:fix; node --run type-check; node --run test",
-    "test": "npm run test --workspaces -- --import='./test/snapshots.ts' --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout",
+    "test": "npm run test --workspaces",
     "type-check": "tsc"
   },
   "repository": {
@@ -31,6 +31,7 @@
     "typescript": "^5.8.3"
   },
   "workspaces": [
-    "./recipes/*"
+    "./recipes/*",
+    "utils"
   ]
 }
diff --git a/recipes/correct-ts-specifiers/package.json b/recipes/correct-ts-specifiers/package.json
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node --no-warnings --experimental-import-meta-resolve --experimental-strip-types ./src/workflow.ts",
-    "test": "node --no-warnings --experimental-import-meta-resolve --experimental-test-module-mocks --experimental-test-snapshots --experimental-strip-types --import='../../test/snapshots.ts' --test --experimental-test-coverage --test-coverage-include='src/**/*' --test-coverage-exclude='**/*.test.ts' './**/*.test.ts'"
+    "test": "node --no-warnings --experimental-import-meta-resolve --experimental-test-module-mocks --experimental-test-snapshots --experimental-strip-types --import='@nodejs/codemod-utils/snapshots' --test --experimental-test-coverage --test-coverage-include='src/**/*' --test-coverage-exclude='**/*.test.ts' './**/*.test.ts'"
   },
   "repository": {
     "type": "git",
@@ -35,6 +35,7 @@
     "@nodejs-loaders/alias": "^2.1.2"
   },
   "devDependencies": {
+    "@nodejs/codemod-utils": "*",
     "@types/node": "^24.0.3"
   }
 }
diff --git a/recipes/correct-ts-specifiers/src/map-imports.test.ts b/recipes/correct-ts-specifiers/src/map-imports.test.ts
@@ -6,7 +6,7 @@ import { dExts } from './exts.ts';
 import type { FSAbsolutePath } from './index.d.ts';
 
 
-type Logger = typeof import('./logger.ts').logger;
+type Logger = typeof import('@nodejs/codemod-utils/logger').logger;
 type MapImports = typeof import('./map-imports.ts').mapImports;
 
 describe('Map Imports', { concurrency: true }, () => {
@@ -17,7 +17,7 @@ describe('Map Imports', { concurrency: true }, () => {
 	before(async () => {
 		const logger = mock.fn<Logger>();
 		({ mock: mock__log } = logger);
-		mock.module('./logger.ts', {
+		mock.module('@nodejs/codemod-utils/logger', {
 			namedExports: { logger },
 		});
 
diff --git a/recipes/correct-ts-specifiers/src/map-imports.ts b/recipes/correct-ts-specifiers/src/map-imports.ts
@@ -1,6 +1,6 @@
+import { logger } from '@nodejs/codemod-utils/logger';
 import type { FSAbsolutePath, Specifier } from './index.d.ts';
 import { fexists } from './fexists.ts';
-import { logger } from './logger.ts';
 import { isDir } from './is-dir.ts';
 import { isIgnorableSpecifier } from './is-ignorable-specifier.ts';
 import { replaceJSExtWithTSExt } from './replace-js-ext-with-ts-ext.ts';
diff --git a/recipes/correct-ts-specifiers/src/replace-js-ext-with-ts-ext.test.ts b/recipes/correct-ts-specifiers/src/replace-js-ext-with-ts-ext.test.ts
@@ -8,7 +8,7 @@ import type { FSAbsolutePath } from './index.d.ts';
 
 type MockModuleContext = ReturnType<typeof mock.module>;
 
-type Logger = typeof import('./logger.ts').logger;
+type Logger = typeof import('@nodejs/codemod-utils/logger').logger;
 type ReplaceJSExtWithTSExt = typeof import('./replace-js-ext-with-ts-ext.ts').replaceJSExtWithTSExt;
 
 describe('Correcting ts file extensions', { concurrency: true }, () => {
@@ -23,7 +23,7 @@ describe('Correcting ts file extensions', { concurrency: true }, () => {
 	before(async () => {
 		const logger = mock.fn<Logger>();
 		({ mock: mock__log } = logger);
-		mock__logger = mock.module('./logger.ts', {
+		mock__logger = mock.module('@nodejs/codemod-utils/logger', {
 			namedExports: { logger },
 		});
 
diff --git a/recipes/correct-ts-specifiers/src/replace-js-ext-with-ts-ext.ts b/recipes/correct-ts-specifiers/src/replace-js-ext-with-ts-ext.ts
@@ -1,9 +1,11 @@
 import { extname } from 'node:path';
 
+import { logger } from '@nodejs/codemod-utils/logger';
+
 import type { FSAbsolutePath, NodeModSpecifier, ResolvedSpecifier, Specifier } from './index.d.ts';
 import { type DExt, type JSExt, type TSExt, extSets, suspectExts } from './exts.ts';
 import { fexists } from './fexists.ts';
-import { logger } from './logger.ts';
+
 import { isDir } from './is-dir.ts';
 
 /**
diff --git a/recipes/correct-ts-specifiers/src/workflow.test.ts b/recipes/correct-ts-specifiers/src/workflow.test.ts
@@ -3,8 +3,7 @@ import { execPath } from 'node:process';
 import { readFile } from 'node:fs/promises';
 import { describe, it } from 'node:test';
 import { fileURLToPath } from 'node:url';
-
-import { spawnPromisified } from '../../../test/spawn-promisified.ts';
+import { spawnPromisified } from '@nodejs/codemod-utils/spawn-promisified';
 
 describe('workflow', () => {
 	it('should update bad specifiers and ignore good ones', async (t) => {
diff --git a/tsconfig.json b/tsconfig.json
@@ -40,9 +40,9 @@
     "skipLibCheck": true
   },
   "include": [
-    "./build/",
     "./recipes/",
     "./test",
+    "./utils"
   ],
   "exclude": [
     "node_modules",
diff --git a/utils/package.json b/utils/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@nodejs/codemod-utils",
+  "version": "0.0.0",
+  "description": "Utilities for Node.js userland migrations.",
+  "exports": {
+    "./*": [
+      "./src/*.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --no-warnings --experimental-test-snapshots --experimental-strip-types --import='./src/snapshots.ts' --test --experimental-test-coverage --test-coverage-include='src/**/*' --test-coverage-exclude='**/*.test.ts' './**/*.test.ts'"
+  },
+  "author": "Augustin Maurouy",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "dedent": "^1.6.0"
+  }
+}
diff --git a/utils/src/logger.test.snap.cjs b/utils/src/logger.test.snap.cjs
diff --git a/utils/src/logger.test.ts b/utils/src/logger.test.ts
@@ -1,8 +1,8 @@
 import assert from 'node:assert/strict';
 import { execPath } from 'node:process';
 import { describe, it } from 'node:test';
-
-import { spawnPromisified } from '../../../test/spawn-promisified.ts';
+import dedent from 'dedent';
+import { spawnPromisified } from './spawn-promisified.ts';
 
 describe('logger', { concurrency: true }, () => {
 	it('should emit non-error entries to standard out, collated by source module', async (t) => {
@@ -12,7 +12,7 @@ describe('logger', { concurrency: true }, () => {
 				'--no-warnings',
 				'--experimental-strip-types',
 				'-e',
-				`
+				dedent`
 				import { logger } from './logger.ts';
 
 				const source1 = '/tmp/foo.js';
@@ -40,7 +40,7 @@ describe('logger', { concurrency: true }, () => {
 				'--no-warnings',
 				'--experimental-strip-types',
 				'-e',
-				`
+				dedent`
 				import { logger } from './logger.ts';
 
 				const source1 = '/tmp/foo.js';
@@ -50,7 +50,7 @@ describe('logger', { concurrency: true }, () => {
 				const source2 = '/tmp/foo.js';
 				logger(source2, 'error', 'sh*t happened');
 				logger(source2, 'warn', 'maybe other bad');
-			`,
+				`,
 			],
 			{
 				cwd: import.meta.dirname,
diff --git a/utils/src/logger.ts b/utils/src/logger.ts
@@ -22,8 +22,6 @@ const logs = new Map<Source, Set<FileLog>>();
 
 process.once('beforeExit', emitLogs);
 
-/* node:coverage disable */
-// this is actually coveraged, but v8 doesn't recognise it
 function emitLogs() {
 	let hasError = false;
 
@@ -43,4 +41,3 @@ function emitLogs() {
 		console.log('[Codemod: correct-ts-specifiers]: migration complete!');
 	}
 }
-/* node:coverage enable */
diff --git a/utils/src/snapshots.ts b/utils/src/snapshots.ts
@@ -1,13 +1,11 @@
 import { basename, dirname, extname, join } from 'node:path';
 import { snapshot } from 'node:test';
 
-snapshot.setResolveSnapshotPath(generateSnapshotPath);
 /**
  * @param {string} testFilePath `'/tmp/foo.test.js'`
  * @returns `'/tmp/foo.test.snap.cjs'`
- * @type {Parameters<snapshot.setResolveSnapshotPath>[0]}
  */
-function generateSnapshotPath(testFilePath) {
+const generateSnapshotPath: Parameters<typeof snapshot.setResolveSnapshotPath>[0] = (testFilePath) => {
 	if (!testFilePath) return '';
 
 	const ext = extname(testFilePath);
@@ -16,3 +14,5 @@ function generateSnapshotPath(testFilePath) {
 
 	return join(base, `${filename}.snap.cjs`);
 }
+
+snapshot.setResolveSnapshotPath(generateSnapshotPath);
diff --git a/utils/src/spawn-promisified.test.ts b/utils/src/spawn-promisified.test.ts
@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import process from "node:process";
+import { spawnPromisified } from "./spawn-promisified.ts";
+
+describe("spawnPromisified",{concurrency: true} , () => {
+  it("should spawn a process and return its output", async () => {
+	const { code, stdout, stderr } = await spawnPromisified(
+	  "echo",
+	  ["Hello, World!"],
+	  {
+		cwd: import.meta.dirname,
+	  }
+	);
+
+	assert.strictEqual(code, 0);
+	assert.strictEqual(stdout.trim(), "Hello, World!");
+	assert.strictEqual(stderr, "");
+  });
+
+  it("should handle node process arguments", async () => {
+	const { code, stdout, stderr } = await spawnPromisified(
+	  process.execPath,
+	  ["-e", "console.log('Hello from Node!')"],
+	  {
+		cwd: import.meta.dirname,
+	  }
+	);
+
+	assert.strictEqual(code, 0);
+	assert.strictEqual(stdout.trim(), "Hello from Node!");
+	assert.strictEqual(stderr, "");
+  });
+
+
+  it("should handle errors in the spawned process", async () => {
+	try {
+	  // @ts-ignore - it's a test, we expect that argument to be invalid
+	  await spawnPromisified("nonexistent-command");
+	} catch (error) {
+	  assert.strictEqual(error.error.code, "ENOENT");
+	}
+  });
+});
diff --git a/utils/src/spawn-promisified.ts b/utils/src/spawn-promisified.ts
@@ -28,10 +28,9 @@ export function spawnPromisified(...args: Parameters<typeof spawn>) {
 				stdout,
 			});
 		});
-		child.on('error', (code, signal) => {
+		child.on('error', (error) => {
 			reject({
-				code,
-				signal,
+				error,
 				stderr,
 				stdout,
 			});
