# nodejs/userland-migrations architecture

> Architecture diagram of the GitHub repository nodejs/userland-migrations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nodejs/userland-migrations
- Repository: https://github.com/nodejs/userland-migrations

## Overview

##### 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.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users and Tools
    Developer["Developer Workstation"]:::external
    CLI["Codemod CLI"]:::external

    Developer -->|"run npx codemod workflow run"| CLI

    %% Monorepo Container
    subgraph "Monorepo Repository" 
        direction TB
        MonorepoRoot["/"]:::code
        ConfigPkg["package.json"]:::code
        ConfigTS["tsconfig.json"]:::code
        CI_CI["ci.yml"]:::ci
        CI_Pub["codemod_publish.yml"]:::ci

        subgraph "Recipes" 
            direction TB
            RecipeA["correct-ts-specifiers"]:::code
            RecipeWF["create-require-from-path: workflow.yaml"]:::code
            TestsDir["tests/"]:::code
        end

        subgraph "Shared Utils" 
            direction TB
            UtilsAST["ast-grep"]:::code
            UtilsLog["logger.ts"]:::code
            UtilsSpawn["spawn-promisified.ts"]:::code
        end
    end

    %% CI and Registries
    GHActions["GitHub Actions"]:::ci
    NPM["NPM Registry"]:::external
    CodemodReg["Codemod Registry"]:::external

    %% Data Flows
    CLI -->|"loads workflow"| RecipeA
    RecipeA -->|"reads workflow.yaml"| RecipeWF
    RecipeA -->|"calls shared utilities"| UtilsAST
    RecipeA -->|"calls shared utilities"| UtilsLog
    RecipeA -->|"calls shared utilities"| UtilsSpawn
    RecipeA -->|"runs tests"| TestsDir
    MonorepoRoot -->|"push/PR triggers"| GHActions
    GHActions -->|"publish on tag"| NPM
    GHActions -->|"index recipes"| CodemodReg

    %% Click Events
    click MonorepoRoot "https://github.com/nodejs/userland-migrations/tree/main//"
    click RecipeA "https://github.com/nodejs/userland-migrations/tree/main/recipes/correct-ts-specifiers/"
    click RecipeWF "https://github.com/nodejs/userland-migrations/blob/main/recipes/create-require-from-path/workflow.yaml"
    click TestsDir "https://github.com/nodejs/userland-migrations/tree/main/recipes/*/tests/"
    click UtilsAST "https://github.com/nodejs/userland-migrations/tree/main/utils/src/ast-grep/"
    click UtilsLog "https://github.com/nodejs/userland-migrations/blob/main/utils/src/logger.ts"
    click UtilsSpawn "https://github.com/nodejs/userland-migrations/blob/main/utils/src/spawn-promisified.ts"
    click CI_CI "https://github.com/nodejs/userland-migrations/blob/main/.github/workflows/ci.yml"
    click CI_Pub "https://github.com/nodejs/userland-migrations/blob/main/.github/workflows/codemod_publish.yml"
    click ConfigPkg "https://github.com/nodejs/userland-migrations/blob/main/package.json"
    click ConfigTS "https://github.com/nodejs/userland-migrations/blob/main/tsconfig.json"
    click Developer "https://github.com/nodejs/userland-migrations/tree/main/n/a"
    click CLI "https://github.com/nodejs/userland-migrations/tree/main/n/a"
    click GHActions "https://github.com/nodejs/userland-migrations/tree/main/n/a"
    click NPM "https://github.com/nodejs/userland-migrations/tree/main/n/a"
    click CodemodReg "https://github.com/nodejs/userland-migrations/tree/main/n/a"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#000,stroke-width:1px
```
