Skip to content

CLAUDE.md

Latest commit

 

History

History
164 lines (128 loc) · 6.33 KB

CLAUDE.md

File metadata and controls

164 lines (128 loc) · 6.33 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Baboon is a Domain Modeling Language (DML) compiler with schema evolution support. It compiles .baboon domain model files to multiple target languages (Scala, C#, Python, Rust, TypeScript, Kotlin, Java, Dart, Swift) with automatic JSON and UEBA codec generation.

Essential Commands

This project uses mudyla for build orchestration.

Build Commands

# Format code
mdl :fmt

# Build the compiler native executable
mdl :build

# Run the full test suite
mdl :build :test

# Run specific test suites independently:
# - Regular ADT tests
mdl :build :test-gen-regular-adt :test-cs-regular :test-scala-regular :test-rust-regular :test-typescript-regular :test-kotlin-regular :test-kotlin-kmp-regular :test-java-regular :test-dart-regular :test-swift-regular
# - Wrapped ADT tests
mdl :build :test-gen-wrapped-adt :test-cs-wrapped :test-scala-wrapped :test-rust-wrapped :test-typescript-wrapped :test-kotlin-wrapped :test-kotlin-kmp-wrapped :test-java-wrapped :test-dart-wrapped :test-swift-wrapped
# - Manual/compatibility tests
mdl :build :test-gen-manual :test-gen-compat-scala :test-gen-compat-cs :test-gen-compat-rust :test-gen-compat-typescript :test-gen-compat-kotlin :test-gen-compat-kotlin-kmp :test-gen-compat-java :test-gen-compat-dart :test-gen-compat-swift :test-manual-cs :test-manual-scala :test-manual-rust :test-manual-typescript :test-manual-kotlin :test-manual-kotlin-kmp :test-manual-java :test-manual-dart :test-manual-swift

# Run complete build pipeline (format, build, test)
mdl :full-build

# Create distribution packages
mdl :build :mkdist

Direct SBT Commands (for development)

# Compile the project
sbt compile

# Build native executable
sbt GraalVMNativeImage/packageBin

# Clean build
sbt clean compile

# Run all tests
sbt test

# Run specific test
sbt "testOnly *SpecificTestSpec"

Running the Compiler

# Example compilation command
baboon \
  --model-dir ./src/test/resources/baboon/ \
  --meta-write-evolution-json baboon-meta.json \
  --lock-file=./target/baboon.lock \
  :cs \
  --output ./output/cs \
  :scala \
  --output ./output/scala \
  :rust \
  --output ./output/rust \
  :typescript \
  --output ./output/ts \
  :kotlin \
  --output ./output/kotlin \
  :java \
  --output ./output/java \
  :dart \
  --output ./output/dart \
  :swift \
  --output ./output/swift

High-Level Architecture

Core Components

  1. Parser (parser/ package)

    • Parses .baboon files using FastParse
    • Main entry: BaboonParser.scala
    • Produces raw AST representations

  2. Type System (typer/ package)

    • Converts raw AST to typed AST
    • Handles type resolution, inheritance, and validation
    • Key classes: BaboonTyper.scala, TypePasses.scala

  3. Validators (validator/ package)

    • Ensures model consistency
    • Checks evolution compatibility
    • Validates foreign type mappings

  4. Code Generators (translator/ package)

    • csharp/ - C# code generation with advanced deduplication
    • scala/ - Scala code generation
    • python/ - Python code generation
    • rust/ - Rust code generation with native types, serde derive, and custom UEBA binary codecs
    • typescript/ - TypeScript code generation with function-based JSON/UEBA codecs
    • kotlin/ - Kotlin code generation with Jackson JSON codecs and UEBA binary codecs
    • java/ - Java code generation with Jackson JSON codecs and UEBA binary codecs
    • dart/ - Dart code generation with dart:convert JSON codecs and UEBA binary codecs
    • swift/ - Swift code generation with JSONSerialization JSON codecs and UEBA binary codecs
    • Each generator produces source files, codec implementations and conversions from lower versions to higher ones

  5. Runtime Support (src/main/resources/baboon-runtime/)

    • Contains runtime libraries copied to generated code
    • Separate implementations for each target language

Domain Language Features

Baboon files support:

  • Structural inheritance: Using + (union), - (subtraction), ^ (intersection)
  • Type categories: DTOs, ADTs, enums, foreign types, type aliases
  • Collections: Lists, sets, dictionaries, options
  • Annotations: @root (entry points); : derived[json], : derived[ueba] (request codecs)
  • Evolution: Automatic schema migration where possible

Key Design Patterns

  1. Multi-stage Compilation:

    • Parse → Raw AST → Typed AST → Validated Model → Generated Code
    • Each stage uses separate data structures for type safety

  2. Dependency Injection:

    • Uses distage for wiring components
    • Allows easy testing and modularity

  3. Codec Generation:

    • Generates both JSON and custom binary (UEBA) codecs
    • JSON: Circe (Scala), Newtonsoft.Json (C#), serde (Rust), Jackson (Kotlin, Java), dart:convert (Dart), JSONSerialization (Swift), custom (Python, TypeScript)
    • Supports automatic evolution between versions

  4. CLI Design:

    • Multi-modal CLI with language-specific options
    • Uses decline for command parsing

Testing Strategy

  • Unit tests for individual components
  • Integration tests with full compilation cycles
  • Generated code tests in test/cs-stub/, test/sc-stub/, test/py-stub/, test/rs-stub/, test/ts-stub/, test/kt-stub/, test/jv-stub/, test/dt-stub/, and test/sw-stub/
  • Cross-platform compatibility tests in test/conv-test-{cs,sc,py,rs,ts,kt,jv,dt,sw}/ (verifies JSON/UEBA interop across all languages)
  • Evolution tests validating schema migration

Parallel Test Execution: Test actions test-gen-regular-adt and test-gen-wrapped-adt can run in parallel. Each action:

  1. Creates an isolated temporary directory under target/ (test-regular/ or test-wrapped/)
  2. Copies stub projects (excluding generated files and build artifacts) via rsync
  3. Generates code into the isolated directory
  4. Subsequent test actions run in these isolated directories

Important Considerations

  1. Root Types: Only types marked with @root or transitively referenced by roots are included in output
  2. Foreign Types: Require manual codec implementation in target languages
  3. Evolution: Not all schema changes are automatically evolvable
  4. Deduplication: C# generator performs sophisticated deduplication to reduce code size
⚡