Lesma AGENTS.md

AGENTS.md — Lesma project guide for AI agents

This file gives future agents (and humans) a quick reference for how the Lesma compiler works, how to build it, and how to validate changes.

---

What Lesma is

Lesma is a compiled, statically typed, imperative, object-oriented language that targets LLVM. The compiler is C++23 and uses LLVM for code generation, optimization, JIT, and object-file emission. The standard library is written in Lesma (.les files in src/stdlib/).

---

Project layout

• src/ — Compiler and stdlib
  • src/cli/main.cpp — CLI entry point (when LESMA_BUILD_CLI is on).
  • src/liblesma/ — Core library:
    • Common/ — Utils, logging, errors (LesmaError, CodegenError in Backend/CodegenError.h).
    • Frontend/ — Lexer, Parser (tokens → AST).
    • AST/ — AST node definitions and visitor interface.
    • Token/ — Token types and Token class.
    • Symbol/ — Symbol table, Type, Value, TypeUtils.
    • Backend/ — Codegen (AST → LLVM IR), MangleUtils, CodegenTypeUtils, linking/JIT.
  • src/stdlib/ — Lesma standard library (e.g. base.les, math.les, time.les).
  • src/lsp/ — lesma-lsp (when LESMA_BUILD_LSP is ON). Advertises UTF-8 position encoding (PositionEncodingKind::UTF8); clients must send Position.character as UTF-8 code units (bytes) from the line start. Enables vcpkg feature lsp (libgit2, minimal: pcre2 only, no HTTPS/SSH) for workspace-wide .les discovery in Git work trees without shelling out to git.
• tests/lesma/success/ — Programs that must compile and run (exit 0).
• tests/lesma/failure/ — Programs that must be rejected (expected to fail).
• scripts/run_tests.sh — Runs the compiler on all success/failure cases (run + compile for each).
• benchmark/ — Google Benchmark targets plus the benchmark suite integration harness (benchmark/SuiteWallClock.cpp).

---

Wall-clock benchmark (benchmark suite)