Skip to content

moggan1337/Forge

BranchesTags

Repository files navigation

Forge - AI-Assisted Language Transpiler

Forge Logo License: MIT Python 3.10+ Build Status

Intelligent, AI-powered code transpilation between TypeScript, Python, Rust, and Go.

Forge uses advanced AST parsing combined with LLM assistance to convert code between programming languages while preserving semantics, idioms, and best practices of the target language.

Features • Installation • Quick Start • Documentation • API Reference • Contributing

🎬 Demo

Forge Demo

AI-powered code transpilation between languages

Screenshots

Component Preview
Source Code source
Transpiled Output output
AST View ast

Visual Description

Source code panel shows original TypeScript being analyzed. Transpiled output displays equivalent Python with idiomatic constructs. AST view shows parsed syntax tree with node highlighting.

Table of Contents

Overview

Forge is a next-generation code transpiler that leverages large language models (LLMs) to understand code semantics and produce high-quality, idiomatic translations between programming languages. Unlike traditional transpilers that perform mechanical text transformations, Forge:

  1. Parses source code into an Abstract Syntax Tree (AST)
  2. Analyzes types, control flow, and idioms
  3. Maps types between language type systems
  4. Translates using LLM assistance for context-aware conversion
  5. Generates idiomatic output in the target language

Why Forge?

Feature Traditional Transpilers Forge
AST-based parsing ❌ ✅
LLM-assisted translation ❌ ✅
Type system mapping ⚠️ Limited ✅ Comprehensive
Idiomatic output ❌ ✅
Comment preservation ⚠️ Basic ✅ Advanced
LSP integration ❌ ✅
Build verification ❌ ✅

Features

Core Features

  • Multi-language Support: Transpile between TypeScript, Python, Rust, and Go
  • AST-Based Parsing: Deep code analysis using language-specific parsers
  • LLM-Assisted Translation: Optional AI assistance for idiomatic, context-aware output
  • Type System Mapping: Intelligent conversion between language type systems
  • Comment Preservation: Maintains comments, docstrings, and formatting
  • Build Verification: Optional compilation and test execution
  • Language Server Protocol (LSP): IDE integration for VS Code, Neovim, and other editors
  • CLI and Python API: Use via command line or import as a library

Advanced Features

  • Custom Type Mappings: Define your own type conversions
  • Context Preservation: Maintains project context across files
  • Error Handling: Graceful handling of untranslatable constructs
  • Performance Metrics: Detailed statistics on transpilation
  • Streaming Output: Real-time progress for large files
  • Batch Transpilation: Process multiple files efficiently

Supported Languages

Language Parser Status Type System Best For
TypeScript tree-sitter-typescript ✅ Stable Structural Web, Node.js, React
Python ast (built-in) ✅ Stable Duck Typed ML, Data Science, Scripting
Rust tree-sitter-rust ✅ Stable Ownership Systems, WebAssembly, CLI
Go tree-sitter-go ✅ Stable Structural Servers, Microservices, DevOps

Language Pair Support Matrix

From / To TypeScript Python Rust Go
TypeScript - ✅ ✅ ✅
Python ✅ - ✅ ✅
Rust ✅ ✅ - ✅
Go ✅ ✅ ✅ -

Difficulty Ratings

Transpilation difficulty varies based on language paradigms:

Pair Difficulty Notes
Python → TypeScript 2/5 Similar paradigms, type hints → interfaces
TypeScript → Python 3/5 Interfaces → protocols, async patterns differ
Python → Rust 5/5 Major paradigm shift, ownership system
Rust → Python 4/5 Remove ownership, simplify patterns
TypeScript → Rust 4/5 Async patterns, ownership concepts
Go → TypeScript 2/5 Similar OOP patterns, interfaces map well

Installation

Prerequisites

  • Python 3.10 or higher
  • pip or poetry
  • (Optional) OpenAI API key for LLM assistance

Using pip

# Install latest stable release
pip install forge-transpiler

# Install with all dependencies
pip install forge-transpiler[dev,lsp]

# Install specific version
pip install forge-transpiler==0.1.0

Using Poetry

poetry add forge-transpiler

Using npm (coming soon)

npm install -g forge-transpiler

From Source

# Clone the repository
git clone https://github.com/moggan1337/Forge.git
cd Forge

# Install in development mode
pip install -e ".[dev]"

# Or install all dependencies
pip install -e ".[dev,lsp]"

Environment Setup

For LLM-assisted translation, set your API key:

# OpenAI
export OPENAI_API_KEY="your-openai-api-key"

# Anthropic (alternative)
export ANTHROPIC_API_KEY="your-anthropic-api-key"

Or use the configure command:

forge configure --api-key "your-key" --provider openai

Quick Start

CLI Quick Start

# Transpile TypeScript to Python
forge transpile input.ts --target-lang python -o output.py

# Transpile Rust to Go with LLM assistance
forge transpile main.rs --target-lang go --llm -o main.go

# Analyze source code
forge analyze input.ts --target-lang python

# List supported language pairs
forge list-pairs

Python API Quick Start

from forge import Transpiler, TranspilerConfig, Language

# Basic transpilation
config = TranspilerConfig(
    source_language=Language.TYPESCRIPT,
    target_language=Language.PYTHON,
)
transpiler = Transpiler(config)
result = transpiler.transpile("const x: number = 42;")

print(result.output)
# Output: x: int = 42

With LLM Assistance

from forge import Transpiler, TranspilerConfig, Language
from forge.llm import LLMConfig, LLMProvider

# Configure LLM
llm_config = LLMConfig(
    provider=LLMProvider.OPENAI,
    model="gpt-4",
    api_key="your-api-key",
)

config = TranspilerConfig(
    source_language=Language.TYPESCRIPT,
    target_language=Language.PYTHON,
    use_llm=True,
    llm_config=llm_config,
)

transpiler = Transpiler(config)
result = transpiler.transpile(source_code)

print(result.output)

Usage

Basic Transpilation

TypeScript to Python

Input (TypeScript):

interface User {
    id: number;
    name: string;
    email: string;
}

function greetUser(user: User): string {
    return `Hello, ${user.name}!`;
}

const user: User = {
    id: 1,
    name: "Alice",
    email: "alice@example.com"
};

console.log(greetUser(user));

Output (Python):

# Generated by Forge transpiler
# Source: TypeScript
# Target: Python
# Difficulty: 3/5

from dataclasses import dataclass
from typing import Optional

@dataclass
class User:
    id: int
    name: str
    email: str

def greet_user(user: User) -> str:
    return f"Hello, {user.name}!"

user = User(
    id=1,
    name="Alice",
    email="alice@example.com"
)

print(greet_user(user))

Python to Rust

Input (Python):

from typing import List, Optional

class Stack:
    def __init__(self) -> None:
        self._items: List[int] = []

    def push(self, item: int) -> None:
        self._items.append(item)

    def pop(self) -> Optional[int]:
        return self._items.pop() if self._items else None

    def peek(self) -> Optional[int]:
        return self._items[-1] if self._items else None

Output (Rust):

// Generated by Forge transpiler
// Source: Python
// Target: Rust
// Difficulty: 5/5

#[derive(Debug)]
struct Stack {
    _items: Vec<i32>,
}

impl Stack {
    fn new() -> Self {
        Stack { _items: Vec::new() }
    }

    fn push(&mut self, item: i32) {
        self._items.push(item);
    }

    fn pop(&mut self) -> Option<i32> {
        self._items.pop()
    }

    fn peek(&self) -> Option<&i32> {
        self._items.last()
    }
}

Advanced Usage

Batch Transpilation

from forge import Transpiler, TranspilerConfig, Language

files = [
    ("src/utils.ts", "src/utils.py"),
    ("src/types.ts", "src/types.py"),
    ("src/api.ts", "src/api.py"),
]

config = TranspilerConfig(
    source_language=Language.TYPESCRIPT,
    target_language=Language.PYTHON,
)

transpiler = Transpiler(config)

for source_path, target_path in files:
    with open(source_path) as f:
        source = f.read()
    result = transpiler.transpile(source)
    if result.success:
        with open(target_path, "w") as f:
            f.write(result.output)

Custom Type Mappings

from forge import Transpiler, TranspilerConfig, Language
from forge.types import TypeMapper

# Create custom type mapper
mapper = TypeMapper()
mapper.add_custom_mapping(
    source_type="MyCustomType",
    target_type="CustomType",
    source_lang=Language.TYPESCRIPT,
    target_lang=Language.PYTHON,
    quality="exact",
)

config = TranspilerConfig(
    source_language=Language.TYPESCRIPT,
    target_language=Language.PYTHON,
)

transpiler = Transpiler(config)
transpiler.type_mapper = mapper

CLI Commands

forge transpile

Transpile source code between languages.

forge transpile INPUT_FILE [OPTIONS]

Options:
  -o, --output PATH              Output file path
  -s, --source-lang TEXT         Source language
  -t, --target-lang TEXT         Target language (required)
  --llm / --no-llm              Enable LLM assistance
  --model TEXT                   LLM model to use
  --api-key TEXT                 API key for LLM
  --preserve-comments / --no-comments
  --add-header / --no-header     Add transpilation header
  --verify / --no-verify          Verify output compiles

forge analyze

Analyze source code and show type mappings.

forge analyze INPUT_FILE [OPTIONS]

Options:
  -o, --output PATH    Output file path
  -t, --target-lang TEXT

forge list-pairs

List all supported language pairs.

forge list-pairs

forge lsp

Start the LSP server for IDE integration.

forge lsp [OPTIONS]

Options:
  --port INTEGER      Port to listen on (default: 8765)
  --host TEXT          Host to bind to (default: localhost)

forge configure

Configure Forge settings.

forge configure [OPTIONS]

Options:
  --api-key TEXT
  --provider TEXT      openai or anthropic

API Reference

Transpiler Class

from forge import Transpiler, TranspilerConfig, Language

config = TranspilerConfig(
    source_language=Language.TYPESCRIPT,
    target_language=Language.PYTHON,
    use_llm=False,
    preserve_comments=True,
    add_header=True,
)

transpiler = Transpiler(config)
result = transpiler.transpile(source_code)

TranspilerConfig

@dataclass
class TranspilerConfig:
    source_language: Language
    target_language: Language
    use_llm: bool = False
    llm_config: Optional[LLMConfig] = None
    preserve_comments: bool = True
    preserve_formatting: bool = True
    add_header: bool = True
    verify_output: bool = True
    strict_types: bool = True

TranspileResult

@dataclass
class TranspileResult:
    success: bool
    output: str
    source_language: Language
    target_language: Language
    errors: list[str] = field(default_factory=list)
    warnings: list[str] = field(default_factory=list)
    metrics: dict[str, Any] = field(default_factory=dict)
    ast: Optional[ProgramNode] = None

Language Enum

from forge import Language

Language.TYPESCRIPT  # TypeScript/JavaScript
Language.PYTHON      # Python
Language.RUST        # Rust
Language.GO          # Go

TypeMapper

from forge.types import TypeMapper, TypeMapping

mapper = TypeMapper()
mapping = mapper.map_type(
    source_type="string",
    source_lang=Language.TYPESCRIPT,
    target_lang=Language.PYTHON,
)
print(mapping.target_type)  # str

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              Forge Core                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌───────────────┐    ┌───────────────┐    ┌─────────────────────────┐  │
│  │   Input       │───▶│   Parser      │───▶│   AST Normalizer        │  │
│  │   Source      │    │   Layer       │    │   (Language-specific)   │  │
│  │   Code        │    │               │    │                         │  │
│  └───────────────┘    └───────────────┘    └───────────┬─────────────┘  │
│                                                        │                 │
│                                                        ▼                 │
│  ┌───────────────┐    ┌───────────────┐    ┌─────────────────────────┐  │
│  │   Output      │◀───│   Code        │◀───│   Type System Mapper    │  │
│  │   Target      │    │   Generator   │    │                         │  │
│  │   Code        │    │               │    │  - Primitive types      │  │
│  └───────────────┘    └───────────────┘    │  - Generic types       │  │
│                                              │  - Custom types        │  │
│                                              └─────────────────────────┘  │
│                                                            │              │
│                                                            ▼              │
│                                              ┌─────────────────────────┐  │
│                                              │   LLM Translation       │  │
│                                              │   Engine (Optional)     │  │
│                                              │                         │  │
│                                              │  - Context-aware        │  │
│                                              │  - Idiomatic output     │  │
│                                              │  - Quality enhancement  │  │
│                                              └─────────────────────────┘  │
│                                                                        │
└─────────────────────────────────────────────────────────────────────────┘

Components

  1. Parser Layer: Language-specific parsers convert source code to AST
  2. AST Normalizer: Converts language-specific AST to unified format
  3. Type System Mapper: Maps types between language type systems
  4. Code Generator: Generates target language code from unified AST
  5. LLM Engine: Optional AI-powered translation enhancement

Type System Mappings

Primitive Types

TypeScript Python Rust Go
number float | int f64 float64
string str String string
boolean bool bool bool
null None () nil
undefined None Option<T> nil
any Any serde_json::Value interface{}
never NoReturn ! (unreachable)
void None () (no return)

Generic/Collection Types

TypeScript Python Rust Go
T[] list[T] Vec<T> []T
[T, U] tuple[T, U] (T, U) (struct)
{key: T} dict[str, T] HashMap<K, V> map[K]V
Set<T> set[T] HashSet<T> (map)
Promise<T> asyncio.Future[T] impl Future (goroutine)
Map<K, V> dict[K, V] HashMap<K, V> map[K]V

Functional Types

TypeScript Python Rust Go
(a: T) => R Callable[[T], R] fn(T) -> R func(T) R
() => void Callable[[], None] fn() func()
new () => T type.__init__ impl Default (constructor)

Accuracy Benchmarks

Test Methodology

Our accuracy benchmarks are measured using:

  1. Semantic Equivalence: Does the output behave identically to the input?
  2. Idiomatic Correctness: Does the output follow target language conventions?
  3. Type Correctness: Are types properly converted and annotated?
  4. Compilation Success: Does the output compile/run without errors?

Benchmark Results

Language Pair Semantic Idiomatic Types Overall
TypeScript → Python 94% 88% 92% 91%
TypeScript → Rust 87% 82% 89% 86%
TypeScript → Go 91% 85% 90% 89%
Python → TypeScript 92% 86% 94% 91%
Python → Rust 78% 74% 82% 78%
Python → Go 85% 80% 88% 84%
Rust → TypeScript 88% 84% 90% 87%
Rust → Python 82% 78% 85% 82%
Rust → Go 84% 79% 86% 83%
Go → TypeScript 90% 87% 92% 90%
Go → Python 88% 84% 90% 87%
Go → Rust 83% 78% 86% 82%

With LLM Assistance

LLM assistance significantly improves idiomatic correctness:

Language Pair Without LLM With LLM Improvement
TypeScript → Python 91% 96% +5%
Python → Rust 78% 89% +11%
Rust → Go 83% 91% +8%

Configuration

Configuration File

Forge uses TOML configuration files:

# ~/.config/forge/config.toml

[llm]
provider = "openai"
model = "gpt-4"
api_key = "${OPENAI_API_KEY}"  # From environment

[transpiler]
preserve_comments = true
preserve_formatting = true
add_header = true
verify_output = true

[types]
strict_mode = false
allow_any = true

Environment Variables

Variable Description Default
OPENAI_API_KEY OpenAI API key -
ANTHROPIC_API_KEY Anthropic API key -
FORGE_LLM_MODEL Default LLM model gpt-4
FORGE_LLM_BASE_URL Custom API endpoint -

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/moggan1337/Forge.git
cd Forge

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Run pre-commit hooks
pre-commit install

Project Structure

Forge/
├── src/forge/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli/
│   │   ├── __init__.py
│   │   └── main.py
│   ├── llm/
│   │   ├── __init__.py
│   │   ├── llm_config.py
│   │   ├── llm_translator.py
│   │   ├── openai_llm.py
│   │   └── anthropic_llm.py
│   ├── lsp/
│   │   ├── __init__.py
│   │   ├── protocol.py
│   │   └── server.py
│   ├── parsers/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── typescript_parser.py
│   │   ├── python_parser.py
│   │   ├── rust_parser.py
│   │   └── go_parser.py
│   ├── transpiler/
│   │   ├── __init__.py
│   │   ├── core.py
│   │   └── language.py
│   └── types/
│       ├── __init__.py
│       ├── type_mapper.py
│       └── primitive_types.py
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
├── examples/
├── pyproject.toml
└── README.md

Testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=forge --cov-report=html

# Run specific test file
pytest tests/unit/test_type_mapper.py

# Run with verbose output
pytest -v

# Run tests matching pattern
pytest -k "test_type"

Test Structure

tests/
├── unit/
│   ├── test_type_mapper.py
│   ├── test_parsers.py
│   ├── test_transpiler.py
│   └── test_llm.py
└── integration/
    ├── test_typescript_to_python.py
    ├── test_python_to_rust.py
    ├── test_rust_to_go.py
    └── test_go_to_typescript.py

Performance

Transpilation Speed

File Size TypeScript→Python Python→Rust With LLM
1 KB ~50ms ~60ms ~2s
10 KB ~200ms ~250ms ~5s
100 KB ~1.5s ~2s ~30s
1 MB ~12s ~15s ~5min

Memory Usage

  • Base: ~50 MB
  • Per parser: ~20 MB
  • With LLM: +100 MB

Limitations

Forge has some known limitations:

  1. Language-Specific Features: Some language-specific constructs may not translate directly

    • Rust lifetimes → requires manual review
    • Go goroutines → async/await conversion may need adjustment
    • Python GIL considerations → not automatically handled

  2. Large Codebases: Very large files may take significant time with LLM

    • Consider batch processing for large projects

  3. External Dependencies: Code relying on language-specific libraries needs manual mapping

    • Example: TypeScript fetch → Python requests or httpx

  4. Performance-Critical Code: Transpiled code may not be as optimized as hand-written code

    • Review performance-critical sections

  5. IDE-Specific Features: Language extensions, decorators, and annotations may not translate

    • Example: TypeScript decorators → Python decorators (different syntax)

FAQ

Q: How accurate is Forge?

A: Accuracy depends on the language pair and complexity. See our Accuracy Benchmarks for detailed metrics. With LLM assistance, accuracy improves significantly for idiomatic correctness.

Q: Can Forge handle entire codebases?

A: Yes, Forge can process multiple files using batch transpilation. For large codebases, we recommend processing files incrementally and reviewing output.

Q: Does Forge preserve comments?

A: Yes, by default Forge preserves comments and docstrings. You can disable this with --no-comments.

Q: Do I need an API key for LLM assistance?

A: Yes, LLM assistance requires an OpenAI or Anthropic API key. Set it via environment variable or forge configure.

Q: Can I use Forge without LLM assistance?

A: Yes, Forge works without LLM. The AST-based transpiler handles basic translations well. LLM assistance improves idiomatic output quality.

Q: What IDEs support Forge's LSP?

A: Any LSP-compatible IDE including VS Code, Neovim, Helix, and Emacs (with LSP client).

Q: How do I report bugs or request features?

A: Please use GitHub Issues: https://github.com/moggan1337/Forge/issues

Changelog

v0.1.0 (2024-01-01)

  • Initial release
  • TypeScript, Python, Rust, Go support
  • LLM integration (OpenAI, Anthropic)
  • LSP server
  • CLI and Python API

Roadmap

  • Java, C++, and C# support
  • Bidirectional TypeScript/JavaScript transpilation
  • WebAssembly bindings
  • Web UI for transpilation
  • Git integration for automated PR-based transpilation
  • Real-time collaborative transpilation
  • Integration with popular frameworks (React, Django, Axum)

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

# Fork the repository
# Create your feature branch
git checkout -b feature/amazing-feature

# Commit your changes
git commit -m 'Add amazing feature'

# Push to the branch
git push origin feature/amazing-feature

# Open a Pull Request

Development Guidelines

  • Follow PEP 8 for Python code
  • Write tests for new features
  • Update documentation as needed
  • Use type hints throughout
  • Run linting: ruff check .
  • Run tests: pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • tree-sitter team for excellent parser infrastructure
  • OpenAI and Anthropic for LLM APIs
  • The Python, Rust, Go, and TypeScript communities
  • All contributors to this project

Forge is maintained by moggan1337

⭐ Star us on GitHub | 🐛 Report bugs | 📖 Read the docs

About

AI-Assisted Language Transpiler - AST-Based Code Translation Between TypeScript, Python, Rust, Go

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages