How nodejs/userland-migrations works
Project Type and Purpose
• This is an open-source monorepo of “codemod” recipes—automated source-to-source transformation scripts—for Node.js userland code.
• Each recipe is packaged as its own small Node.js/TypeScript module (with a workflow.yaml, src/, tests/, and package.json), intended to be published to npm and run by the community via the codemod CLI.
High-Level Architecture Components
A. Developer Workstation
• Runs git clone, installs dependencies (npm install), invokes npx codemod workflow run -w .../recipes/<recipe>/workflow.yaml.
B. Codemod CLI
• External command-line tool that parses the recipe’s workflow.yaml, loads the compiled JS from src/, and orchestrates AST transformations (via ast-grep and other utilities).
C. Monorepo
• Top-level folders and files:
• .github/: CI workflows (ci.yml, codemod_publish.yml).
• recipes/: N sub-folders, each a standalone recipe/package.
• utils/src/: shared helper modules (logger, spawn-promisified, AST-grep wrappers).
• Config files (tsconfig.json, package.json, biome.jsonc, .editorconfig, etc.).
D. Continuous Integration (GitHub Actions)
• On push or PR: installs deps, compiles TS, runs per-recipe tests under recipes/*/tests, runs linting, and (on release) publishes each recipe to npm.
E. NPM Registry & Codemod Registry
• Hosts published recipe packages (@nodejs/<recipe>).
• Codemod Registry (https://codemod.link/nodejs-official) indexes these recipes for discovery by the CLI.
Relationships and Data Flows
1. Developer → Codemod CLI: issues a command pointing at a local recipe folder.
2. Codemod CLI → Monorepo/Recipe: reads workflow.yaml, dynamically imports the recipe’s dist/index.js or src/workflow.ts.
3. Recipe Module → Utils Library: calls shared functions (AST traversal, logging, child-process spawn).
4. Recipe Module → Target Codebase: applies transformations, writes patched files.
5. Monorepo → GitHub Actions: code pushed triggers CI jobs.
6. CI → NPM Registry: on tagged release, publishes each @nodejs/<recipe> package.
7. End Users → Codemod Registry → NPM Registry: discover and install published recipes without cloning the repo.
Key Architectural Patterns & Principles
• Monorepo with “package per recipe” pattern, enabling easy sharing of config and utilities.
• Declarative workflows (workflow.yaml) separate configuration from code (src/workflow.ts).
• Shared utility library for cross-recipe concerns (logging, AST helpers, testing harness).
• CI pipelines for automated build, test, and publish steps.
Putting It All Together
• Inside the recipe, show calls out to “Shared Utils.”
• At the top or bottom, illustrate “GitHub Actions” connecting the Monorepo to “NPM Registry” and “Codemod Registry.”