elo: Instructions file for Claude Code

Claude Development Guide for Elo

This document provides instructions for AI assistants (like Claude) working on the Elo compiler project.

Project Overview

Elo is a small expression language that compiles to three target languages:

• Ruby: Server-side scripting
• JavaScript: Client-side execution
• PostgreSQL SQL: Database queries

The compiler translates Elo expressions into semantically equivalent code in each target language.

Design principles

Following the vision, design and implementation choices MUST target a language that stays simple, well-designed, portable and safe, in that order. We SHOULD always restrict Elo's powerfullness if a wanted feature leads to a violation of those principles.

CRITICAL when adding a language construct or stdlib function, you MUST also document it in README (no details) and on website (with example).

Architecture

Elo currently has the following components :

• A parser (src/parser.ts)
• AST types and factory (src/ast.ts)
• Type system (src/types.ts)
• Intermediate Representation with type inference (src/ir.ts, src/transform.ts)
• Standard library abstraction for type-based dispatch (src/stdlib.ts)
• One compiler per target language (src/compilers/*.ts)
• A binary command (bin/eloc and src/cli.ts)
• A try-elo website to demonstrate Elo (web/)

Compilation Pipeline

1. Parse: Source → AST (parser.ts)
2. Transform: AST → Typed IR (transform.ts) - infers types and rewrites operators as function calls
3. Emit: IR → Target code (compilers/*.ts) - uses StdLib for type-based dispatch

Test-Driven Development

Elo is developped in TDD. We have three levels of testing :

• npm run test:unit : checks the behavior of core and utility functions
• npm run test:integration : checks expected compilation output from sources
• npm run test:acceptance : checks expected semantics against ruby, node and psql

CRITICAL : the three levels of tests MUST be maintained ; all tests MUST PASS at all times.