From 0ba94881beda48df3c1b4be1803cdc7dd2e62425 Mon Sep 17 00:00:00 2001 From: dimgigov Date: Sat, 9 May 2026 18:40:30 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20add=20compliance=20plan=20=E2=80=94=201?= =?UTF-8?q?71/233=20(73%),=20roadmap=20to=2090%+?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PLAN.md | 174 +++++++++++++++++++++++++------------------------------- 1 file changed, 78 insertions(+), 96 deletions(-) diff --git a/PLAN.md b/PLAN.md index d0ec4e0..a4337e8 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,114 +1,96 @@ -# План за Clojure/Nim — Ден на Победата Edition 🎖️ +# Clojure/Nim — Test Suite Compliance Plan -## Направено (8-9 май 2026) +## Current Status: 171/233 (73%) -### Ядро (Compiler Core) -- ✅ `loop`/`recur` вече работи в компилиран код (критичен бъг оправен) -- ✅ `compile-lib` режим — експортирани функции за library generation -- ✅ 20+ компилаторни предупреждения изчистени -- ✅ `make check` — build + test + всички примери +| Component | Pass | Total | % | +|---|---|---|---| +| clojure.string | 8 | 8 | 100% | +| clojure.core | 163 | 225 | 73% | +| **Total** | **171** | **233** | **73%** | -### AI Интеграция (Phase AI-1 до AI-4) — 9 май 2026 -- ✅ **AI-Assisted Errors** — error cache, Reader/Emitter/Nim error coverage -- ✅ **AI Code Generation** — `(ai/generate "...")` в REPL, `:ai` команда, JSON REPL `ai-generate` -- ✅ **AI Optimization Hints** — `(ai/optimize "...")`, `buildOptimizationPrompt` -- ✅ **AI Debugging** — `(ai/debug expr)`, `buildDebugPrompt`, JSON REPL `ai-debug` +## What's Working (171 tests passing) -### Тестове -- ✅ `tests/test_macros.nim` — 30 теста за макроси -- ✅ `tests/test_eval.nim` — +30 нови теста (math, collections, agents, channels) -- ✅ `tests/test_emitter.nim` — +3 теста за loop/recur +### 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) -### Документация -- ✅ README.md, ROADMAP.bg.md, ARCHITECTURE.md синхронизирани -- ✅ LICENSE файл добавен +### clojure.string +All 8 tests pass: `blank?`, `capitalize`, `ends-with?`, `escape`, `lower-case`, `reverse`, `starts-with?`, `upper-case` -### Нови Target-и -- ✅ `experiments/web-target/` — Clojure → Nim → JS -- ✅ `experiments/native-lib/` — Clojure → Nim → C shared library -- ✅ `experiments/wasm-target/` — WASM skeleton +## 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 -## План за 9 май — AI Интеграция (DeepSeek / Xiaomi MiMo) +Affected tests: `ancestors`, `derive`, `descendants`, `dissoc`, `ifn_qmark`, `not_eq`, `parents`, `underive`, `bound_fn`, `bound_fn_star`, `var_qmark`, `case` -### Phase AI-1: AI-Assisted Error Messages ✅ -**Цел:** Когато `cljnim compile` fail-не, AI анализира грешката и дава обяснение на български/английски. +### 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. -**Имплементация:** -- ✅ `src/ai_assist.nim` — Error cache за чести грешки (in-memory, 50 записа, TTL 1 час) -- ✅ ReaderError/EmitterError coverage — AI обяснения за грешки на всички нива (reader, emitter, Nim compiler) -- ✅ Интеграция с DeepSeek API (вече беше) -- ✅ Cache за чести грешки +Affected tests: `add_watch`, `conj`, `conj_bang`, `hash_set`, `reduce`, `remove_watch` -### Phase AI-2: AI Code Generation в REPL ✅ -**Цел:** Генериране на Clojure функции от описание. +### 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. -```clojure -user> (ai/generate "функция за бързо сортиране на вектор") -" (defn quicksort [v] ...)" +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 ``` -**Имплементация:** -- ✅ `ai/generate` builtin в eval.nim (interpreter) -- ✅ `:ai ` в human REPL (вече беше) -- ✅ `ai-generate` op в JSON REPL +### 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 -### Phase AI-3: AI Optimization Hints ✅ -**Цел:** Компилаторът използва AI за избор на алгоритми. +### 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 -```clojure -user> (ai/optimize "(defn sum [nums] (reduce + nums))") -"Consider using transients for large collections..." -``` +## Next Steps to Reach 90%+ -**Имплементация:** -- ✅ `ai/optimize` builtin в eval.nim -- ✅ `:optimize ` в human REPL -- ✅ `ai-optimize` op в JSON REPL -- ✅ `buildOptimizationPrompt` в ai_assist.nim +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) -### Phase AI-4: AI Debugging ✅ -**Цел:** REPL команди за анализ на runtime поведение. - -```clojure -user> (ai/debug (factorial 5)) -🤖 AI Analysis: -- factorial(5) = 120 (коректно) -- Време: O(n) рекурсия -``` - -**Имплементация:** -- ✅ `ai/debug` special form в eval.nim (raw expression pre-evaluation) -- ✅ `:debug ` в human REPL -- ✅ `ai-debug` op в JSON REPL -- ✅ `buildDebugPrompt` в ai_assist.nim - ---- - -## Технически детайли за AI интеграция - -### DeepSeek API -- Endpoint: `https://api.deepseek.com/v1/chat/completions` -- Model: `deepseek-chat` или `deepseek-coder` -- Български език: ✅ поддържа - -### Xiaomi MiMo -- Endpoint: зависи от deployment -- Може да се self-hostва - -### Архитектура -``` -User Input → Clojure/Nim → Error/Request → AI Module → DeepSeek/MiMo API - ↓ - Cached Response → User -``` - ---- - -## Следващи стъпки (ядро) - -1. ✅ **Обединяване на CljVal типовете** — `src/types.nim` + `lib/cljnim_runtime.nim` + `src/runtime.nim` + `lib/cljnim_runtime_js.nim` — всички 4 файла вече имат идентичен CljKind enum (15 стойности) -2. ✅ **`try`/`catch`/`finally`** — пълна имплементация в emitter — exception type вече се използва, binding e cljMap с `:type` и `:message` -3. ✅ **`swap!`/`reset!`** в interpreter-а — вече беше имплементирано -4. ✅ **Reader edge cases** — `-.5` negative floats, scientific notation `1e5`/`1.5e-3`, unterminated string tests, negative float tests — 13 нови теста +Estimated effort: 2-3 focused sessions to reach 90%+ (210+/233).