morph-cli 0.1.0

AST-based codebase migration and codemod tool for JavaScript and TypeScript projects.
Documentation 
# morph-cli

> Fast AST-based codebase migration tool for JavaScript and TypeScript projects.

`morph-cli` helps modernize large codebases using structured AST transforms, safe dry-runs, rollback support, migration planning, review workflows, and incremental analysis.

Built for developers who want safer large-scale migrations without relying on fragile regex replacements.

---

## Features

### Codebase Migrations
- CommonJS → ESM
- JavaScript → TypeScript
- React class components → hooks
- Express → Fastify
- Tailwind modernization foundations

### Safety & Review
- Dry-run by default
- Interactive review mode
- Rollback support
- Migration checkpoints
- Confidence scoring
- Verification mode
- Replay support

### Project Intelligence
- Framework detection
- Dependency analysis
- Workspace/monorepo support
- Migration planner
- Recipe recommendations
- Modernization scoring

### Developer Experience
- Incremental caching
- Watch mode
- Presets & profiles
- Execution reports
- Shell completions
- Library/API mode
- Local dashboard foundation

---

# Why morph-cli?

Large migrations are painful.

Most migration tooling:
- relies on regex replacements
- breaks formatting
- lacks rollback support
- provides poor visibility into risky changes

`morph-cli` focuses on:
- AST-based transforms
- safety-first workflows
- explainable migrations
- incremental adoption
- scalable repository analysis

---

# Installation

## Cargo

```bash
cargo install morph-cli

From Source

git clone https://github.com/s0r0j/morph-cli.git
cd morph-cli
cargo build --release

Binary:

./target/release/morph

Quick Start

Scan a project

morph scan .

Generate migration recommendations

morph plan .

Run a dry-run migration

morph run commonjs-to-esm .

Apply changes

morph run commonjs-to-esm . --write

Review changes interactively

morph run commonjs-to-esm . --review

Verify migration output

morph verify

Rollback a migration

morph rollback <session-id>

Example Workflow

# Analyze repository
morph scan .

# Generate migration plan
morph plan .

# Run migration safely
morph run commonjs-to-esm . --review

# Verify results
morph verify

# Export report
morph run commonjs-to-esm . --export-report report.json

Supported Recipes

Recipe Description
commonjs-to-esm Convert CommonJS modules to ESM
js-to-ts Migrate JavaScript projects to TypeScript
react-class-to-hooks Convert React class components to hooks
express-to-fastify Migrate Express applications to Fastify

Safety Features

morph-cli is designed to be conservative by default.

Features include:

  • Dry-run execution
  • Confidence scoring
  • Verification checks
  • Rollback support
  • Review mode
  • Risk detection
  • Execution safeguards
  • Incremental checkpoints

Unsafe or unsupported patterns are skipped with warnings instead of being forcefully rewritten.

Monorepo Support

morph-cli supports:

  • npm workspaces
  • pnpm workspaces
  • yarn workspaces

You can scope migrations to specific packages:

morph run commonjs-to-esm . --package api

Presets

Built-in migration presets:

morph preset list

Examples:

  • modern-node
  • typescript-adoption
  • react-modernization

Reports & Sessions

morph-cli stores:

  • migration sessions
  • dry-run snapshots
  • scan summaries
  • validation reports

Useful commands:

morph sessions
morph history
morph scans
morph dry-runs

Watch Mode

Incrementally analyze repositories during development:

morph watch

Configuration

Example morph-cli.toml:

dry_run_default = true

excluded_paths = [
  "dist",
  "build",
  "node_modules"
]

[profiles.safe]
review = true
allow_risky = false

[profiles.aggressive]
review = false
allow_risky = true

Philosophy

morph-cli is built around a few core principles:

  • AST-based transforms over regex hacks
  • Conservative migrations over risky rewrites
  • Explainable automation
  • Safe incremental modernization
  • Human review when confidence is low

Project Status

morph-cli is currently under active development.

Some advanced framework patterns and ecosystem edge cases may still require manual migration work.

Always review important migrations before deploying to production.

Roadmap

Planned areas of improvement:

  • Better transform coverage
  • Real-world repository validation
  • Stronger semantic verification
  • Plugin runtime support
  • AI-assisted migration suggestions
  • Expanded ecosystem recipes

Contributing

Contributions are welcome.

Before contributing:

  • keep changes focused
  • avoid broad unrelated refactors
  • preserve existing behavior where possible

License

MIT License

Author

Built by Shreyaj Dinesh

GitHub: https://github.com/s0r0j