jolt/.dirge/skills/jolt-compiler/SKILL.md

description
Jolt compiler architecture and implementation plan

Jolt Compiler

Two-phase source-to-source compiler: Clojure forms → annotated AST → Janet source → Janet bytecode.

Architecture

Clojure source → Reader → raw AST
                            ↓
                   analyze-form (classify symbols, produce :op AST)
                            ↓
                   emit* dispatch (generate Janet source string)
                            ↓
                   Janet compile → bytecode

Follows CLJS cljs.analyzer / cljs.compiler pattern.

Key decisions

• Target: Janet source text (fed to Janet's compile), not direct bytecode. Simpler, debuggable, portable across Janet versions.
• Mode gating: Opt-in per context via :compile? flag on init. eval-string still interprets unless opted in.
• Caching: In-memory bytecode cache in context first. Disk persistence (.jimage files) as follow-up.

AST ops (CLJS subset + Jolt-specific)

Core: const, var, local, binding, if, do, let, loop, recur, fn, fn-method, def, invoke, quote, try, throw, set!, new, host-field, host-call

Jolt-specific: deftype, defmulti, defmethod, syntax-quote

File layout

File	Purpose
src/jolt/compiler.janet	analyze-form, emit* dispatch, compile-form, symbol classifier
src/jolt/loader.janet	load-ns, reload-ns, in-memory bytecode cache
test/compiler-test.janet	Round-trip: compile-form → Janet eval → assert

Modified files:

• evaluator.janet — add compiler fast-path for def/defn/defmacro when :compile? set
• types.janet — add :compiled-cache table to context
• api.janet — expose compile-string, load-ns, compile-file; init gets :compile? flag
• reader.janet — no change
• core.janet — no change

Emit target advantages

Both input and output are parenthesized prefix syntax, so many forms pass through almost unchanged:

Clojure:  (defn f [x] (+ x 1))
AST:      {:op :def :name "f" :init {:op :fn :methods [...]}}
Janet:    (defn f [x] (+ x 1))          ← nearly identical

Main work:

• Symbol resolution (Clojure's clojure.core/+ → Janet's core-+)
• Truthiness wrapping (nil/false are falsey in Clojure, Janet only nil)
• Special form mapping (loop*/recur → Janet loop + explicit recur vars)
• Vars → Janet table lookups

Implementation phases

Phase	What	Deliverable
1	compiler.janet — analyze-form skeleton + emit* for const, do, if, let, fn, def, invoke	Basic forms compile and run
2	Symbol classifier — resolve locals/vars/core at analyze time	No runtime resolve-sym in compiled code
3	loader.janet + api.janet wiring — :compile? flag, load-ns, caching	File-based namespace loading works
4	Macro integration — expand at analyze time via interpreter	Macros work in compiled code
5	Remaining ops: loop/recur, try/throw, quote, syntax-quote, set!, deftype, .	Full language coverage
6	Tests + benchmarks	Correctness + speedup measurement

Pitfalls

• Janet compile produces bytecode tied to Janet version — source-to-source avoids this
• CLJS analyzer is ~5000 lines; Jolt's can be simpler because emit target is s-expressions
• Symbol resolution must happen at analyze time, not runtime, for compiled code
• Macro expansion still uses interpreter at analyze time — macros are not AOT-compiled