Contributing to Codemod

December 24, 2025 · View on GitHub

Thank you for your interest in contributing to Codemod! This guide will help you get started.

This repository contains Codemod's open-source tooling: the CLI and core libraries that power code migrations, framework upgrades, and large-scale changes. We welcome contributions from the community to help make code modernization accessible to everyone.

Note: This repository focuses on the open-source CLI and core libraries. Codemod platform (web app) is part of Codemod's enterprise features and is maintained by the Codemod core team.

Table of Contents

Code of Conduct

This project follows our Code of Conduct. By participating, you are expected to uphold this code.

Ways to Contribute

We welcome contributions in several areas:

📚 Documentation

Help improve our documentation (docs/) to make Codemod more accessible:

  • Documentation improvements – Fix typos & inaccuracies, clarify explanations, add examples
  • Tutorials and guides – Share your knowledge with the community

🛠️ Tooling

We especially welcome bug fixes and moderate improvements to existing tooling. Drastic changes to user experience or major feature additions typically require broader alignment, as they affect many users and workflows—these are often discussed with the core team internally first.

If you have a cool new idea or want to explore bigger changes, please ping us in the community channel before submitting a PR. We’d love to chat and help shape the direction together!

Help improve the core tools that power Codemod:

CLI (crates/cli/)

The Rust-based CLI is the heart of Codemod. Contributions welcome for:

  • New features and commands
  • Performance improvements
  • Bug fixes
  • Better error messages and user experience

JSSG & workflows (crates/core/, crates/codemod-sandbox/)

The workflow engine and JavaScript ast-grep execution:

  • Workflow engine (crates/core/) – Core execution engine improvements
  • JSSG execution (crates/codemod-sandbox/) – JavaScript/TypeScript codemod execution
  • Workflow features – New step types, better error handling, performance optimizations

Codemod MCP (crates/mcp/)

The Model Context Protocol server for AI-powered codemod creation:

  • MCP tools – New analysis and transformation tools
  • AI improvements – Improvements to AI-powered codemod generation
  • IDE support – Better integration with AI-powered IDEs

📦 Registry

The best way to contribute to the registry is by publishing codemods:

  • Publish codemods – Share your transformations with the community
  • Improve existing codemods – Submit improvements to community codemods
  • Document codemods – Help others discover and use codemods effectively

Learn more about publishing codemods in the Registry documentation.

Explore Codemod Registry ->

Getting Started

Prerequisites

  • Node.js >= 24.x
  • pnpm >= 10.x
  • Rust (latest stable) – for CLI and core development

Development Setup

Run Documentation Local Server

# Install Mintlify CLI
npm i -g mint

# Run documentation site (in docs/)
mint dev

Install Dependencies

# Install Node.js dependencies
pnpm install

# Rust dependencies are automatically managed by Cargo
# No separate installation needed

Build the Project

# Build the Rust CLI (from project root)
cargo build --release

# Or build specific crates
cargo build --release --package codemod
cargo build --release --package codemod-sandbox

Test the CLI

# Build the CLI
cargo build --release --package codemod --bin codemod

# Test CLI commands
./target/release/codemod --help
./target/release/codemod workflow --help
./target/release/codemod jssg --help

Project Structure

This monorepo contains the open-source Codemod CLI and core libraries:

Core Components

  • crates/cli/ – Main Rust-based CLI
  • crates/core/ – Workflow engine (butterflow-core)
  • crates/codemod-sandbox/ – JavaScript/TypeScript execution sandbox for JSSG
  • crates/mcp/ – Model Context Protocol server for AI-powered codemod creation
  • crates/models/ – Workflow models and data structures
  • crates/runners/ – Container runners (Docker, Podman)
  • crates/state/ – Workflow state management
  • crates/telemetry/ – Telemetry and analytics

Semantic Analysis

  • crates/language-core/ – Language provider core abstractions
  • crates/language-javascript/ – JavaScript/TypeScript semantic analysis
  • crates/language-python/ – Python semantic analysis
  • crates/semantic-factory/ – Semantic analysis factory
  • crates/llrt-capabilities/ – LLRT capabilities module

Testing

  • crates/testing-utils/ – Shared testing utilities for Rust crates

Shared Packages

  • packages/jssg-types/ – TypeScript types for JSSG codemods
  • packages/jssg-utils/ – Utility functions for JSSG codemods
  • packages/tsconfig/ – Shared TypeScript configuration
  • packages/codemod-utils/ – Public utilities for codemod authors
  • packages/utilities/ – Internal shared utilities

Applications

  • docs/ – Documentation website (Mintlify)

Making Changes

Development Workflow

  1. Make your changes in the appropriate directory
  2. Write or update tests for your changes
  3. Run tests to ensure everything passes
  4. Lint your code: 
    # TypeScript/JavaScript
pnpm lint
pnpm format

# Rust
cargo fmt --check
cargo clippy
  5. Format your code: 
    # TypeScript/JavaScript
pnpm lint:fix
pnpm format:fix

# Rust
cargo fmt

Code Style

  • TypeScript/JavaScript: We use oxlint for linting and oxfmt for formatting
  • Rust: We use rustfmt (configured in rustfmt.toml) and clippy
  • Documentation: Follow existing patterns and use clear, concise language
  • Write clear, self-documenting code
  • Add comments for complex logic

Testing

Run Tests

# Run all Rust tests
cargo test

# Run tests for a specific crate
cargo test --package codemod-sandbox
cargo test --package butterflow-core

Writing Tests

  • Write tests for new features and bug fixes
  • Aim for good test coverage
  • Use descriptive test names
  • Test both happy paths and edge cases
  • For CLI changes, test the actual command execution

Testing CLI Changes

# Build the CLI
cargo build --release --package codemod --bin codemod

# Test a command
./target/release/codemod workflow validate -w path/to/workflow.yaml
./target/release/codemod jssg run script.js --target ./test-dir

Submitting Changes

Before Submitting

  1. Update documentation if you've changed functionality
  2. Add changelog entries if applicable
  3. Ensure all tests pass
  4. Ensure linting passes
  5. Rebase on latest main: 
    git fetch upstream
git rebase upstream/main

Commit Messages

We use Conventional Commits:

  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • refactor: for code refactoring
  • test: for test changes
  • chore: for maintenance tasks
  • perf: for performance improvements

Examples:

feat(cli): add support for custom workflow paths
fix(jssg): handle edge case in TypeScript parsing
docs: update CLI reference with new commands

Pull Request Process

  1. Push your branch to your fork:

    git push origin feature/your-feature-name

  2. Create a Pull Request on GitHub:

    • Use a clear, descriptive title
    • Fill out the PR template
    • Link any related issues
    • Describe what changes you made and why

  3. Respond to feedback:

    • Address review comments
    • Make requested changes
    • Keep the discussion constructive

  4. Sign the CLA: You'll be asked to sign our Contributor License Agreement when you create your first PR.

PR Checklist

  • Code follows the project's style guidelines
  • Tests pass locally
  • Documentation updated (if needed)
  • Commit messages follow Conventional Commits
  • Changes are focused and atomic
  • No breaking changes (or clearly documented)

Contributing to Specific Areas

CLI Development

The CLI is written in Rust. Key areas:

  • Commands (crates/cli/src/commands/) – Add new commands or improve existing ones
  • Workflow execution (crates/cli/src/workflow_runner.rs) – Workflow execution logic
  • Engine integration (crates/cli/src/engine.rs) – Integration with execution engines

Workflow Engine

The workflow engine (crates/core/) orchestrates multi-step codemod execution:

  • Execution logic – How workflows are parsed and executed
  • Step types – Support for new step types
  • Error handling – Better error messages and recovery

JSSG

JavaScript ast-grep execution (crates/codemod-sandbox/):

  • Execution engine – JavaScript/TypeScript code execution
  • Module resolution – Better handling of imports and dependencies
  • TypeScript support – Enhanced TypeScript parsing and transformation

Documentation

Documentation is in docs/:

  • MDX files – Documentation content
  • Examples – Code examples and snippets
  • Images – Screenshots and diagrams

Getting Help

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

Thank You! 🎉

Thank you for contributing to Codemod! Your contributions help make code modernization accessible to everyone. Whether you're fixing a typo, adding a feature, or publishing a codemod to the registry, every contribution makes a difference.