bara-lang/docs/ROADMAP.md

Development Roadmap

Phase 0: Compiler Core ✅

• Clojure Reader (EDN parser)
• Reader supports: lists (), vectors [], maps {}, strings, keywords, symbols, numbers, booleans, nil
• Reader supports: quote ', syntax-quote `, unquote ~, unquote-splicing ~@
• Reader supports: comments ;, read-all
• AST → Nim Emitter
• CLI (compile, run, read, repl)
• Special forms: def, defn, fn, let, if, do, quote
• Special forms: when, cond
• Arithmetic operators: +, -, *, /
• Comparison operators: =, not=, not, <, >, <=, >=
• Core functions: println, map, filter, reduce
• Runtime type system: CljVal with nil, bool, int, float, string, keyword, symbol, list, vector, map, fn, atom

Phase 1: Macro System ✅

• macroexpand, macroexpand-1
• syntax-quote, unquote, unquote-splicing
• gensym
• defmacro (user-defined macros)
• Built-in macros: ->, ->>, and, or, when, when-not, cond
• Built-in macros: cond->, cond->>, doto, as->, some->, some->>
• Built-in macros: for, doseq, dotimes
• Built-in macros: when-let, if-let
• Built-in macros: comment, assert, with-open

Phase 2: REPL & Tooling ✅

• Human REPL (:help, :defs, :clear, :ns, :quit)
• JSON REPL (--json) with structured I/O
• Batch evaluation (eval-batch)
• Structured errors (type, message, form, line)
• Session persistence for def/defn definitions

Phase 3: Nim Interop ✅

• Call Nim functions: (nim/math/sin x), (nim/strutils/toUpper s)
• C FFI via Nim importc

Phase 4: AI-Native Tooling 🔄

• File operations from REPL: (file/read "path"), (file/write "path" "content")
• Git operations from REPL: (git/status), (git/commit "msg"), (git/push)
• nREPL protocol compatibility
• Tool-call format for AI framework integration

Phase 5: Persistent Data Structures

• Persistent Vector (Hash Array Mapped Trie)
• Persistent Map (HAMT)
• Persistent Set
• conj, assoc, dissoc, get, get-in
• nth, first, rest, last, count on persistent collections
• Transients for batch mutations

Phase 6: Clojure Core Library

• range, repeat, cycle, iterate
• take, drop, partition, interleave, concat
• str, pr-str, println, prn
• slurp, spit, read-line
• meta, with-meta, vary-meta
• type, instance?, satisfies?

Phase 7: Project Compilation

• Compile entire projects (not just single files)
• Namespace system (ns, require, use)
• Module caching for faster REPL startup
• Dependency resolution

Phase 8: Self-Hosted REPL

• Compile forms in memory (no temp files)
• Fast REPL startup (< 100ms)
• Hot code reloading

Phase 9: Concurrency

• Atoms (compare-and-swap)
• Agents
• core.async channels (simplified)

Known Issues

• ->> threading macro with nested map/reduce requires proper macro expansion context
• REPL definitions are re-compiled from scratch on each evaluation (slow but correct)
• No true persistent data structures yet (runtime uses Nim seq/tables)