bara-lang/PLAN.md

Clojure/Nim — Test Suite Compliance Plan

Current Status: 171/233 (73%)

Component	Pass	Total	%
clojure.string	8	8	100%
clojure.core	163	225	73%
Total	171	233	73%

What's Working (171 tests passing)

Core Infrastructure

• Reader: Clojure syntax parsing, #? reader conditionals, #uuid"...", #"regex", char literals (\newline, \space, etc.), N/M/ratio suffixes, comma as whitespace
• Emitter: Macro expansion, scope tracking, iterative worklist form processing, metadata stripping, namespace-qualified macro resolution
• Macros: deftest, is, testing, are, thrown?, when-var-exists, and, or, when, when-not, cond, for, doseq, dotimes, ->, ->>, some->, some->>, cond->, cond->>, doto, as->, defmacro, comment
• HAMT Data Structures: Persistent Vector, Map, Set — all native Nim, zero Java dependency
• Runtime: 100+ functions implemented (arithmetic, collections, predicates, I/O, agents, channels)

clojure.string

All 8 tests pass: blank?, capitalize, ends-with?, escape, lower-case, reverse, starts-with?, upper-case

Remaining Failures (62 tests)

Priority 1 — Missing Advanced Features (~15 tests)

These need new emitter/compiler support:

• defprotocol — protocol definitions
• defrecord — record types
• deftype — custom types
• defmulti / defmethod — multimethods
• instance? — type checking against protocols/records

Affected tests: ancestors, derive, descendants, dissoc, ifn_qmark, not_eq, parents, underive, bound_fn, bound_fn_star, var_qmark, case

Priority 2 — Reader Preprocessing (~10 tests)

The test_single.py preprocessor uses regex to replace #{} sets with @[], which breaks when sets contain nested }. Need proper set literal parsing or native #{} support in reader.

Affected tests: add_watch, conj, conj_bang, hash_set, reduce, remove_watch

Priority 3 — are_arity (5 tests)

#?@ splice inside are forms doesn't match arity correctly. The preprocessor's extract_default doesn't handle all #?@ patterns.

Affected tests: bit_and, bit_and_not, bit_flip, bit_set, bit_shift_left

Priority 4 — Missing Runtime Functions (~10 tests)

Simple stubs needed:

• aclone, int-array — Java array interop stubs
• rseq — reverse sequence
• empty — empty collection (different from empty?)
• delay — lazy evaluation
• create-ns — namespace creation
• sorted-map-by — sorted map with comparator

Priority 5 — Type Mismatches (~9 tests)

Nim type errors from edge cases in macro expansion:

• compare, cons, drop_last, fnil, get, shuffle, vec, update, taps

Priority 6 — Other (~13 tests)

• bigint — integer overflow on big numbers
• constantly, atom, transient — closing quote errors in generated Nim
• merge — syntax error in generated code
• portability — unquote-splicing edge case
• random_uuid, uuid_qmark, parse_uuid — UUID dispatch reader issue
• realized_qmark, when_first, when_let — indentation issues

Architecture Notes

Compilation Pipeline

Clojure source → Reader (AST) → Macro expansion → Emitter (Nim code) → Nim compiler → C compiler → native binary

Key Files

• src/reader.nim — Clojure parser (455 lines)
• src/emitter.nim — Nim code generator (1443 lines)
• src/macros.nim — Macro system (527 lines)
• lib/cljnim_runtime.nim — Runtime library (1896 lines)
• lib/cljnim_pvec.nim — HAMT Persistent Vector
• lib/cljnim_pmap.nim — HAMT Persistent Map
• test_single.py — Test runner for clojure-test-suite

What Makes This Different from Other Clojure Dialects

• No JVM — compiles to native via Nim → C
• Native HAMT — persistent data structures written in Nim, not Java
• Zero dependencies — no GraalVM, no JVM, no Google Closure Compiler
• Multi-target — native, shared library, WASM, JavaScript

Next Steps to Reach 90%+

1. Implement defprotocol / defrecord / deftype emitter support (~15 tests)
2. Add native #{} set literal support in reader (~10 tests)
3. Fix #?@ splice handling in are preprocessor (~5 tests)
4. Add remaining runtime function stubs (~10 tests)
5. Fix Nim type edge cases in emitter (~5 tests)

Estimated effort: 2-3 focused sessions to reach 90%+ (210+/233).