Ahoy! - Educational Language & Transpiler

A tiny, pirate-themed programming language that transpiles to clean JavaScript, featuring a zero-dependency lexer/parser/generator pipeline and VS Code TextMate grammar.

TypeScript
Bun
TextMate Grammar
Shiki
VS Code Extension API

View code

Problem

Compilers and language design are frequently perceived as intimidating academic topics wrapped in heavy tooling (LLVM, ANTLR, complex AST frameworks), making it hard to see how tokens actually become running code.

Solution

Built a clean, zero-dependency transpiler in TypeScript that transforms readable pirate-flavored syntax into standard modern JavaScript, paired with an official VS Code extension and Shiki grammar.

My role

Sole language designer and engineer - designed grammar, wrote the scanner, recursive descent parser, AST generator, CLI, and TextMate syntax highlighting.

Impact

Provides a transparent, end-to-end reference implementation for understanding lexical analysis, syntax trees, and code generation in fewer than 1,000 lines of code.

Challenges

Designing an intuitive grammar with unambiguous operator precedence, building single-source TextMate scopes that work seamlessly across VS Code and Shiki, and keeping generated JavaScript idiomatic and readable.

Screenshots

The problem

Understanding how programming languages actually work is often obscured by large compiler frameworks and bytecode virtual machines. Most introductory resources either stop at basic regex replacement or jump straight into complex compiler-compiler generators.

The goal with Ahoy! was to demonstrate the entire journey of source code from raw text to execution with zero external compiler dependencies.

The approach

Ahoy treats syntax highlighting and language tooling as first-class citizens alongside the compiler itself:

Single Source of Truth: The language specification (SPEC.md) directly guides the recursive descent parser, the VS Code TextMate grammar, and the Shiki web highlighter.
Three-Stage Pipeline:
1. Lexer: Scans characters into structured tokens (keywords like ye be called, identifiers, operators, and comments).
2. Parser: A recursive descent parser that constructs an Abstract Syntax Tree (AST) while preserving operator precedence.
3. Code Generator: Walks the AST nodes and emits formatted, idiomatic JavaScript.
Zero Dependencies: The core transpiler runs natively on Bun and TypeScript without external libraries.

Architecture notes

Source Code (.pirate)
       │
       ▼ [Lexer]         Scans characters into tokens
Token Stream
       │
       ▼ [Parser]        Recursive descent parser builds AST
AST Tree
       │
       ▼ [Generator]     Walks AST and emits clean JavaScript
JavaScript Code (.js)

Developer experience

Beyond the CLI (pirate build and pirate run), the project includes a ready-to-install extension for VS Code and Cursor that enables syntax highlighting and automatic comment toggling (Cmd + / with ~), plus Shiki integration for documentation sites.