chore: set up initial actions & docs (#1)

Co-authored-by: Augustin Mauroy <[email protected]>
Co-authored-by: Jordan Harband <[email protected]>

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.github/dependabot.yml

@@ -0,0 +1,23 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: ci
+
+  - package-ecosystem: npm # See documentation for possible values
+    directories:
+      - / # Location of package manifests
+      - /recipies/*
+    commit-message:
+      prefix: deps
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+# For more information see: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow
+
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  lint-and-types:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [23.x]
+    steps:
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run lint
+    - run: npm run format
+    - run: npm run test:types
+
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        node:
+          - version: 23.x
+          - version: 22.x
+          # glob is not backported below 22.x
+        os:
+          - macos-latest
+          - ubuntu-latest
+          - windows-latest
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2
+    - name: Set up Node.js ${{ matrix.node.version }}
+      uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # 4.1.0
+      with:
+        node-version: ${{ matrix.node.version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run test:unit
+    - run: npm run test:e2e

.gitignore

@@ -0,0 +1,10 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Commonly ignored Node.js files
+node_modules
+npm-debug.log
+.npm
+.env.*
+
+# OSX
+.DS_Store

.nvmrc

@@ -0,0 +1 @@
+23

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+      "biomejs.biome"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "biomejs.biome",
+    "javascript.updateImportsOnFileMove.enabled": "always",
+    "typescript.updateImportsOnFileMove.enabled": "always"
+}

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# 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.
+
+> [!NOTE]
+> 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`.
+
+## Before pushing a commit
+
+A convenient superset of checks is available via `node --run pre-commit`, which automatically fixes formatting and linting issues, checks types, and runs unit and end-to-end tests. Changes resulting from this should be committed.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright Contributors to the Userland Migrations project.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.link/nodejs-official).

biome.jsonc

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "formatter": {
+    "indentStyle": "tab",
+    "lineWidth": 100
+  },
+  // Rules for the linter
+  "linter": {
+    "rules": {
+      "style": {
+        "useImportType": "error",
+        "useNodeAssertStrict": "error",
+        "useNodejsImportProtocol": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noEmptyBlock": "error",
+        "noDuplicateAtImportRules": "error",
+        "noDuplicateObjectKeys": "error"
+      },
+      "correctness": {
+        "noUnusedVariables": "error",
+        "useArrayLiterals": "off",
+        "noUnknownFunction": "error"
+      },
+      "nursery": {
+        "noEnum": "error"
+      }
+    }
+  },
+  // Language specific settings
+  "javascript": {
+    "formatter": {
+			"semicolons": "always",
+      "quoteStyle": "single",
+      "trailingCommas": "all"
+    },
+		"linter": {
+      "enabled": true
+    }
+  },
+  "json": {
+    "formatter": {
+      "enabled": false
+    }
+  },
+  // VSC specific settings
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git"
+  }
+}

build/snapshots.mts

@@ -0,0 +1,17 @@
+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`);
+}