Initial commit

ROADMAP.md

@@ -0,0 +1,169 @@
+# Пътна Карта: Clojure/Nim
+
+## Фаза 0: Инфраструктура и Планиране ✅
+
+- [x] Определяне на цели и архитектура
+- [x] Избор на подход (изходен Nim код vs директен C)
+- [x] Създаване на структура на проекта
+- [ ] CI/CD pipeline
+- [ ] Система за тестване
+
+## Фаза 1: Reader (Clojure → Clojure Data Structures)
+
+**Цел:** Правилно парсиране на Clojure синтаксис към Clojure структури от данни.
+
+- [ ] Символи (`sym`, `foo/bar`)
+- [ ] Ключови думи (`:key`, `:ns/key`)
+- [ ] Числа (integers, floats, ratios, big ints)
+- [ ] Низове с escape sequences
+- [ ] Коментари (`;`)
+- [ ] Колекции:
+  - [ ] Списъци `(...)`
+  - [ ] Вектори `[...]`
+  - [ ] Maps `{...}`
+  - [ ] Sets `#{...}`
+- [ ] Цитиране (`'`, `` ` ``, `~`, `~@`, `#`)
+- [ ] Четене на dispatch macros (`#'`, `#_`, `#{}`, etc.)
+- [ ] Reader conditionals (`#?()`)
+- [ ] Метаданни (`^`)
+
+## Фаза 2: Runtime Структури от Данни
+
+**Цел:** Имплементиране на Clojure структурите от данни в Nim.
+
+- [ ] **Persistent Vector** (Hash-mapped trie, като Clojure's HMT)
+- [ ] **Persistent Map** (Hash-mapped trie)
+- [ ] **Persistent Set** (върху Map)
+- [ ] **Linked List** (свързан списък за sequences)
+- [ ] **Lazy Seq**
+- [ ] **Atoms** (STM ще дойде по-късно)
+- [ ] **Keywords** (interned)
+- [ ] **Symbols**
+- [ ] **Vars**
+- [ ] **Namespaces**
+
+## Фаза 3: Макро Система и AST
+
+**Цел:** Clojure макроси, които работят върху Clojure структури.
+
+- [ ] **Clojure AST** представяне в Nim
+- [ ] **Macro expansion engine**
+- [ ] Специални форми:
+  - [ ] `def`
+  - [ ] `fn` / `defn`
+  - [ ] `let` / `letfn`
+  - [ ] `if` / `when` / `cond`
+  - [ ] `do`
+  - [ ] `quote`
+  - [ ] `loop` / `recur`
+  - [ ] `throw` / `try` / `catch` / `finally`
+  - [ ] `var`
+  - [ ] `binding` (dynamic vars)
+- [ ] Core макроси:
+  - [ ] `defmacro`
+  - [ ] `->`, `->>`
+  - [ ] `and`, `or`
+  - [ ] `cond->`, `cond->>`
+  - [ ] `doto`
+  - [ ] `for`, `doseq`
+  - [ ] `lazy-seq`
+
+## Фаза 4: Nim Code Emitter
+
+**Цел:** Транслиране на Clojure AST към Nim код.
+
+- [ ] **Symbol мапинг** (Clojure → Nim naming)
+- [ ] **Type inference** (основно)
+- [ ] **Emitter за специални форми**:
+  - [ ] Функции (`proc` в Nim)
+  - [ ] Променливи (`var` / `let` / `const`)
+  - [ ] Условни изрази (`if` / `case`)
+  - [ ] Цикли
+  - [ ] Изключения (`try` / `except`)
+- [ ] **Interop**:
+  - [ ] Извикване на Nim функции от Clojure
+  - [ ] Извикване на C библиотеки
+  - [ ] FFI механизъм
+- [ ] **Type hints** поддръжка
+
+## Фаза 5: Core Библиотека
+
+**Цел:** Имплементация на Clojure core функции.
+
+### 5.1 Функции за Колекции
+- [ ] `map`, `filter`, `reduce`
+- [ ] `first`, `rest`, `next`, `last`
+- [ ] `conj`, `into`
+- [ ] `assoc`, `dissoc`, `get`, `get-in`
+- [ ] `update`, `update-in`
+- [ ] `keys`, `vals`
+- [ ] `count`, `empty?`, `seq`
+- [ ] `take`, `drop`, `partition`
+- [ ] `concat`, `interleave`
+
+### 5.2 Функции за Низове
+- [ ] `str`, `pr-str`, `println`, `prn`
+- [ ] `subs`, `clojure.string/` namespace
+
+### 5.3 Функции за IO
+- [ ] `slurp`, `spit`
+- [ ] `read-line`
+
+### 5.4 Функции за Мета
+- [ ] `meta`, `with-meta`, `vary-meta`
+- [ ] `type`, `instance?`
+
+## Фаза 6: REPL и Инструменти
+
+**Цел:** Интерактивна среда за разработка.
+
+- [ ] **REPL цикъл** (Read-Eval-Print-Loop)
+- [ ] **Hot reloading** на код
+- [ ] **Error reporting** с Clojure стек тракове
+- [ ] **Auto-completion**
+- [ ] **Doc strings** (`doc` функция)
+- [ ] **Source** (`source` функция)
+- [ ] **AOT компилация**
+
+## Фаза 7: Многонишковост и STM (по-късно)
+
+**Цел:** Clojure's конкурентност модел.
+
+- [ ] **Atoms** (CAS)
+- [ ] **Agents**
+- [ ] **Refs + Software Transactional Memory**
+- [ ] **Futures** / **Promises**
+- [ ] **core.async** (channels, go blocks) — голяма задача
+
+## Фаза 8: Оптимизации и Полиране
+
+- [ ] **Protocol имплементация** (като Clojure protocols)
+- [ ] **Multimethods**
+- [ ] **Records и Types**
+- [ ] **Бързо стартиране** (малък runtime)
+- [ ] **Малък размер на бинарния файл**
+- [ ] **Подобрена производителност** на persistent структурите
+- [ ] **Tree shaking** / Dead code elimination
+
+## Бъдещи Идеи
+
+- **GraalVM нативен образ** алтернатива (Clojure/Nim като lighter alternative)
+- **Babashka-подобен скриптов инструмент**
+- **Nim библиотеки достъпни директно** от Clojure
+- **ClojureScript съвместимост** (споделен код)
+- **LSP/Language Server** за Clojure/Nim
+- **nREPL съвместимост**
+
+---
+
+## Текущ Фокус
+
+Следваща стъпка: **Фаза 1 — Reader**
+
+Ще започнем с имплементация на базов Clojure reader, който може да парсира:
+1. Числа и низове
+2. Символи и keywords
+3. Специални знаци (`'`, `` ` ``, `~`, `@`)
+4. Списъци и вектори
+
+Първият milestone е работещ reader, който може да обработи `(+ 1 2)` и да върне правилна Clojure data structure.