chore: set up initial actions & docs

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  Lint:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [23.x]
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run test:lint
+    - run: npm run test:types
+
+  Test:
+    runs-on:
+      macos-latest
+      ubuntu-latest
+      windows-latest
+
+    strategy:
+      matrix:
+        node-version: [23.x, 22.x, 20.x]
+        fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run test:unit
+    - run: npm run test:e2e

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+A recipe generally has a few things:
+
+* A `README.md` explaining its purpose and use (including any options, and required and optional
+files).
+* Tests via node's test runner (min coverage: 80%)
+  * unit tests  (file extension: `.spec.mjs` or `.spec.mts`)
+  * end-to-end test(s) for accepted use-cases (file extension: `.e2e.mjs` or `.e2e.mts`)
+* Code comments (js docs, etc)
+* Types (either via typescript or jsdoc)
+
+CI will run lint & type checking and all included test files against all PRs.
+
+> [!INFO]
+> snapshots will be generated with the file extension `.snap.cjs`.
+
+New recipes are added under `./recipes` in their own folder, succinctly named for what it does. General-purpose recipes have simple names like `correct-ts-specifiers`. A suite of migrations has a name like `migrate from 18 to 20`, and more specific migrations are named like `migrate fs.readFile from 18 to 20`.

README.md

@@ -1 +1,23 @@
 # Node.js userland migrations
+
+This repository contains codemodes (automated migrations) for "userland" code. These are intended to facilitate adopting new features and upgrading source-code affected by breaking changes.
+
+## Usage
+
+> [!CAUTION]
+> These scripts change source code. Commit any unsaved changes before running them. Failing to do so may ruin your day.
+
+To run the transform scripts use [`codemod`](https://go.codemod.com/github) command below:
+
+```console
+$ npx codemod <transform> --target <path> [...options]
+```
+
+* `transform` - name of transform. see available transforms below.
+* `path` - directory to transform. defaults to the current directory.
+
+See the [codemod CLI doc](https://go.codemod.com/cli-docs) for a full list of available commands.
+
+## Available codemods
+
+All Node.js codemods are also available in the [Codemod Registry](https://codemod.com/registry?framework=node.js).

biome.jsonc

@@ -0,0 +1,28 @@
+{
+  "formatter": {
+    "indentStyle": "tab",
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+			"semicolons": "always",
+      "quoteStyle": "single",
+      "trailingCommas": "all"
+    },
+		"linter": {
+			"style": {
+				"useImportType": true
+			}
+		}
+  },
+  "json": {
+    "formatter": {
+      "enabled": false
+    }
+  },
+	"markdown": {
+    "formatter": {
+      "enabled": false
+    }
+  }
+}

build/snapshots.ts

@@ -0,0 +1,18 @@
+import { basename, dirname, extname, join } from 'node:path';
+import { snapshot } from 'node:test';
+
+
+snapshot.setResolveSnapshotPath(generateSnapshotPath);
+/**
+ * @param testFilePath '/tmp/foo.test.js'
+ * @returns '/tmp/foo.test.snap.cjs'
+ */
+function generateSnapshotPath(testFilePath?: string) {
+  if (!testFilePath) return '';
+
+  const ext = extname(testFilePath);
+  const filename = basename(testFilePath, ext);
+  const base = dirname(testFilePath);
+
+  return join(base, `${filename}.snap.cjs`);
+}

package.json

@@ -0,0 +1,35 @@
+{
+  "name": "userland-migrations",
+  "version": "1.0.0",
+  "description": "A collection of migration recipes for userland code.",
+  "main": "index.js",
+  "scripts": {
+    "test:e2e": "node --no-warnings --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=./coverage.lcov --test-reporter=spec --test-reporter-destination=stdout --import './build/snapshots.ts' -test --test-coverage-include='recipes/**/*' --test-coverage-exclude='**/*.e2e.m(j|t)s' './packages/*/*.e2e.m(j|t)s'",
+    "test:lint": "biome lint ./recipes",
+    "test:types": "tsc",
+    "test:unit": "node --no-warnings --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=./coverage.lcov --test-reporter=spec --test-reporter-destination=stdout --experimental-test-module-mocks --import './build/snapshots.ts' -test --test-coverage-include='recipes/**/*' --test-coverage-exclude='**/*.spec.m(j|t)s' --test-coverage-lines=0.8 './packages/*/*.spec.m(j|t)s'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodejs/userland-migrations"
+  },
+  "keywords": [
+    "automation",
+    "codemod",
+    "migrations",
+    "node.js"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nodejs/userland-migrations/issues"
+  },
+  "homepage": "https://nodejs.org/learn/userland-migrations",
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.9.1",
+    "typescript": "^5.6.3"
+  },
+  "workspaces": [
+    "./recipes/*"
+  ]
+}