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: (file/read "path"), (file/write "path" "content"), (file/append "path" "content")
• File operations: (file/ls "dir"), (file/exists? "path")
• Git operations: (git/status), (git/commit "msg"), (git/push)
• Git operations: (git/diff), (git/log)
• nREPL protocol compatibility (JSON over TCP, --tcp PORT)
• Tool-call format for AI framework integration

Phase 5: Persistent Data Structures ✅ (Complete)

• Persistent Vector (Hash Array Mapped Trie, 32-way branching)
• Persistent Map (HAMT) — pmapAssoc, pmapDissoc, pmapGet in O(log₃₂ n)
• Persistent Set — backed by HAMT map, conj/disj/contains?/get
• conj, assoc, dissoc, get, get-in
• nth, first, rest, last, count on persistent collections
• Transients for batch mutations
• conj!, assoc!, persistent!

Phase 6: Clojure Core Library ✅ (Complete)

• range (0/1/2/3 args), 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 [lib :as alias]))
• Module caching for faster REPL startup
• Dependency resolution (deps.edn, Git deps to .deps/)

Phase 8: Self-Hosted REPL ✅

• Compile forms in memory (tree-walking interpreter, <1ms eval)
• Fast REPL startup (~0.02ms per eval vs 1133ms compiled)
• Hot code reloading (def/defn update env immediately)

Phase 9: Concurrency ✅

• Atoms (compare-and-swap)
• Agents (send, await, deref — sync dispatch in interpreter)
• core.async channels (chan, >!, <!, close!, go — interpreter-first)

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 — interpreter path handles most cases in <0.1ms now)
• ffi/interop examples fail — sin symbol not found (Nim module import issue, pre-existing)

Recent Bug Fixes (2026-05-08)

• Fixed: quot/rem — added cljQuot/cljRem to runtime + interpreter support
• Fixed: rem — interpreter and compiled path both now handle (rem n d)
• Cleanup: removed unused processAgentActions proc, unused sequtils import in repl.nim