Meta Convert Guide

Language Conversion Guide

Comprehensive patterns and strategies for converting code between programming languages.

Quick Navigation

Examples

Reference Guides

Gotchas

When to Use This Skill

• Converting code from one language to another
• Planning a language migration
• Understanding conversion challenges between languages
• Looking up type mappings or idiom translations
• Referencing error handling, concurrency, or async patterns across languages
• Learning about gotchas when converting between specific language families

This Skill Does NOT Cover

• Creating new conversion skills (see meta-convert-dev)
• Language tutorials (see lang-*-dev skills)
• Runtime interop/FFI (see language-specific interop skills)

Related Skills

• meta-convert-dev - For creating new convert-X-Y skills
• convert-* skills - Language-pair specific conversion skills

Core Conversion Methodology

The APTV Workflow

Every conversion follows: Analyze → Plan → Transform → Validate

┌─────────────────────────────────────────────────────────────┐
│                    CONVERSION WORKFLOW                       │
├─────────────────────────────────────────────────────────────┤
│  1. ANALYZE    │  Understand source code structure          │
│                │  • Parse and identify components            │
│                │  • Map dependencies                         │
│                │  • Identify language-specific patterns      │
├─────────────────────────────────────────────────────────────┤
│  2. PLAN       │  Design the target architecture            │
│                │  • Create type mapping table                │
│                │  • Identify idiom translations              │
│                │  • Plan module/package structure            │
├─────────────────────────────────────────────────────────────┤
│  3. TRANSFORM  │  Convert code systematically               │
│                │  • Types and interfaces first               │
│                │  • Core logic second                        │
│                │  • Adopt target idioms (don't transliterate)│
├─────────────────────────────────────────────────────────────┤
│  4. VALIDATE   │  Verify functional equivalence             │
│                │  • Run original tests against new code      │
│                │  • Property-based testing for edge cases    │
│                │  • Performance comparison if relevant       │
└─────────────────────────────────────────────────────────────┘

See also: FORMS.md for APTV phase checklists

Analyze Phase

Before writing any target code:

1. Parse the source - Understand structure, not just syntax
2. Identify components:
   • Types/interfaces/classes
   • Functions/methods
   • Module boundaries
   • External dependencies
3. Note language-specific features:
   • Generics usage
   • Error handling patterns
   • Async patterns
   • Memory management approach

Plan Phase

Create explicit mappings before transforming. Use the templates in FORMS.md:

## Type Mapping Table

| Source (TypeScript) | Target (Rust)      | Notes             |
| ------------------- | ------------------ | ----------------- |
| `string`            | `String` / `&str`  | Owned vs borrowed |
| `number`            | `i32` / `f64`      | Specify precision |
| `T[]`               | `Vec<T>`           | Owned collection  |
| `T \| null`         | `Option<T>`        | Nullable handling |
| `Promise<T>`        | `Future<Output=T>` | Async handling    |

See also: reference/type-system-mapping.md for complete mappings

Transform Phase

Golden Rule: Adopt target idioms, don't write "Source code in Target syntax"

// Source: TypeScript
function findUser(id: string): User | null {
  const user = users.find((u) => u.id === id);
  return user || null;
}

// BAD: Transliterated (TypeScript in Rust clothing)
fn find_user(id: String) -> Option<User> {
    let user = users.iter().find(|u| u.id == id);
    match user {
        Some(u) => Some(u.clone()),
        None => None,
    }
}

// GOOD: Idiomatic Rust
fn find_user(id: &str) -> Option<&User> {
    users.iter().find(|u| u.id == id)
}

See also: examples/idiom-translation.md for more patterns

Validate Phase

1. Functional equivalence: Same inputs → same outputs
2. Edge case coverage: Property-based tests
3. Error behavior: Same error conditions trigger appropriately
4. Performance baseline: Comparable or better performance

See also: FORMS.md for testing strategy checklist

The 8 Pillars of Conversion

Every comprehensive conversion addresses these domains:

The 9th Pillar: Dev Workflow

For REPL-centric languages (Clojure, Elixir, Haskell), add:

See also: reference/dev-workflow-repl.md

Quick Reference Tables

Type System Comparison

See also: tables/quick-reference.md for complete tables

Error Model Comparison

See also: reference/error-handling.md

Concurrency Model Comparison

See also: reference/concurrency.md

Common Conversion Patterns

Null Handling

See also: examples/idiom-translation.md

Error Propagation

See also: examples/error-handling.md

Collection Operations

See also: tables/quick-reference.md

Decision Trees

When to Clone vs Borrow

Is the data needed after the function returns?
├─ NO → Borrow (&T)
└─ YES → Does caller need to keep using it?
         ├─ NO → Move (T)
         └─ YES → Clone (.clone())

See also: FORMS.md for complete decision trees

GC → Ownership Strategy

Is this data shared across components?
├─ YES → Consider Arc<T> or Rc<T>
└─ NO → Single owner, use moves

Is this data mutated by multiple parts?
├─ YES → Arc<Mutex<T>> or channels
└─ NO → Immutable borrows (&T)

See also: reference/memory-ownership.md

Common Pitfalls

See also: reference/gotchas/by-family.md

Testing Conversions

Testing Pyramid

         ┌───────────────┐
         │  Integration  │  Same API behavior
         └───────────────┘
    ┌─────────────────────────┐
    │    Property-Based       │  Invariants hold
    └─────────────────────────┘
 ┌───────────────────────────────────┐
 │           Unit Tests              │  Logic matches
 └───────────────────────────────────┘
┌─────────────────────────────────────────┐
│        Input/Output Comparison          │  Golden tests
└─────────────────────────────────────────┘

Golden Testing

1. Generate test cases from original implementation
2. Save as JSON fixtures
3. Run converted code against same inputs
4. Compare outputs

See also: FORMS.md for testing checklist

Language-Specific Quick Links

Converting FROM

Converting TO

References

Related Skills

• meta-convert-dev - For creating new convert-X-Y skills
• convert-typescript-rust - TypeScript → Rust conversion
• convert-python-rust - Python → Rust conversion
• convert-golang-rust - Go → Rust conversion

Language Skills

For language-specific fundamentals (not conversion):

• lang-typescript-dev - TypeScript development patterns
• lang-python-dev - Python development patterns
• lang-rust-dev - Rust development patterns
• lang-elixir-dev - Elixir development patterns