melange-bindings-against-tsc

Validate Melange bindings against TypeScript definitions

An OCaml binary tool that validates Melange bindings by type-checking the compiled JavaScript output against original TypeScript type definitions using tsserver.

🎯 Overview

This tool helps ensure that Melange FFI bindings correctly represent TypeScript APIs by:

1. Parsing TypeScript .d.ts definition files
2. Generating Melange bindings (.ml/.mli files) with @genType annotations
3. Compiling the bindings via melc (Melange compiler)
4. Validating the generated TypeScript types against the original definitions using tsserver
5. Reporting any type mismatches or binding errors

✨ Features

• ✅ Automatic validation - Compare generated types with original TypeScript definitions
• 🔄 TypeScript AST parsing - Uses TypeScript's own compiler API via Node.js
• 🎨 Beautiful reports - Console, JSON, and HTML output formats
• 🚀 genType integration - Leverages genType for bidirectional type generation
• 📦 DefinitelyTyped support (planned) - Pull type definitions from @types packages

📋 Prerequisites

• OCaml >= 5.1.0
• Dune >= 3.12
• Node.js >= 18 (for TypeScript parsing and tsserver)
• TypeScript (install globally: npm install -g typescript)
• Melange (forked version with genType support - coming soon)

🚀 Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/melange-bindings-against-tsc.git
cd melange-bindings-against-tsc

# Install dependencies
opam install . --deps-only

# Build
dune build

# Install
dune install

Via OPAM (coming soon)

opam install melange-bindings-against-tsc

📖 Usage

Basic Usage

Validate a single TypeScript definition file:

melange-bindings-against-tsc path/to/types.d.ts

With Options

# Specify output directory for generated bindings
melange-bindings-against-tsc types.d.ts --output-dir ./generated

# JSON output format
melange-bindings-against-tsc types.d.ts --format json

# HTML report
melange-bindings-against-tsc types.d.ts --format html > report.html

# Verbose logging
melange-bindings-against-tsc types.d.ts --verbose

Future: Pull from DefinitelyTyped

# Pull and validate React types
melange-bindings-against-tsc --pull react

# Pull specific version
melange-bindings-against-tsc --pull react@18.2.0

🏗️ Project Structure

melange-bindings-against-tsc/
├── bin/                       # CLI entry point
├── lib/
│   ├── typescript/            # TypeScript parsing and tsserver integration
│   ├── melange/               # Binding generation and type mapping
│   ├── validator/             # Validation orchestration and reporting
│   ├── fetcher/               # DefinitelyTyped integration (future)
│   └── utils/                 # Shared utilities
├── test/
│   ├── fixtures/              # Test TypeScript definition files
│   └── unit/                  # Unit tests
└── examples/                  # Example usage

🔧 How It Works

1. TypeScript Parsing

(* Parse .d.ts file into OCaml AST *)
let%lwt module_ = Typescript.Parser.parse_file "lodash.d.ts" in
(* Returns: { declarations; imports; file_path } *)

2. Binding Generation

(* Generate Melange bindings *)
let config = {
  module_name = "lodash";
  output_dir = "./_melange_bindings";
  use_gentype = true;
} in
let%lwt output = Melange.Generator.generate_bindings module_ config in

Example output (lodash.ml):

external map : 'a array -> ('a -> 'b) -> 'b array = "map"
  [@@mel.module "lodash"] [@@genType]

external filter : 'a array -> ('a -> bool) -> 'a array = "filter"
  [@@mel.module "lodash"] [@@genType]

3. Compilation & Validation

(* Compile with melc - generates .js and .gen.ts files *)
(* Start tsserver and validate types *)
let%lwt result = Validator.validate module_ config in

(* Generate report *)
let report = Report.generate Console result in
print_endline report

🎨 Example Output

🔍 Validating lodash.d.ts...

✅ map - PASS
   Expected: <T, U>(array: T[], fn: (item: T) => U) => U[]
   Generated: <T, U>(array: T[], fn: (item: T) => U) => U[]

❌ filter - FAIL
   Expected: <T>(array: T[], predicate: (item: T) => boolean) => T[]
   Generated: <T>(array: T[], predicate: (item: T) => bool) => T[]
   Error: Type mismatch - 'bool' should be 'boolean'

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary: 1/2 passed (50%)

🛠️ Development

Building

# Build the project
dune build

# Run in development mode
dune exec melange-bindings-against-tsc -- test/fixtures/simple.d.ts --verbose

# Run tests
dune runtest

# Watch mode
dune build --watch

Testing

# Run all tests
dune test

# Run specific test
dune exec test/test_parser.exe

Documentation

# Generate API documentation
dune build @doc

# View documentation
open _build/default/_doc/_html/index.html

📚 Architecture

Type Mapping

TypeScript types are mapped to OCaml/Melange types:

TypeScript	OCaml/Melange
number	int / float
string	string
boolean	bool
T[]	'a array
T | null	'a option
{ x: T }	{ x : t }
(x: T) => U	t -> u
Promise<T>	t Lwt.t

Melange Fork with genType

This project requires a fork of Melange with integrated genType support (following the conservative approach from issue #916):

• Port genType to Melange's typed tree
• Add Dune rules for post-compilation genType processing
• Generate .gen.ts files alongside .js output

🗺️ Roadmap

• TypeScript AST parsing via Node.js
• Basic type mapping (TS → OCaml)
• Melange binding generation
• CLI with cmdliner
• Complete JSON to OCaml AST conversion
• tsserver integration and type comparison
• Melange fork with genType
• Comprehensive test suite
• DefinitelyTyped integration (--pull command)
• Watch mode for continuous validation
• VS Code extension

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Development Setup

# Install development dependencies
opam install --deps-only --with-test --with-doc .

# Install pre-commit hooks
# (coming soon)

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Melange - OCaml to JavaScript compiler
• genType - Original genType implementation
• TypeScript - TypeScript compiler and tsserver
• DefinitelyTyped - TypeScript type definitions

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Status: 🚧 Early development - Core features implemented, validation pipeline in progress